The scene_tool Manual

The scene_tool utility program allows the user to extract information from a DIRSIG scene HDF file generated by the scene2hdf utility.

Overview

Usage for the scene_tool utility.

$ scene_tool -h
Usage: scene_tool [options] <command> ...

DIRSIG Scene scanning and interaction tool

Options:
  -h/--help
	Display this help and exit.
  -v/--version
	Display build and version info and exit.
  --log_level string
	Sets the minimum logging level. Values are: debug, info, warning, error, critical, off

Commands:
  traceback
  flatten
  summary
  fbx

For subcommand help: scene_tool <command> -h

The FBX Tool

The fbx tool will will take the entire scene captured in the scene HDF file and output it to a single FBX file. This is useful for visualizing an entire scene that was assembled from a complex hierarchy of geometry. Since the FBX format does support instancing of geometry, the resulting FBX file retains most of the individual geometry components of the scene.

Below is the command-line help for this tool:

Usgae for the fbx tool.

$ scene_tool fbx -h
Usage: scene_tool ... fbx [options] filename+

Positional Arguments:
  filename
	The input filename(s) (.hdf)

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename (.fbx)
  -s/--start_time float
	Set the relative start time in seconds. Only relevant if there are dynamic instances.
  -d/--duration float
	Set the duration in seconds. Only relevant if there are dynamic instances.

Example Usage

The most common usage is to create a single FBX file from the scene:

Outputting a FBX file for a scene.

$ scene_tool fbx --output foxbat.fbx foxbat.scene.hdf

If the scene contains moving geometry, then the state of the scene at a specific time can be extracted using the --start_time option. This time is the relative time in seconds:

Outputting a FBX file for a scene at a specific time.

$ scene_tool fbx --start_time 12.4 --output foxbat.fbx foxbat.scene.hdf

If you want the FBX to include the scene motion (as animation layers), then include the --duration with the start time.

Outputting a FBX file for a scene with the first 30 seconds of motion.

$ scene_tool fbx --start_time 0.0 --duration 30.0 --output foxbat.fbx foxbat.scene.hdf

The Flatten Tool

The flatten tool will take the entire scene captured in the scene HDF file and output it to a single Alias/Wavefront OBJ file. This is useful for visualizing an entire scene that was assembled from a complex hierarchy of geometry. Since the OBJ format does not support instancing of geometry the resulting OBJ file is single "flattened" facetized representaton of the scene.

A large and complex scene might produce an OBJ file that is very large (many gigabytes) and which some 3D geometry tools might have a hard time displaying.

Below is the command-line help for this tool:

Usage for the flatten tool.

$ scene_tool flatten -h
Usage: scene_tool ... flatten [options] filenames+

Positional Arguments:
  filenames
	The input filename(s) (.hdf)

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename (.obj)
  -p/--precision int
	The precision in decimal places.
  -b/--bound_only
	Only output bounding boxes instead of full facet objects.
  -x/--show_transform
	Print the transform of each instance as a comment in the OBJ.
  -g/--groups
	Emit shading groups in the OBJ.
  -t/--time float
	The relative time in seconds. Only relevant if there are dynamic instances.
  --subset_min float float float
	The subset bound minimum coordinate.
  --subset_max float float float
	The subset bound maximum coordinate.

Example Usage

The most common usage is to create a single OBJ file from the scene:

Outputting an OBJ file for a modest sized scene.

$ scene_tool flatten --output foxbat.obj foxbat.scene.hdf

If the scene is very large and complex, then the instanced objects in the scene can be output as bounding boxes via the --bound_only option rather than facetized objects:

Outputting an OBJ file of bounding boxes for a larger sized scene.

$ scene_tool flatten --bound_only --output megascene1.obj tile_1_2_3_4_5.scene.hdf

If the scene contains moving geometry, then the state of the scene at a specific time can be extracted using the --time option. This time is the relative time in seconds:

Outputting an OBJ file for a scene at a specific time.

$ scene_tool flatten --time 12.4 --output foxbat.obj foxbat.scene.hdf

The Summary Tool

The summary tool produces a small JSON document containing information about the scene, including the scene meta-data (name, authors, description, etc.), geographic origin, size, bounding box and any tags. This summary document is useful for checking the history and features of a scene HDF file. Below is the command-line help for this tool:

Usage for the summary tool.

$ scene_tool summary -h
Usage: scene_tool ... summary [options] filenames+

Positional Arguments:
  filenames
	The input filename(s) (.hdf)

Options:
  -h/--help
	Display this help and exit.
  -o/--output string
	The output filename (.json), default stdout.

Example Usage

The primary usage is to generate the JSON document:

$ scene_tool summary foxbat_day.scene.hdf
{
  "foxbat_day.scene.hdf": {
    "authors": [
      "Joseph Sirianni, Robert Rose and Mike Platt."
    ],
    "boxMax": [
      799.8418579101563,
      2200.0,
      36.583309173583984
    ],
    "boxMin": [
      -919.8418579101563,
      -969.8418579101563,
      -0.007275000214576721
    ],
    "description": "This scene was created in 1994. It features an airfield featuring several MIG-25 (aka \"Foxbat\") fighter jets. This day variant does not include the user-defined sources.",
    "generator": "scene2hdf",
    "md5Hash": "074f4f002c152f3692551e816b5cbb5b",
    "name": "Foxbat, Day",
    "origin": {
      "altitude": -2.8179105715508967e-09,
      "latitude": 43.119998931884766,
      "longitude": -78.44999694824219
    },
    "size": [
      1719.6837158203125,
      3169.841796875
    ],
    "tags": [
      "active",
      "aircraft",
      "cal",
      "choppers",
      "fighters",
      "helicopters",
      "ka27",
      "radar",
      "russian"
    ]
  }
}

The Traceback Tool

The traceback tool is used to find out information for a given instance in a scene. The most common usage of this tool is when using the instance index truth collector and the instance report. The index provided by that collector can be used in the JSON instance report to fetch indexes that can be linked to data in the input scene HDF file. Below is the command-line help for this tool:

Usage for the traceback tool.

$ scene_tool traceback -h
Usage: scene_tool ... traceback [options] filename

Positional Arguments:
  filename (required!)
	The input filename (.hdf)

Options:
  -h/--help
	Display this help and exit.
  -i/--index uint(required!)
	The master table index to trace.

Example Usage

The most common usage of this tool is in combination with various geometry index truth products (sceneindex, geometryindex and instanceindex) and the instance report produced by DIRSIG at run time. The HDF Base Index or HDF Leaf Index from the instance report can be provided to the --index command-line to extract more information about either the base geometry or a specific instance.

Consider the following entry from an instance report of the Foxbat scene:

Example JSON entry from the DIRSIG instance report.

  {
    "Filename": "/Users/dirsig/foxbat/geometry/objects/aircraft.gdb",
    "Geometry Index": 9,
    "HDF Base Index": 23,
    "HDF Leaf Index": 27,
    "Instance Index": 15,
    "Scene Index": 1
  },

You can extract the information about this instance using the HDF "leaf" index value of 27:

Extracting information about a static instance from a scene.

$ scene_tool traceback --index 27 foxbat_day.scene.hdf
Index = 27
  Type = StaticInstance (Leaf)
  Tags = fighters
  Transform = [-0.000000, 1.000000, 0.000000, -15.850000, -1.000000, -0.000000, 0.000000, -63.000000, 0.000000, 0.000000, 1.000000, 0.000000]
  Material LUT = [2, 14, 6, 7, 8]
Index = 23
  Type = FacetizedObject (Base)
  Original Filename = /Users/dirsig/foxbat/geometry/objects/aircraft.gdb

Note that it includes information about the instance including tags, the material lookup table (LUT) and the static instance transform. It automatically includes information about the base geometry (index 23). Information about the base geometry can be accessed directly using the HDF base index:

$ scene_tool traceback --index 23 foxbat_day.scene.hdf
Index = 23
  Type = FacetizedObject (Base)
  Original Filename = /Users/dirsig/foxbat/geometry/objects/aircraft.gdb

The HDF "leaf" index for a dynamic instance (in this case, the plane that is landing on the runway in the Foxbat scene), will yield slightly different information about the instance, but the same base geometry information as the static instances of the same object:

Extracting information about a dynamic instance from a scene.

$ scene_tool traceback --index 61 foxbat_day.scene.hdf
Index = 61
  Type = FlexMotionInstance (Leaf)
  Material LUT = [2, 14, 6, 7, 8]
Index = 23
  Type = FacetizedObject (Base)
  Original Filename = /Users/dirsig/foxbat/geometry/objects/aircraft.gdb

The indexes used in the examples above may not match your version of the Foxbat scene.