NAME

copy_dataset - copy an entire TerraVision dataset (DEM or OI) to another location

copy_dataset <input-dataset> <output-dataset> [...]

This utility copies tile and tspec data from one location to another. The source and destination can be on different media, e.g. localdisk or http, and you can change the name, image format, and storage format of the data during the copy (where appropriate). Options are provided to selectively copy only the tspec or only the tile data.

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:

<input-dataset>

This must be the first argument on the command line. It specifies the name and location of the dataset that you wish to copy. 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

<output-dataset>

This must be the second argument on the command line. It specifies the name and location of the dataset that you wish to produce. This should be a localdisk directory name or a file URL as in the case for <input-dataset>. Note that if you are writing to a DPSS, then you must supply at least one -writeserver<n> option.

Optional Parameters for the Input Dataset:

-readlrbt

Supplying this option means that you want to read a raw (lrbt-raster) version of the input dataset, if available. This is the default action. Note that if a raw version is not available, then copy_dataset will try to find and read a JPEG version instead (unless you specify -readexact).

-readjpeg

Supplying this option means that you want to read a JPEG compressed version of the input dataset, if available. Note that if a JPEG compressed version is not available, then copy_dataset will try to find and read a raw version instead (unless you specify -readexact).

-readtiffs

If the input dataset is on localdisk, then this option means that you want to read the TIFF file version of the dataset, if available. The TIFF file is a composite format that contains all of the tiles for a single level of the dataset in one file. This is the default storage format to use. Note that if the TIFF file is not available, then copy_dataset will try to use the raw tile format instead (unless you specify -readexact).

-readrawtiles

If the input dataset is on localdisk, then this option means that you want to read the older .tile format data. These are raw files where each tile in a dataset is stored as a single .tile file (using a naming convention of p<x>p<y>.tile). Note that if the raw tile files are not available, then copy_dataset will try to use the TIFF format tiles instead (unless you specify -readexact).

-readexact

This option stops any fallback selection for the input dataset. By default, if a particular version of a dataset is not available, then copy_dataset will try to find another one to use (e.g. different image format, or storage format). You can use this option to make copy_dataset fail if the specified (or default) version of the dataset is not available.

-readsetid <id>

If the input dataset is on a DPSS, then you can use this option to specify the set ID of the set you wish to read. This uniquely identifies a set on a DPSS and so any server combination or image format requests will be ignored.

-readserver1 <server-name>, -readserver2 <server-name>, ...

If the input dataset is on a DPSS, then you can use these options to specify the server combination of the set that you wish to use. If you do not specify any server combination, then you are saying that you don't care about the server combination and copy_dataset will pick any set (whilst trying to satisfy your image format request). For example, if you wanted to read from a dataset that only has the server combination sri-server1 and lbl-server3, then you would say: -readserver1 sri-server1 -readserver2 lbl-server3 (N.B. order is not important).

-readmetadata

If the input dataset is on a DPSS, then you can use this option to tell copy_dataset that you want to use the metadata URLs to try and find a valid tspec file. By default, copy_dataset will first try to read a tspec file from the DPSS dataset itself. If this fails, then it will read each of the metadata URLs in turn until a valid tspec file is found. You can therefore use this option if you don't want to read the tspec from the DPSS dataset.

-readnewtspec

When trying to read tspec data from localdisk or over http, this option will force copy_dataset to only try and read the new single-file version of the tspec. By default, copy_dataset will first try to read the new tspec format, and if this fails it will then try to read the old tspec format.

-readoldtspec

When trying to read tspec data from localdisk or over http, this option will force copy_dataset to only try and read the old multiple file versions of the tspec data. By default, copy_dataset will first try to read the new tspec format, and if this fails it will then try to read the old tspec format.

-dontvalidatetspec

By default, copy_dataset will try to perform a number of checks on any tspec file that it manages to load. These ensure that many of the tspec values are valid. If you want to bypass this validation process, then you can supply this option.

Optional Parameters for the Output Dataset:

-writelrbt

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

-writejpeg

Supplying this option means that you want to create a dataset containing JPEG compressed tiles. Note that this option will not work in conjunction with the -writerawtiles option. Note also that this option is not appropriate for DEM data - if you are copying a DEM dataset and specify this option then it will be ignored (see -writeexact though).

-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. This option is ignored for DEM datasets.

-writetiffs

If you are creating a dataset on localdisk (as opposed to on a DPSS), then supplying this option means that you want 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 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).

-writeexact

This option stops any fallback selection for the output dataset. Currently this just means that copy_dataset will fail if you try to specify a JPEG version of a DEM dataset, as this combination is not currently supported. If you do not supply this option and you do a -writejpeg for a DEM output dataset, then that option will be ignored.

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

-info

This is a useful option that will display some details about the output dataset once it has been copied. 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 copy_dataset 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 copy_dataset's help text (which includes copy_dataset'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 copy a localdisk DEM dataset onto a DPSS. We need to specify the server combination for this operation - in this example we specify a two server combination. We also specify a single metadata URL to use as a fallback tspec location. Note however that the tspec file will also be loaded onto the DPSS along with the tile data.

     copy_dataset ~magic/TileSets/Pyramids/laguna_beach.dem \
                  x-dpss://iss-1.sri.magic.net/Pyramids/laguna_beach.dem \
                  -writeserver1 sri-server1 -writeserver2 lbl-server3 \
                  -metadata1 file://localhost/~magic/TileSets/Pyramids/laguna_beach.dem
   

2. In the following example, we show how to copy only a tspec file from one dataset to another (the PyramidUrls database will also be updated). Note that in this example we also specify a different name for the output dataset.

     make_dem ~magic/TileSets/Pyramids/laguna_beach.oi \
              ~magic/TileSets/Pyramids/laguna.oi \
              -tspeconly
   

3. The next example will copy an OI dataset on a DPSS to a localdisk dataset. All of the tiles and tspec data will be copied, and the ~magic/TileSets/Pyramids/PyramidUrls database will be updated. We also request that the tiles for the new dataset be written in JPEG compressed format. The -info parameter is used to provide some feedback once the dataset has been copied. (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.)

     copy_dataset x-dpss://iss-1.sri.magic.net/Pyramids/yosemite.oi \
                  ~magic/TileSets/Pyramids/yosemite.oi
                  -writejpeg -info
   

copy_dataset.c - source code for the program
copy_dataset.irix - Irix 6.3 executable
copy_dataset.solaris - Solaris 2.6 executable

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

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