The scene_tool
utility program allows the user to extract information
from a DIRSIG scene HDF file generated by the scene2hdf
utility.
Overview
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:
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:
$ 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:
$ 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.
$ 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:
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:
$ 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:
$ 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:
$ 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:
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:
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:
{
"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
:
$ 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:
$ 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. |