DIRSIG renders scenes consisting of 3D facetized objects. Early versions stored the scene in a single Geometric Database file that contained the entire scene. Among other limitations, this approach meant that duplicated geometry was physically duplicated in the GDB file (inefficent disk usage) and in memory during run-time (inefficient memory usage). The current version of DIRSIG uses one of more Object Database files that assembles a set of geometric objects into a scene. The following sections describe the different types of objects available and the syntax to combine them.

Facetized Geometry

Facetized geometry can be added via the OBJECT section. A facetized object is defined by:

  • The base geometry file

  • The units employed in the geometry file

  • A list of instance insertions for that base object

The following example will be referenced in the detailed description that follows:

DIRSIG_ODB = 1.0

OBJECT {
    GDB_FILENAME = building.gdb
    UNITS = INCHES
    INSTANCES {
        INFO = 8415.00, 3610.00, 15.24, 1.00, 1.00, 1.00, 0.00, 0.00, -90.0
        INFO = 8410.00, 3620.00, 15.24, 1.00, 1.00, 1.00, 0.00, 0.00, +90.0
    }
}

OBJECT {
    OBJ_FILENAME = streetlight.obj
    UNITS = METERS
    INSTANCES {
        INFO = 15850.00, 2300.00, 15.24, 1.00, 1.00, 1.00, 0.00, 0.00, 0.0
    }
}

OBJECT {
    GDB_FILENAME = house.gdb
    UNITS = METERS
    INSTANCES {
        INFO = -4.08519 0 -0.0143796 1621.31 -0.0279271 7.79807e-08 2.10345 -1506.47 7.48304e-10 2.91028 -5.63618e-08 -0.295091 0 0 0 1
    }
}

OBJECT {
    GDB_FILENAME = car.gdb
    UNITS = METERS
    INSTANCES {
        INFO = car_path.mov
    }
}

Base Geometry

The base geometry can be supplied by either the GDB_FILENAME or the OBJ_FILENAME variable, which specifies the name of either a DIRSIG Geometric Database file or an Alias/Wavefront OBJ file. The second object in the previous example specified an Alias/Wavefront OBJ file, and the remaining objects used native DIRSIG Geometric Database format files.

Units

The UNITS variable is used to specify the units employed in the base geometry. This allows DIRSIG to know that a distance of 1 in the geometry file is to be interpreted as either METERS, CENTIMETERS, FEET or INCHES.

Instances

For each object in the object database, a list of instances is also provided. Each instance of the object defines the rotation and scale of the given object at a given location.

Note The object database makes several assumptions about the model geometry provided for each object. The translation of the object is applied to the origin of the object model. In most cases, it is desired that the user modify the object geometry so that the model is centered about the X and Y origin and the bottom of the model (smallest Z value) is at the Z origin. In this configuration, it is very easy to place the object within the scene. The rotation angles are also relative to the origin of the object space. If the object is not "centered" in the described fashion, the rotation of the object may yield unexpected results.

Each instance requires a minimal amount of system resources so a high fidelity object can be used many times in a scene with very little incremental resource requirements over that of a single instance of the object. This subsection consists of a series of INFO entries that define a the location and orientation of the base geometry. There are 3 possible options available:

Static Instances via XYZ Triplets

This specification is the most common and the format is recognized by containing exactly 9 fields in the comma separated string assigned to the INFO. These 9 fields are (in order) the X, Y, Z location (in Scene ENU coordinates), the X, Y, Z scale factors and the X, Y, Z rotation angles (in degrees). Internally these translation, scale and rotation axis triplets are used to create an affine transform:

DIRSIG_ODB = 1.0

OBJECT {
    GDB_FILENAME = car.gdb
    UNITS = METERS
    INSTANCES {
        INFO = +5, +5, 0, 2, 2, 2, 0, 0, 0
    }
}
Important The order of operations is (1) the object is scaled, (2) the object is rotated and (3) the object is translated.
Important A scale factor of 0 in any dimension is considered an error.
Important The rotation order for the angles is always Z, then Y, then X.

Static Instances via Affine Transform

The following example shows how to directly provide an affine transform to describe the instance. This description method is commonly used when we import instance information from scene building tools such as CityEngine. The format is recognized by containing exactly 16 fields in the comma separated string assigned to the INFO. These fields represent the values of the 4x4 matrix defining an affine transform of the base object. The 4x4 matrix is "unrolled" into these 16 fields using a row-major order:

DIRSIG_ODB = 1.0

OBJECT {
    GDB_FILENAME = car.gdb
    UNITS = METERS
    INSTANCES {
        INFO = +2, 0, 0, +5, 0, +2, 0, +5, 0, 0, +2, 0, 0, 0, 0, 1
    }
}

Dynamic Instances via Delta Motion

The following example shows an object to be dynamically positioned, scaled and rotated as a function of time using the Delta motion model:

DIRSIG_ODB = 1.0

OBJECT {
    GDB_FILENAME = car.gdb
    UNITS = METERS
    INSTANCES {
        INFO = car.mov
    }
}

Instanced Object Databases

In addition to using a single object as the base geometry, the user can also specify another Object Database file. This allows the user to create meta-objects that can be instanced. For example, the user might want to create a helicopter with a spinning rotor. This meta-object could be created as an ODB file using an OBJECT for the helicopter body and a second OBJECT for the rotor. The body object would have a single, fixed instance and the rotor object would have a single, dynamic instance that rotates the blades. This ODB would now represent a complete helicopter with spinning rotors (see the example below):

DIRSIG_ODB = 1.0

OBJECT {
    GDB_FILENAME = helicopter_body.gdb
    UNITS = METERS
    INSTANCES {
        INFO = 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0
    }
}

OBJECT {
    GDB_FILENAME = helicopter_rotor.gdb
    UNITS = METERS
    INSTANCES {
        INFO = spin.mov
    }
}

To instance this meta-object multiple times, the user can specify the meta-object via the ODB_FILENAME variable (see the example below):

DIRSIG_ODB = 1.0

OBJECT {
    ODB_FILENAME = helicopter.odb
    UNITS = METERS
    INSTANCES {
        INFO = 8415.0, 3610.0, 15.0, 1.0, 1.0, 1.0, 0.0, 0.0, -90.0
        INFO = 8410.0, 3620.0, 15.0, 1.0, 1.0, 1.0, 0.0, 0.0, +90.0
    }
}

Primitive Geometry

This geometry file also supports a set of primitive objects that are built-in to the DIRSIG model. These objects have the benefit that they usually employ analytical functions to represent the geometry rather than quantize the surface with polygons. For example, the "sphere" object is perfectly smooth.

Note These objects do not support instancing like the facetized objects. If you want more than one object, create an additional entry. However, the GLIST file (the modern version of this file) does support translation, scaling and rotation of primitive objects.

Each object also supports an optional TEMPERATURE tag that can override the temperature (in Kelvin) that would otherwise be computed by the temperature solver for the material assigned to the object.

Volume objects (boxes, spheres, etc.) support a CONCENTRATION tag that defines the concentration of the bulk (volume) material assigned to the object. Without this concentration, material configurations that depend on a concentration (e.g. absorption) with generate run-time errors.

Plane (Uniform)

A simple, plane that extends infinitely in the XY plane can be defined with a given material ID and at a given Z. The following example creates a plane with material ID = 10 at Z = 5 meters:

GROUND_PLANE {
    ANCHOR = 0.0, 0.0, 5.0
    MATERIAL_ID = 10
}
Note For a simple plane, the X,Y values of the ANCHOR are not used.

Plane (Checkerboard)

A checkerboarded version of the plane is created by adding the ADD_CHECKS section. Within that section, you must define the second material ID and the size of the checkerboard blocks.

GROUND_PLANE {
    ANCHOR = 0.0, 0.0, 15.0
    MATERIAL_ID = 10
    ADD_CHECKS {
        MATERIAL_ID = 12
        WIDTH = 2.0
    }
}
Note For a checkerboarded plane, the X,Y values of the ANCHOR locate the center of the checkerboard pattern and can be used to shift the pattern if desired.
plane1
Figure 1. A checkerboarded plane object

Sphere

A sphere object can be placed based on user-supplied location of the center and will be sized with a user-supplied radius. A sphere has only one material associated with it. The following example shows how to place a sphere with a material ID of 4, and a radius of 4 meters at 0, 0, 8:

SPHERE {
   RADIUS = 4.0
   CENTER = 0, 0, 8.0
   MATERIAL_IDS = 4
}
sphere1
Figure 2. A sphere object

Box

An axis-aligned box object can be placed based on the location of the lower extent and upper extent. A box has only one material associated with it. The following example shows how to create a box that is 2 x 8 x 1 meters centered at 0, 0, 0.5:

BOX {
    LOWER_EXTENT = -1.0, -4.0, 0.0
    UPPER_EXTENT = +1.0, +4.0, 1.0
    MATERIAL_IDS = 4
}
box1
Figure 3. A box object

Disk

A disk object can be created that occupies a given XY plane at a user-defined Z value. A disk has only a single material associated with it. The following example shows how to place a 10 centimeter radius disk with material ID = 4 at 20, -10, 4:

DISK {
    CENTER = 20.0, -10.0, 4.0
    RADIUS = 0.10
    MATERIAL_ID = 4
}
Note The disk object supports an optional NORMAL variable that can be used to orient the object. For example, NORMAL = 0.0, 0.707, 0.707
disk1
Figure 4. A disk object

Secchi Disk

The Secchi disk object is a variant of the simple disk object, and is intended to reproduce an object commonly used in the estimation of water clarity. The disk object has two high contrast materials (usually white and black paint) that are painted in a 2x2 checkerboard pattern. The following example is the same as the simple disk, except that a second material ID is provided to indicate the second material used.

SECCHI_DISK {
    CENTER = 20.0, -10.0, 4.0
    RADIUS = 0.10
    MATERIAL_IDS = 4, 1000
}
secchi1
Figure 5. A Secchi disk object

Cylinder

A cylinder can be created with a user-defined radius, and can optionally include geometry for either end. The POINT_A and POINT_B variables define the end points of the cylinder, and therefore allow the user to orient the cylinder in any direction. The CAP_A and CAP_B variables control the modeling of the endcap geometry.

The following example shows how to create a vertically oriented cylinder that is 20 meters tall with a radius of 5 meters:

CYLINDER {
    POINT_A = -12, -12, 0.0
    POINT_B = -12, -12, 20.0
    RADIUS = 5.0
    CAP_A = TRUE
    CAP_B = TRUE
    MATERIAL_ID = 4
}
cylinder2
Figure 6. A cylinder object with end caps

The CAP_A and CAP_B variables control if the end caps for the two ends are modeled.

cylinder3
Figure 7. A cylinder object without one end cap
cylinder4
Figure 8. A cylinder object without both end caps