NAME

make_dem - create a DEM dataset from a source (rectified) image file

make_dem <dataset> <img-name> [...]

This utility can be used to create DEM (elevation) terrain datasets for the TerraVision application from source imagery. The utility can write datasets to local disk or directly to a DPSS (if DPSS supported compiled in). The following data are generated for you:

1. create the tiles.tspec file for a dataset (unless -tilesonly specified)
2. create the image tiles for all levels of the dataset (unless -tspeconly specified).

The utility creates a multi-resolution pyramid of tiled images for the dataset. Each successive level is exactly half the resolution of its previous level. The input image is recursively down sampled to create new resolution levels until the down sampled image is contained within a single 128 x 128 pixel tile.

Currently make_dem recognises the following input formats. make_dem determines the file format soley based upon the extension of the image filename that you specify. Depending upon the particular image format, some information about the data can be automatically extracted for you.

1. USGS DEM (.dem) - the US Geological Survey's Digital Elevation Model format. This format contains all of the parameters that make_dem requires in order to create a TerraVision DEM dataset.

2. NIMA DTED (.dt0) - Digital Terrain Elevation Model (level 0) format. This format contains all of the parameters that make_dem requires in order to create a TerraVision DEM dataset.

3. LAS (.img) - Land Analysis System image files (RGB only). If there is a .prt file for the specified .img file, then this will be read to find out various pieces of information about the raw image data. Normally this means you don't have to supply the options -width, -height, -startres, -ll_e, -ll_n, or -zone, as these are defined in the .prt file.

   N.B. checks are made on the contents of the .prt file to ensure that the projection code is UTM or GEOGRAPHIC (make_oi will fail if the projection code is anything else). A warning will be displayed if the projection units value are not meters (for UTM) or degrees (for Lat/Long).

4. RAW (.raw) - a raw, binary bitmap. The order of the pixels must be left->right, top->bottom (row-major), i.e. the first pixel in the image corresponds to the upper-left corner of the dataset. The elevation values are assumed to be in values of meters and stored as 32-bit (4-byte) integers, although this latter default can be changed with the -bytespercomp option. In order to preserve a number of decimal places of accuracy, the meters values are normally assumed to be multiplied by some constant. The -scale option specifies the inverse scaling factor to retrieve the original meter values, i.e. if you set -scale is 0.001 then you are saying that each 32-bit integer in the raw data represents the actual meter value multiplied by 1000.

   Because this format contains only raw data, you must specify the image dimensions and georeferencing information on the command line, e.g. -width, -height, -startres, -zone, etc.

5. LRBT (.lrbt) - a raw, binary bitmap (RGB and grayscale). The order of the pixels must be left->right, bottom->top (row-major), i.e. the first pixel in the image corresponds to the lower-left corner of the dataset. The elevation values are assumed to be given as scaled, 32-bit integers by default - as in the case for RAW (.raw) files above.

   Because this format contains only raw data, you must specify the image dimensions and georeferencing information on the command line, e.g. -width, -height, -startres, -zone, etc.

A number of command line options are supported. These are described below. The position of any optional argument on the command line is not significant. Running the program with no parameters will display a help text.

Required Parameters:

<dataset>

This must be the first argument on the command line. It specifies the name and location of the dataset that you wish to create. This can be a localdisk directory name, a file://localhost URL, or an http:// URL for a HTTP dataset. Examples of valid dataset names include:

• ~magic/TileSets/Pyramids/laguna_beach.dem
• file://localhost/homedir/magic/TileSets/Pyramids/yosemite
• http://www.tvgeo.com/TileSets/Pyramids/ntc-1-utm-2scene.33.dem

N.B. make_dem will append a ".dem" extension to the name of your pyramid if you do not supply one. So in the second example above, make_dem will create a dataset called "yosemite.dem".

<img-name>

This must be the second argument on the command line. It specifies the name of a file on local disk that contains the input imagery for the dataset. The currently supported file formats that this program supports are described above. The filename extension is used to work out the particular format that is being used, e.g. .dem or .dted.

-width <pixels>

This option is used to specify the pixel width of the image that is being used to create the dataset (number of samples). make_dem needs to know this value, but it will be found for you automatically if you are using .img format imagery. N.B. this option will override any values found from these input files.

-height <pixels>

This option is used to specify the pixel height of the image that is being used to create the dataset (number of lines). make_dem needs to know this value, but it will be found for you automatically if you are using .img format imagery. N.B. this option will override any values found from the

Optional Parameters:

-bytespercomp <bytes>

This option specifies the byte size of each elevation value in the raw data file. By default this value is 4, i.e. 32-bit elevation values are assumed. You could however read DEM data where each value is stored as a 16-bit integer by specifying -bytespercomp 2 and make_dem will resampled the data to 32-bit for you (unless -outbytespercomp is specified).

-outbytespercomp <bytes>

This option specifies the byte size of each elevation value in the TerraVision dataset that is output. By default this value is 4, i.e. 32-bit elevation values are assumed. You could however create TerraVision datasets where each value is stored as a 16-bit integer by specifying -outbytespercomp 2 and make_dem will resampled the data to 16-bit as necessary.

-startlev <level>

This specifies the starting level number (0..n) to use for the dataset (a terrain dataset is a multi-resolution pyramid where each level of the pyramid contains data for the same geographical area, but at different resolutions). The default setting is 0, and there is probably little reason to change this.

-startres <resolution>

This option is used to specify the resolution of the input image (i.e. for the highest resolution level of the dataset). That is, how many meters or degrees does a single pixel in the input level image project to in the actual terrain. If you do not specify this value, then the default is 32.0 - i.e. one pixel represents 32 m on the ground.

-geoname <geoset_name>

This string can be used to define the geoset name of the dataset. The geoset name is used to give a name to the combination of the OI and DEM dataset for a particular region, i.e. this should be the same (and unique) for both the OI and DEM. If you do not specify a geoset name then one will be generated automatically be taking the dataset name, removing any filename extensions, and capitalizing it.

-planet <planet_name>

This string can be used to specify the planet that the dataset is on. This can be one of "earth", "mars", "venus", etc. Case is not important (i.e. "earth", "Earth", or "EARTH" are all good). If you do not specify this string, then "earth" will be assumed.

-type <source_type>

This string can be used to describe the source of the input image. The default value is "unknown".

-descr <description>

This string can be used to provide a human-readable description of the dataset, e.g. to specify where the dataset is, how large it is, etc. The default value is "".

-sources <string>

This string is used to provide the locations of the source imagery. That is, the permanent location of the input file. The default value is "".

-ops <operations>

This string declares a list of operations that have been performed on the input image. This string is composed of one or more predefined tokens separated by spaces (i.e. always enclose list in quotes if specifying more than one token). Possible tokens include: merge, window, tile, rectify, oi-trim, utm-to-lvcs, mosaic, gauss-reduce, point-sample, terraform-mosaic, scan, usgs-rectify, usgs-mosaic, gpyramid. For example, a valid operations string might be "usgs-rectify usgs-mosaic". By default, "point-sample" will be appended to any string you supply (or "gauss-reduce" if you specify the -gaussian command line argument).

-doneby <name>

This option is used to declare the name of the person, organization, and/or software that was used to generate the dataset. By default, this will be "the tsmApi library".

-scale <factor>

This option lets you specify the scaling factor for the data in the DEM file. The data in the DEM file will be copied verbatim into the new dataset. However, this scaling factor lets you specify whether the data should be scaled when it is read from the dataset (i.e. this scaling factor is applied internally be the tsmApi library when it reads DEM data). The default value is 1.

This default scaling value assumes that the input DEM data are in units of meters. These values are stored as 4-byte integers, so if for example you wanted sub-meter accuracy then you could multiply all of the raw values by 1000 and set -scale 0.001. This will give you 3 decimal places of accuracy.

-offset <value>

As well as scaling the elevation values when they are eventually read from the new dataset, you can specify an offset. This is a value that is added to the elevation value once it has been scaled. The default value is 0.

-sealevel <value>

This is the height value that is used in the input data (after applying the scale and offset) to represent areas of sea. When make_dem is creating a tileset it will convert all instances of this elevation value to 0.0 in the resulting DEM. This can be used if your elevation data uses a special value (e.g. -9999) to represent sea areas. The default value is 0.0.

Geo-reference Information:

1. UTM:

   -ll_e <eastings>

   You need to provide georeferencing information so that the exact location of the dataset on the planet is known. This is done by providing the lower-left coordinate of the image (the upper-right coordinate can be calculated from the lower-left coordinate, the image size, and the resolution). The -ll_e argument is used to specify the easting value of the lower-left UTM coordinate (in units of meters).

   -ll_n <northings>

   This argument is used to specify the northing value of the image's lower-left UTM coordinate (in units of meters). Use a negative northing value to specify coordinates in the southern hemisphere.

   -zone <number>

   This argument is used to specify the UTM zone number for the lower-left corner of the image. A UTM zone number should be in the range 1..60 (i.e. each zone is 6 degrees of longitude).

2. Lat/Long:

   -ll_lat <degrees>

   You can use these options to specify a lat/long geo-reference. The -ll_lat option can be used to specify the latitude of the lower-left coordinate of the image (the upper-right coordinate can be calculated from the lower-left coordinate, the image size, and the resolution).

   -ll_long <degrees>

   This argument is used to specify the longitude value of the image's lower-left lat/long coordinate (in units of degrees).

Dataset Generation Options:

-writelrbt

Supplying this option means that you want make_dem to create a dataset containing raw (lrbt-raster) tiles. This is the default image format.

-writejpeg

This option is not appropriate for DEM data.

-jpegquality <percentage>

This option is not appropriate for DEM data.

-writetiffs

If you are creating a dataset on localdisk (as opposed to on a DPSS), then supplying this option means that you want make_dem to write the tile data using a blocked TIFF format, where all of the tiles for a single level are stored in a single TIFF file. This is the default storage format.

-writerawtiles

If you are creating a dataset on localdisk (as opposed to on a DPSS), then supplying this option means that you want make_dem to write the tile data using the .tile format, where each tile is stored as a single, raw file (using a naming convention of p<x>p<y>.tile).

-writeserver1 <server-name>, -writeserver2 <server-name>, ...

If you are creating a dataset on a DPSS (as opposed to on localdisk), then these options let you specify the server combination of the set to be created. You must specify at least one server if you are going to write to a DPSS set. For example, a two server combination would be defined by: -writeserver1 sri-server1 -writeserver2 lbl-server3.

-metadata1 <url>, -metadata2 <url>, ...

If you are creating a dataset on a DPSS (as opposed to on localdisk), then these options let you specify the metadata URLs for the set. Metadata URLs specify one of more locations of the dataset's tspec file which are accessible using conventional http or localdisk protocols. You do not need to specify any metadata URLs because a tspec file will always be written to a block on the DPSS for that dataset (unless you specify -tilesonly of course).

Optional Output Control:

-tilesonly

If you supply this command line option the make_dem will only create the tile data for the dataset - it will not create a tspec file or update the PyramidUrls database.

-tspeconly

This option means that make_dem will only create the tspec file and update the PyramidUrls database. No tile data will be generated.

-gaussian

When make_dem down samples the original data, there are a number of different schemes that it can employ. Specifying this option means that you want to perform a Gaussian filtering operation so that a single pixel in the down sampled image is calculated by interpolating over a number of pixels in the parent image.

-pointsample

When down sampling images, another scheme is to single choose the value of every second pixel, with no interpolation. Supplying this option will employ this mode operation for the down sampling process. This is the default operation for down sampling of DEM data.

-leaveimages

make_dem will recursively downsample your input image for you in order to generate the input data for all levels of the dataset's multiresolution pyramid. By default, all of these intermediate images are deleted when make_dem finishes its work. If you would like to keep these, then use this option.

-info

This is a useful option that will display some details about a dataset once you have created it. An example output might be:

  Name    = laguna_beach.dem
  Mode    = write-only
  Min Lev = 5 (78.0)
  Max Lev = 8 (624.2)
  Pixels  = 160 x 160
  Tiles   = blocked-tiff
  Type    = dem
  Format  = lrbt-raster

-version

This will display the version of the tsmApi that was used to create the make_dem binary that you are using. Also, if DPSS support is compiled into your binary, then the DPSS version information will be displayed too. This will be followed by make_dem's help text (which includes make_dem's version number).

-debug <level>

This option can be used to set the tsmApi debug level. By default, this is set to 0 (no debug information). If you set this to a higher number (1-5), then the tsmApi library will display debugging messages as it performs various operations. This is provided for debugging purposes.

-help

Finally, you can use the -help option to try and display this page over the web. You will need the program "netscape" in your path. If you already have netscape running, then the manual page will be displayed using that netscape session, rather than trying to reload netscape again. Note that occasional network problems may make this page inaccessible from your terminal.

1. The following example will create a localdisk dataset from a source LAS format image, which has an accompanying .prt file. We use the -info parameter to provide some feedback once the dataset has been generated. (N.B. to make the example readable, we split the one command line over multiple lines using '\' characters at the end of lines to be continued.)

     make_dem ~magic/TileSets/Pyramids/laguna_beach \
              laguna_beach.ca_dem.img \
              -useprt -info
   

2. Now we will show the same example again, but this time we specify all of the information manually, i.e. as if there were no .prt file, and we only create the tspec file - no tile data.

     make_dem ~magic/TileSets/Pyramids/laguna_beach \
              laguna_beach.ca_dem.img \
              -width 160 -height 198 \
              -ll_e 417945 -ll_n 3708247 -zone 11
              -startres 78.0288 \
              -tspeconly
   

3. In the following example, we show how to create a dataset directly on to a DPSS. Here we generate a set using a single server. The tspec file will be written to a block on the DPSS.

     make_dem x-dpss://iss-1.sri.magic.net/Pyramids/laguna_beach \
              laguna_beach.ca_dem.img \
              -writeserver1 sri-server1 \
              -useprt
   

Martin Reddy, SRI International. <reddy@ai.sri.com>
Yong Tze Chi, SRI International

• make_oi Manual Page
  
• make_geovrml Manual Page
  
• tsmApi Tutorials and Examples Page
  
• tsmApi Home Page