Introduction

The concept of a material bundle is intended to streamline the experience of reusing materials between scenes. By encapsulating all information about a material into one file, the intention is that the user can create a library of high-quality materials that can be used as building blocks to lower the overhead cost of constructing a scene. The mat_bundler program is a key component of this workflow as one of the main avenues to creating a material bundle.

In its current form, mat_bundler will create a material bundle from a DIRSIG4-era material file (.mat) via the build command. In these files, there a number of MATERIAL_ENTRY blocks, each defining a material. Each material has a unique identifier, defined by the ID tag. In its default invocation, mat_bundler will attempt to create a material bundle for each MATERIAL_ENTRY in the given .mat file.

mat_bundler can also be used to examine existing material bundles, via the inspect command. This will produce a brief summary report of the material bundle with the bundle’s metadata and some high-level information about the main material in the bundle.

Default Usage.
$ mat_bundler build path/to/file.mat

This usage of mat_bundler will create a number of material bundles in the current directory, each with the name $ID.mat.hdf, where $ID is the value of the ID tag in the corresponding MATERIAL_ENTRY block in the .mat file. There will not necessarily be a bundle for every material, as mat_bundler only supports a subset of all possible materials, however, warnings will be printed for any encountered unsupported material types.

Command-Line Options

The behavior of mat_bundler can be customized through the use of several command-line options. these are described below.

Program help and version

mat_bundler supports the standard DIRSIG -h,--help flags for printing command-line usage and -v,--version for printing version information.

Inspect mode

In order to inspect a material, the inspect command may be utilized:

Example Inspect Mode Output
$ mat_bundler inspect path/to/bundle.mat.hdf
Path: /path/to/bundle.mat.hdf
Name: USGS Pine Wood 2x4 Beam
File Version: 2
Description: Obtained from USGS spectral database: https://speclab.cr.usgs.gov/spectral-lib.html
Author(s):
  Byron Eng
  mat_bundler 2021.20 (a9a59c9)
Organization(s):
  RIT
Spectral sampling: 0.35 - 2.5 [micron] (2151 samples)
Main material:
  Name: USGS Pine Wood 2x4 Beam
  Type: Surface
  Optical Properties:
    Diffuse Reflectance

Specifying a single material

In its default invocation, mat_bundler will attempt to create bundles for every material in a .mat file. This may not always be desirable for a number of reasons. If only a single material is desired, the --id flag may be used:

Single Material Mode
$ mat_bundler build --id=5 path/to/file.mat

in this case the $ID.mat.hdf naming convention is still used and the bundle is still output in the current directory.

Specifying search paths

In a DIRSIG4 scene file, search paths for various types of files can be specified. This can result in paths in a .mat file that cannot be resolved. As such, if these features are used, the user may need to give mat_bundler additional search paths. mat_bundler will output all currently used search paths in its logging output. If a file referenced in the .mat file cannot be located, an error similar to the following will be output:

Example "File Not Found" Error
2020-07-24 10:13:13 (MatFile.cpp:687) [error]: Unable to load material (id = $ID) from $MAT_FILE: Unable to locate required file: $MISSING_FILE
Looked in the following search paths:
  $SEARCH_PATHS

If one of these errors is encountered, it can be rectified by adding an additional search path with -I flag. For example,

Usage With -I option
$ mat_bundler build -I dir/with/missing/file path/to/file.mat

Using this invocation, mat_bundler will search the additional path and should be able to locate the required files. The logging output of mat_bundler can be used to verify that the additional path was added as expected.

Specifying spectral sampling

Similar to a scene HDF file, a material bundle has an inherent spectral sampling. Since these bundles are intended to be reused in many scenes, this spectral resolution should be set as high as possible, as it will be interpolated to the spectral resolution of the scene HDF in the scene compilation process. Since these resolutions cannot be known when making the bundle, the bundle spectral resolution should be made as high as possible, so as to not introduce interpolation artifacts when reusing the material.

By default, mat_bundler uses a high-resolution sampling across the visible to shortwave infrared spectrum. However, this is not intended to be a catch-all default. In many cases, the user knows more about the data than mat_bundler does and should control the sampling through the use of the -w,--wavelengths flag.

The -w flag adds a single, uniformly-sampled wavelength range to the material bundle’s spectral samples. The flag can be used multiple times to build up more complicated ranges. If multiple overlapping ranges are given, mat_bundler will merge the ranges prefer the higher sampling rate in the overlap region. The -w flag supports a number of predefined spectral ranges, which correspond to the predefined ranges that can be put in the properties tag in the scene file. These predefined ranges are described in the scene2hdf manual. It is recommended to just use these predefined ranges, but if a custom range is needed, it can be specified as well with a string of the format start:step:end where all quantities are in units of microns.

For example, the default VNIR ranges would span a range of 0.35 to 1.4 microns. However, if data is only available from 0.35 to 1.1 microns, then this could be specified as below. Two invocations are given to shown how ranges can be combined.

Wavelength Specification Example.
$ mat_bundler build -w vis -w 0.8:0.001:1.000 path/to/file.mat
$ mat_bundler build -w 0.35:0.001:1.000 path/to/file.mat

Using the material bundle

Once the bundle has been created, it can be utilized in a scene via the .mat file through the use of BUNDLE_FILENAME tag. For example:

Example MATERIAL_ENTRY
MATERIAL_ENTRY {
  ID = 1
  NAME = grass
  BUNDLE_FILENAME = materials/grass.mat.hdf
}

When compiling the scene for DIRSIG5, scene2hdf will recognize this tag and ingest the bundle into the scene.

Material bundle file details

Currently, the only supported file format for a material is an HDF file. The interface control document for the for the file format can be for here.