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 (debug, info, warning, error, critical, off). Defaults to info.

Commands:
  raycast
  lookup
  flatten
  summary
  fbx

For command 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:

Usage 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 representation 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 Lookup Tool

The lookup tool can be used to extract information related to various truth indexes (material, optical property and geometry) from a compiled scene file.

The scene indexing can change if changes are made to the scene, especially if those changes involve adding or removing materials or geometry. Hence, some of the indexes in the examples below might not correspond to the current version of the scene being used.

Below is the command-line help for this tool:

Usage for the lookup tool.

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

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

Options:
  -h/--help
	Display this help and exit.
  --material_index uint
	The material index to lookup.
  --property_index uint
	The optical property index to lookup.
  --geometry_index uint
	The base geometry index to lookup.
  --instance_index uint
	The instance index to lookup.
  --master_index uint
	The master table index to lookup.
  -o/--output string
	The output file.

The default for this tool is to write to standard output (e.g., the screen, terminal, etc.). The optional --output option can be used to route the output to a supplied filename.

When the lookup tool output is a JSON document, the jq command-line JSON parsing tool can be employed to make the JSON more human readable.

Example Material Lookup Usage

A "material index" lookup is useful when looking to identify the material associated with the index stored in the Dominant Material Index truth product. In the following example, the Foxbat scene was simulated and the dominant material index for the extended grassy area was 9:

Lookup of the "grass" material index in the Foxbat scene.

$ scene_tool lookup --material_index=9 foxbat_day.scene.hdf
# Material property index = 9
# Type = Surface
# Name = 'grass (id = 10)'
# Optical property index  = 58
# Temperature model index = 8

The output includes the queried index, the material type, the material name and label (ID) and the index pair for the optical property and temperature model.

Example Property Lookup Usage

In the previous example usage, the "grass" material pointed to an optical property with an index of 58. To find out about that optical property, the "optical property index" lookup option can be employed:

Lookup of the "grass" optical property index in the Foxbat scene.

$ scene_tool lookup --property_index=58 foxbat_day.scene.hdf
# Optical property index = 58
# Type = Pure Optical Properties Map
# Reflectance index   = 1
# Transmittance index = 0

The Type indicates that the optical property associated with the grass is a "Pure Optical Properties Map", which is what a standard DIRSIG texture map (and some other optical property map types) get translated into.

The other use for the optical property lookup tool is to extract the spectral curve associated with the Dominant Optical Property Index truth product. For the Foxbat scene, a random grass pixel yielded an optical property index of 45, which can be looked up similarly:

Lookup of the "grass" optical property index in the Foxbat scene.

$ scene_tool lookup --property_index=45 --output prop_info.txt demo.scene.hdf
$ more prop_info.txt
# Optical property index = 45
# Type = Diffuse Reflectance
# Reflectance index   = 43
# Transmittance index = 0
#
# Reflectance data
0.350 0.021627
0.351 0.021627
0.352 0.021627
0.353 0.021627
0.354 0.021627
...
[lines deleted for documentation purposes]
...
2.545 0.243726
2.546 0.243245
2.547 0.242764
2.548 0.242283
2.549 0.241802
2.550 0.24132

For this case, the material type is Diffuse Reflectance, and the spectral reflectance curve data is output.

The spectral sampling (range and resolution) of the spectral data is dictated by the spectral coverage of the scene when it was compiled.

The output file option (-o or --output) is handy if you want to capture the output of the tool to a file for plotting.

Example Geometry Index Lookup Usage

The geometry index truth product can be used to lookup the base geometry object at a given location.

Lookup of geometry index 9 in the Foxbat scene.

$ scene_tool lookup --geometry_index 9 foxbat_day.scene.hdf | jq
[
  {
    "geometryType": "FacetizedObject",
    "isBase": true,
    "isLeaf": false,
    "masterTableIndex": 20,
    "originalFilename": "/Users/dirsig/foxbat/geometry/objects/aircraft.gdb"
  }
]

Example Instance Index Lookup Usage

The instance index truth product can be used to lookup the base geometry object at a given location.

Lookup of instance index 24 in the Foxbat scene.

$ scene_tool lookup --instance_index 24 foxbat_day.scene.hdf | jq
[
  {
    "geometryType": "StaticInstance",
    "isBase": false,
    "isLeaf": true,
    "masterTableIndex": 24,
    "materialLut": [ 2, 14, 6, 7, 8 ],
    "tags": [
      "fighters"
    ],
    "transform": [
      -2.220446049250313e-16, 1, 0,
      -15.850000381469727, -1, -2.220446049250313e-16,
      0, -63, 0,
      0, 1, 0
    ]
  },
  {
    "geometryType": "FacetizedObject",
    "isBase": true,
    "isLeaf": false,
    "masterTableIndex": 20,
    "originalFilename": "/Users/dirsig/foxbat/geometry/objects/aircraft.gdb"
  }
]

In this example, instance index 24 corresponds to a static instance as indicated by the StaticInstance type. In contrast, instance index 58 corresponds to a dynamic instance:

$ scene_tool lookup --instance_index 58 foxbat_day.scene.hdf | jq
[
  {
    "geometryType": "FlexMotionInstance",
    "isBase": false,
    "isLeaf": true,
    "masterTableIndex": 58,
    "materialLut": [ 2, 14, 6, 7, 8 ]
  },
  {
    "geometryType": "FacetizedObject",
    "isBase": true,
    "isLeaf": false,
    "masterTableIndex": 20,
    "originalFilename": "/Users/dirsig/foxbat/geometry/objects/aircraft.gdb"
  }
]

Example Master Table Index Lookup Usage

All of the base geometry and instances can be accessed through the "master table" in the scene HDF file. In many of the tools available in this program you will see a "master table index" provided

Lookup of instance index 24 in the Foxbat scene.

$ scene_tool lookup --instance_index 24 foxbat_day.scene.hdf | jq
[
  {
    "geometryType": "StaticInstance",
    "isBase": false,
    "isLeaf": true,
    "masterTableIndex": 24,
    "materialLut": [ 2, 14, 6, 7, 8 ],
    "tags": [
      "fighters"
    ],
    "transform": [
      -2.220446049250313e-16, 1, 0,
      -15.850000381469727, -1, -2.220446049250313e-16,
      0, -63, 0,
      0, 1, 0
    ]
  },
  {
    "geometryType": "FacetizedObject",
    "isBase": true,
    "isLeaf": false,
    "masterTableIndex": 20,
    "originalFilename": "/Users/dirsig/foxbat/geometry/objects/aircraft.gdb"
  }
]

The Raycast Tool

The raycast tool can be used to trace a user-supplied ray into a scene HDF and return intersection information associated with the ray. The user must provide the scene ENU origin and direction for the ray to be traced. The optional time argument can be used for scenes with dynamic motion (default relative ray time is 0 seconds).

Below is the command-line help for this tool:

Usage for the raycast tool.

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

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

Options:
  -h/--help
	Display this help and exit.
  --origin float float float(required!)
	The scene ENU ray origin.
  --direction float float float(required!)
	The scene ENU ray direction.
  --time float
	The relative ray time (seconds).

The output is a JSON array document sorted by hit distance along the ray. Each JSON object contains the following information:

hitDistance: The distance from the origin to the intersection in meters.
hitNormal: The scene ENU normal vector at the intersection.
hitPosition: The scene ENU position at the intersection.
geometryIndex: The geometry index associated with the intersection. The corresponding base geometry can be resolved using the lookup tool.
instanceIndex: The instance index associated with the intersection. The corresponding instance and base geometry can be resolved using the lookup tool.
masterTableIndex: The master table index associated with the intersection. The corresponding geometry can be resolved using the lookup tool.

Example Usage

The primary usage is to generate a JSON document containing intersection information for geometry along the ray:

JSON output of the raycast tool.

$ scene_tool raycast --origin 41 70 5000 --direction 0 0 -1 foxbat_day.scene.hdf | jq
[
  {
    "geometryIndex": 3,
    "hitDistance": 4990.4755859375,
    "hitNormal": [ 0, 0, 1 ],
    "hitPosition": [ 41, 70, 9.5244140625 ],
    "instanceIndex": 5,
    "masterTableIndex": 9
  },
  {
    "geometryIndex": 3,
    "hitDistance": 4991,
    "hitNormal": [ 0, 0, -1 ],
    "hitPosition": [ 41, 70, 9 ],
    "instanceIndex": 5,
    "masterTableIndex": 9
  },
  {
    "geometryIndex": 0,
    "hitDistance": 5000,
    "hitNormal": [ 0, 0, 1 ],
    "hitPosition": [ 41, 70, 0 ],
    "instanceIndex": 0,
    "masterTableIndex": 1
  }
]

In this example, the ray intersects the top roof of the hangar, the ceiling of the hangar (separate geometry 50 cm below the roof) and then the ground under the hangar.

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 summary of the scene:

JSON output of the summary tool.

$ 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 Z-Probe Tool

The zprobe tool can be used for "poking" a compiled scene HDF at various horizontal locations to determine the vertical height at that location. This is useful for figuring out how to determine Z for an object that you want to place onto a scene at a given XY location:

Usage for the zprobe tool.

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

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

Options:
  -h/--help
	Display this help and exit.
  -i/--input_filename string(required!)
	The input scene XY file.
  --input_frame string
	The input coordinate frame [default = 'enu'].
  -o/--output_filename string(required!)
	The output scene XYZ file.
  --output_coords string
	The output coordinate frame [default = 'enu'].
  --z_origin float
	The Z to probe from [default = 10000 m]).

The input filename is expected to be a two column, ASCII/Text file containing a single horizontal (2D) point for each line. The coordinate frame for the input point can be either Scene ENU or Geodetic. This can be changed with the --input_frame option being set to either enu or geodetic The default is enu. The output filename contains the 3D points for each of the input 2D points. Similarly, the coordinate frame for the output can be set via the --output_frame option, with the default set to enu.

The Z is determined using a simple vertical ray trace that is started from the input XY location and from a height defined by the --z_origin option. This height defaults to 10000 meters and should only need to be changed if the scene is significantly offset from the origin.

Example Usage

In the simplest usage, the user will probe with Scene ENU XY locations to determine the Scene ENU Z location:

$ cat example_xy.txt
1761.611552 3358.382688
2143.895627 1850.597637
5.038513 -2517.220380
2021.088302 1303.361434

$ scene_tool zprobe -i example_xy.txt -o example_xyz.txt example.scene.hdf
# Scene origin = 38.80556041179794, -120.42239788798767, 7.043014976067189e-10
Probing Z for XY = [1761.6116,3358.3826]
Probing Z for XY = [2143.8955,1850.5977]
Probing Z for XY = [5.038513,-2517.2205]
Probing Z for XY = [2021.0883,1303.3615]

$ cat example_xyz.txt
1761.61 3358.38 1743.91
2143.9 1850.6 1719.32
5.03851 -2517.22 1287.63
2021.09 1303.36 1744.22

The tool can also be used with geodetic (latitude and longitude) inputs to get Scene ENU outputs. In this example, we probe a single lat/lon that we know is very close to the Scene ENU origin.

$ cat example_latlon.txt
38.80556041179794 -120.42239788798767

$ scene_tool zprobe -i example_latlon.txt --input_frame geodetic -o example_xyz.txt example.scene.hdf
# Scene origin = 38.80556041179794, -120.42239788798767, 7.043014976067189e-10
Probing Z for lat/lon = [38.80556,-120.4224] -> XY = [-0.3075154,0.07258793]

$ cat example_xyz.txt
-0.307515 0.0725879 1519.14

Any permutation of input and output frames is supported.