NAME

make_oi - create an OI dataset from a source (rectified) image file

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

This utility can be used to create ortho-image terrain datasets for the TerraVision application from source imagery. The utility can write datasets to local disk or directly to a DPSS (if support for DPSS is compiled in), and in either raw or JPEG compressed formats. 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_oi recognises the following input formats. make_oi 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 DOQ (.coq) - the US Geological Survery Digital Orthoquad format for satellite imagery. This format contains a metadata file which describes all of the parameters that make_oi should require.

2. TIFF/GeoTIFF (.tiff/.tif) - the TIFF image file format is supported. Baseline TIFF does not contain any georeference information so you will need to specify things like -startres, -zone, etc. However, the GeoTIFF format does include this information and if make_oi encounters a GeoTIFF file it will attempt to read all geographic information about the image from the file for you. make_oi supports RGB and indexed color TIFF raster files, but it does not currently support reading from tiled TIFF files.

3. JFIF/JPEG (.jpg/.jpeg) - the JPEG image format can be used to specify the OI imagery. As this format contains no georeference information, you will need to specify options such as -startres, -zone, -ll_x, etc. manually.

4. GIF (.gif) - the GIF image format can also be used to specify the OI imagery. As this format contains no georeference information, you will need to specify options such as -startres, -zone, -ll_x, etc. manually.

5. PPM (.ppm) - a binary Portable PixMap image (ASCII PPM files are not supported). This contains the raw data for a colour (RGB) image. If this type of image file is specified, then make_oi reads the image width and height for you, so you don't need to use the -width and -height options. You will still have to specify georeferencing information, e.g. -startres, -zone, -ll_x, etc.

6. PGM (.pgm) - a binary Portable GrayMap image (ASCII PGM files are not supported). This contains the raw data for a grayscale image. If this type of image file is specified, then make_oi reads the image width and height for you and also sets the number of components per pixel to one, so you don't need to use the -width, -height, or -comps options. You will still have to specify georeferencing information, e.g. -startres, -zone, -ll_x, etc.

7. 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, -comps, -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).

8. RAW (.raw) - a raw, binary bitmap (RGB and grayscale). 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. 3 components per pixel (i.e. colour) and 1 component per pixel (i.e. grayscale) formats are supported. Each pixel component is assumed to be one byte in size (although this can be changed with the -bytespercomp option), and for colour images all components are given in the order: red, green, blue.

   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. Also, if the data file contains grayscale data, then you must specify -comps 1.

9. 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. 3 components per pixel (i.e. colour) and 1 component per pixel (i.e. grayscale) formats are supported. Each pixel component is assumed to be one byte in size (although this can be changed with the -bytespercomp option), and for colour images all components are given in the order: red, green, blue.

   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. Also, if the data file contains grayscale data, then you must specify -comps 1.

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 x-dpss:// URL for a DPSS dataset. Examples of valid dataset names include:

• ~magic/TileSets/Pyramids/laguna_beach.oi
• file://localhost/homedir/magic/TileSets/Pyramids/yosemite
• x-dpss://iss-1.sri.magic.net/Pyramids/ntc-1-utm-2scene.128.oi

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

<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. .ppm or .raw.

-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_oi needs to know this value, but it will be found for you automatically if you are using .ppm, .pgm, or .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_oi needs to know this value, but it will be found for you automatically if you are using .ppm, .pgm, or .img format imagery. N.B. this option will override any values found from these input files.

Optional Parameters:

-comps <bands>

This option is used to specify the number of components per pixel for the input image (number of bands). For example, an image file which contains red, green, and blue (RGB) data for each pixel will have 3 components per pixel. This argument is optional - if you do not specify it, then a default of 3 will be assumed.

-bytespercomp <bytes>

This option specifies the byte size of each pixel component in the raw data file. By default this value is 1, i.e. 8-bit values are assumed for each component red, green, and blue, and also grayscale values. You could however read image data where each value is stored as a 16-bit integer by specifying -bytespercomp 2.

-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). For image datasets, this value is general 0. If you do not specify this option, then the default value is also 0.

-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 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 1.0 - i.e. one pixel represents one meter 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. Possible values might be "spot" or "cir-napp". 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, "gauss-reduce" will be appended to any string you supply (or "point-sample" if you specify the -pointsample 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".

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_oi to create a dataset containing raw (lrbt-raster) tiles. This is the default image format.

-writejpeg

Supplying this option means that you want make_oi to create a dataset containing JPEG compressed tiles. Note that this option will not work in conjunction with the -writerawtiles option.

-jpegquality <percentage>

This option allows you to alter the degree of compression used when writing JPEG compressed data (and hence alter the quality of the images). You specify this using a percentage value between 5 and 100, where 100 means the lowest compression ratio and hence the highest image quality. The default value is 75.

-writetiffs

If you are creating a dataset on localdisk (as opposed to on a DPSS), then supplying this option means that you want make_oi 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_oi 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). Note that this format can only be used to store raw tile data: it cannot handle JPEG compressed data.

-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_oi 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_oi will only create the tspec file and update the PyramidUrls database. No tile data will be generated.

-gaussian

When make_oi down samples the original image, 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. This is the default operation for down sampling of imagery.

-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.

-leaveimages

make_oi will automatically downsample your input image for you in order to generate the input data for all of levels of the dataset's multiresolution pyramid. By default, all of these intermediate images are deleted when make_oi 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.oi
  Mode    = write-only
  Min Lev = 0 (2.4)
  Max Lev = 8 (624.2)
  Pixels  = 5435 x 6732
  Tiles   = blocked-tiff
  Type    = image
  Format  = lrbt-raster

-version

This will display the version of the tsmApi that was used to create the make_oi 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_oi's help text (which includes make_oi'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_oi ~magic/TileSets/Pyramids/laguna_beach \
             laguna_beach.ca.img \
             -info
   

2. Now we will show the same example again, but this time we are using a PPM file and so need to specify some of the georeferencing information manually. Also, we only create the tspec file - no tile data.

     make_oi ~magic/TileSets/Pyramids/laguna_beach \
             laguna_beach.ca.ppm \
             -ll_e 417945 -ll_n 3708247 -zone 11
             -startres 2.4384 \
             -tspeconly
   

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

     make_oi x-dpss://iss-1.sri.magic.net/Pyramids/laguna_beach \
             laguna_beach.ca.img \
             -writeserver1 sri-server1 \
             -writejpeg
   

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

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