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

Overview

The help for the scene_tool utility.
$ scene_tool help
Usage: scene_tool [options] command
DIRSIG Scene scanning and interaction tool

Options:
  -h, --help           Displays this help.
  -v, --version        Displays version information.
  --log_level <level>  Sets the minimum logging level. Values are: debug, info,
                       warning, error, critical, off

Arguments:
  command              Available tools:
                         flatten
                         help
                         summary
                         traceback

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.

Warning 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:

The help message for the "flatten" tool.
$ scene_tool help flatten
Usage: scene_tool flatten [options] filename


Options:
  -o, --output <filename>   Output filename (.obj)
  -p, --precision <digits>  Set 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 <seconds>      Set the relative time. Only relevant if there are
                            dynamic instances.
  --subset_min <X,Y,Z>      Set the subset minimum coordinate.
  --subset_max <X,Y,Z>      Set the subset maximum coordinate.

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

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:

The help message for the "summary" tool.
$ scene_tool help summary
Usage: scene_tool summary [options] filename

Options:
  -o, --output <filename>  Output filename

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

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:

$ scene_tool help traceback
Usage: scene_tool traceback [options] filename

Options:
  --index <number>  The index to trace.

Arguments:
  filename          The input filename (.hdf)

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
Note The indexes used in the examples above may not match your version of the Foxbat scene.