This is the manual for the command-line object_tool program that is bundled with DIRSIG and can be used to perform operations on object geometry files in either the GDB or OBJ format.

Overview

The tool can be used to query information about the size of the geometric and materials that it requires. The tool can also be used to perform basic geometric operations including translate, scale or rotate the geometry. More advanced options including adding vertex normals and adding UV texture coordinates to OBJ are also supported.

The tool has a command-line interface so that it can be used to process large sets of files as part of a scene construction workflow. The tool’s interface allows the user to specify a sequence of operations that are performed on the geometry.

Table 1. Supported input file formats
Format Extension Notes Links

DIRSIG GDB

.gdb

http://www.dirsig.org/docs/new/gdb.html

Alias/Wavefront OBJ

.obj

http://www.dirsig.org/docs/new/obj.html

AFACET

.afacet

Collapses hierarchy to single level

https://doi.org/10.1117/12.2304460

ModelMan FACET

.facet
Table 2. Supported output file formats
Format Extension Notes

DIRSIG GDB

.gdb

Supports facet temperatures

Alias/WavefrontOBJ

.obj

Basic Interface

Input Filename and Format

The basic interface to the tool starts with the user supplying the name of the input geometry file via the --input_filename option. Currently supported input file formats will be auto-detected based on the file extension (for example a file ending with the .obj extension is assumed to be an OBJ format file):

$ object_tool --input_filename=truck.obj ...

The user can optionally specify the input file format with the --input_format option:

$ object_tool --input_filename=truck.obj --input_format=obj ...
Tip The --input_format option is useful for when the input geometry file does not end with a recognized extension.

Output Filename

If the program performs operations on the input geometry file, then an output filename should be supplied via the --output_filename option:

$ object_tool --input_filename=truck.obj ... --output_filename=truck.obj
Note If the program is only producing geometry or material summaries of the input geometry, then an output filename is not required.

Common Operations

Minimal Summary

If the tool is run with just an input filename, then a minimal summary of the input geometry file will be printed. The details are different depending on if a GDB or OBJ file is supplied:

$ object_tool --input_filename=aircraft.gdb
Reading input GDB file ...
Reading in geometry file: aircraft.gdb
    Part count = 84
    Invalid/Total facet count = 0/6762
    Shared/Total vertex count = 17146/23016
$ object_tool --input_filename=StorageShed.obj
Reading input OBJ file ...
Reading in geometry file: StorageShed.obj
    Part count   = 1
    Facet count  = 14567
    Vertex count = 12806

Geometry Summary

A more detailed summary of the geometry can be output by supplying the --geometry option:

$ object_tool --input_filename=aircraft.gdb --geometry
Reading input GDB file ...
Reading in geometry file: aircraft.gdb
    Part count = 84
    Invalid/Total facet count = 0/6762
    Shared/Total vertex count = 17146/23016

Geometry summary tool:
    Triangle count = 9492
    Vertex count = 5870
    Minimum = -10.77, -6.715, 0
    Maximum = 10.77, 6.715, 5.35657
    Size = 21.54 x 13.43 x 5.35657 [m]

Material Summary

A summary of the materials required by the geometry file (including the material IDs and how many polygon/facets each ID is assigned to) can be output by supplying the --materials option:

$ object_tool --input_filename=aircraft.gdb --materials
Reading input GDB file ...
Reading in geometry file: aircraft.gdb
    Part count = 84
    Invalid/Total facet count = 0/6762
    Shared/Total vertex count = 17146/23016

Material summary tool:
    1 (assigned to 4244 facets)
    7 (assigned to 3200 facets)
    8 (assigned to 20 facets)
    9 (assigned to 120 facets)
    27 (assigned to 1908 facets)

Quick Geometry and Material Summary

If the program is run with just the name of a file (without the --input_filename syntax) then you get a geometry, group and material summary:

$ object_tool aircraft.gdb
Reading input GDB file ...
Reading in geometry file: aircraft.gdb
    Part count = 84
    Invalid/Total facet count = 0/6762
    Shared/Total vertex count = 17146/23016

Geometry summary tool:
    Triangle count = 9492
    Vertex count = 5870
    Minimum = -10.77, -6.715, 0
    Maximum = 10.77, 6.715, 5.35657
    Size = 21.54 x 13.43 x 5.35657 [m]

Group summary tool:
    FOXBAT_AERIALL_ATTS (assigned to 154 facets)
    FOXBAT_AERIALR_ATTS (assigned to 154 facets)
    FOXBAT_BODY1_ATTS (assigned to 200 facets)
    .
    .
    FOXBAT_WINGFIN_2_ATTS (assigned to 156 facets)
    FOXBAT_WINGL_ATTS (assigned to 40 facets)
    FOXBAT_WINGR_ATTS (assigned to 40 facets)

Material summary tool:
    1 (assigned to 4244 facets)
    7 (assigned to 3200 facets)
    8 (assigned to 20 facets)
    9 (assigned to 120 facets)
    27 (assigned to 1908 facets)

This is the same output as you would get with a more verbose set of options:

$ object_tool --input_filename=aircraft.gdb --geometry --groups --materials

Basic Geometry Modifications

The tool can also perform basic modifications to the geometry. These operations can be useful in automating a workflow that moves geometry out of a 3D geometry authoring application and into DIRSIG.

Keep in mind that the user can provide a sequence of operations via the order that options are specified on the command line. For example, the following syntax:

$ object_tool --input_filename=original.obj --operation1 --operation2 --output_filename=final.obj

will open the file original.obj, run operation #1 on that geometry, then run operator #2 on the geometry resulting from operation #1, and then save the result to final.obj. An arbitrary number operations can be specified in the command-line.

Important The order that operations are performed matters. A translation followed by a rotation produces a different result then the same rotation followed by the same translation.
Tip The geometry summary (--geometry) operation can be injected within a long set of geometry operations multiple times to observe how the geometry changes.

Translation

An object can be translated in any of the three dimensions using the --translatex, --translatey and --translatez options. For example, to translate the geometry in the X dimension by 10 units, the following syntax can be used:

$ object_tool --input_filename=input.obj --translatex=10 --output_filename=output.obj
Note The translation amount is in the same units as the geometry. Although we encourage users to produce final models that are in meters, a model output from a CAD environment might be initially in inches. Therefore any translation operations performed on that geometry before it is scaled from inches to meters will be in inches.

Auto-Centering

Since it is handy to have the origin of the geometry to be at the average XY and minimum Z of an object, the --autocenter option will automatically compute the translation required to produce this state and apply it.

Scaling

Scaling geometry is a very common operation when a change of units is performed. The scale factor is multiplicative and a single factor can be applied to all axes using the --scale operator. For example, to scale an object from inches to meters a scale factor of 0.0254 should be used:

$ object_tool --input_filename=car_inches.obj --scale=0.0254 --output_filename=car_meters.obj

Alternately, there might be a need to scale an object in a single dimension. For that task, the the --scalex, --scaley and --scalez operators can be employed. For example, to make an object 10x bigger in the Z dimension only, the following syntax can be used:

$ object_tool --input_filename=box_short.obj --scalez=10 --output_filename=box_tall.obj

Rotation

An object can be rotated about any of the three basis axes using the --rotatex, --rotatey and --rotatez options.

Note All rotations are right-handed.

For example, to rotate the geometry about the X axis by 45 units, the following syntax can be used:

$ object_tool --input_filename=input.obj --rotatex=45 --output_filename=output.obj
Important Remember that the order of a rotation sequences is important and performing a Z rotation after an X rotation can produce a different result than if the order is flipped.
Tip One of the ways to change from the "+Y is up" to the "+Z is up" convention expected by DIRSIG is to rotate the geometry about the X axis by -90 degrees.

Mirroring Axes

The user can mirror the object geometry across any given axis using the --mirrorx, --mirrory and --mirrorz options. This operator is useful in situations with geometry that is derived from image data, such as a terrain that was built from a Digital Elevation Model (DEM). In those situations, the difference in the location of Y = 0 between image coordinate conventions (upper-left) and Cartesian coordinate conventions (lower-left) can sometimes produce geometry that appears to be flipped or mirrored in the Y axis.

$ object_tool --input_filename=input.obj --mirrory --output_filename=output.obj
Note The mirroring operation is essentially a sign flip. Hence, any coordinate in the axis being mirrored is multiplied by -1.

Swapping Axes

The user can swap any two axes in a model. For example, it is not uncommon for 3D models to use a "+Y is up" convention, but DIRSIG expects a "+Z is up" convention. The user can swap the Y and Z axes to address this using the following syntax:

$ object_tool --input_filename=car_y_up.obj --swap=Y,Z --output_filename=car_z_up.obj
Important This operation purges any vertex normals associated with the geometry. If you want to restore the vertex normals after this operation, the use the --addvertexnormals option or consider using a rotation operation.

Flipping Normals

In some situations you will encounter a geometry model that uses a left-handed normal convention rather than the common right-handed convention that DIRSIG assumes. In that situation, all the of surface normals will point "inward" rather than "outward". The user can choose to flip all the normals in a given piece of geometry using the --flipnormals option.

Advanced Modifications

Adding Vertex Normals

Vertex normals allow for vertex normal interpolation, which can produce the illusion of continuous curvature across surfaces that have quantized curvature due to being composed of a finite number of polygons (facets). The --addvertexnormals tool will compute vertex normals by computing the average normal of all the polygons (facets) that share a geometry vertex:

$ object_tool --input_filename=car.obj --addvertexnormals --output_filename=car_vn.obj

In some situations, you do not want to use the average surface normal at a vertex. For example, along hard edges (like the edges and corners of a box) the vertex normals will make box faces appear to be severely curved when it is unlikely that was the intended result. To address these cases, the --addvertexnormals option can also take a maximum angle (in degrees) that will result in the vertex normal being shared among polygons. For example, it would be uncommon to want to use vertex normals that are greater than 20 degrees from the geometric normal:

$ object_tool --input_filename=car.obj --addvertexnormals=20 --output_filename=car_vn.obj

Adding Texture Coordinates

Advanced UV texture coordinate creation and image mapping must be performed in an advanced 3D authoring tool. However, simple UV texture coordinates can be added to some objects by this tool if they are primarily 2D in the XY plane. Such is the case of most terrains, which usually have a much larger extent in the XY dimension than in the Z dimension. The tool will create a UV coordinate system for all geometry vertexes in the XY plane based on an axis aligned coordinate system that starts at X0, Y0 and extends to X1,Y1. For example, consider a 1 km x 2 km terrain that is centered about the origin. It would have a lower-left XY coordinate of -500,-1000 and an upper-right coordinate of +500,+1000:

$ object_tool --input_filename=terrain.obj --maptexture=-500,-1000,500,1000 --output_filename=terrain_uv.obj

Mirror Texture Coordinates

The --flipu and --flipv operators allow the user to mirror or flip a given UV texture coordinate system in an object such that the new coordinate is 1 minus the original coordinate. For example, the new u would be 1-u.

Common Usage Examples

Changing Units

To change the units of an object to meters, then multiplicative scaling is required. The following list of common unit conversions can be used:

  • Inches to meters: 0.0254

  • Feet to meters: 0.3048

  • Millimeters to meters: 0.001

  • Centimeters to meters: 0.010

$ object_tool --input_filename=car_feet.obj --scale=0.3048 --output_filename=car_meters.obj

Converting from +Y up to +Z up

To convert an object from the "+Y is up" to the expected "+Z is up" convention, the geometry can be rotated about the X axis by -90 degrees:

$ object_tool --input_filename=car_y_up.obj --rotatex=-90 --output_filename=car_z_up.obj

An alternative method is to swap the Y and Z axis. However, that must then be followed by a "mirror" operation on the Y axis:

$ object_tool --input_filename=car_y_up.obj --swap=yz --mirrory --output_filename=car_z_up.obj
Note The "swap and mirror" combination might be faster on very large objects than the "rotate" option decribed previously.

Converting from OBJ to GDB

To convert from an Alias OBJ file to a DIRSIG GDB file, simply use the input and output filenames to specify the desired format. For example:

$ object_tool --input_filename=bmw_328i.obj --output_filename=bmw_328i.gdb
Important The usemtl entries in the OBJ will be used to set the material IDs in the GDB file.

Please note the following about using the GDB format instead to OBJ file format:

  • The GDB file format does not support vertex normals, so the option to have vertex normal interpolation would be eliminated.

  • The GDB file format does not support texture vertexes (UV coordinates), so the option to employ UV mapping would be eliminated.

  • However, the GDB file format allows you to specify temperatures on a per-facet basis.

Converting from GDB to OBJ

To convert from a DIRSIG GDB file to an Alias OBJ file from, simply use the input and output filenames to specify the desired format. For example:

$ object_tool --input_filename=bmw_328i.gdb --output_filename=bmw_328i.obj

The usemtl entries in the target OBJ file will be assigned the DIRSIG material IDs from the source GDB file. Since the source GDB file does not contain vertex normals or texture (UV) coordinates, you might consider using the options to add vertex normals and add texture coordinates.