MOSDEF

Description

MOSDEF generates a mosaic-definition file, in XML format, from an existing mosaic project created by MOSPREP or CATALYST Professional Mosaic Tool. The mosaic-definition file contains all of the information necessary to define the output mosaic and can be used by MOSRUN to create the output mosaic.

Note: When you prepare your mosaic by running MOSPREP, and then define the output mosaic in CATALYST Professional Mosaic Tool, you need not run MOSDEF. You can then run MOSRUN, but do not specify a value for MDFILE.

Parameters

mosdef(silfile, mdfile, dbic, tispec, tipostrn, mapunits, pxszout, blend, nodatval, ftype, foptions)

Name	Type	Caption	Length	Value range
SILFILE	str	Source-image list file	0 -
MDFILE *	str	Mosaic-definition file	1 -
DBIC	List[int]	List of input raster channels	0 -
TISPEC	str	Tile specification	0 -
TIPOSTRN	str	Tile-positioning transformation	0 -
MAPUNITS	str	Map units	0 -	PIXEL, UTM, METER, and others
PXSZOUT	List[float]	Output pixel ground-size	0 - 2
BLEND	List[int]	Blend width (in pixels)	0 - 1	Default: 0
NODATVAL	List[float]	No-data image value	0 -
FTYPE	str	Output file type	0 - 4	PIX \| RAW \| TIF \| XWD Default: PIX
FOPTIONS	str	Options for output format	0 - 64

* Required parameter

Parameter descriptions

SILFILE

The name of an existing source-image list file created by the MOSPREP algorithm or a mosaic project created by CATALYST Professional Mosaic Tool. The file identifies all of the input images to mosaic and the order thereof along with other characteristics of the mosaic to create.

MDFILE

The name of the mosaic-definition file, in XML format, to create.

The file name you specify must not exist already. MOSRUN uses this file, along with the file specified for the SILFILE parameter in MOSPREP, during mosaicking.

The name of the file you specify is used as the base name for the definition polygon, which delineates the boundaries of the output mosaic.

Note: MOSRUN also uses the name of the file you specify as the base name for the tile files.

DBIC

The channel or channels to mosaic and include in the output.

Each output channel is a mosaic of all of the data in the input images that exists in the corresponding channel number. If you do not specify a value for this parameter, all channels are processed.

This parameter is optional.

TISPEC

The tiling scheme to apply to the output mosaic.

When mosaicking large volumes of data, it is more practical to store the mosaic results as a series of smaller tiles than one (potentially) large file. MOSDEF creates the tile-definition layout as a vector-polygon layer.

When the mosaic is defined as a:

Single file, the tile-definition layer will contain only one polygon shape
Series of tiles, the tiles will consist of a series of polygon shapes within the vector layer

If you do not specify a value for this parameter, the entire mosaic is created as one continuous file. The output mosaic in this scenario always has this suffix: 1_1

You can specify the value by using one of the following:

VECTOR, <vector_file>, [<field_name>], [<segment_number>], [<buffer_distance>]

Use VECTOR when you have an existing vector-polygon layer that contains the tile definitions you want to use for this mosaic. You can use the vector_file field to specify the name of the file that contains the tile-definition layer.

In the vector layer you specify, there must be a field (attribute) that has unique identifiers for each tile, which you specify using field_name. MOSRUN uses the values in this field as base names of the mosaic-tile files. If you do not specify a value for field_name, the attribute ShapeID will be used. If you do not specify a value for segment_number, the last segment specified for vector_file will be used.

Optionally, the polygons can be extended with a buffer, if specified. The buffer distance is in the units of the vector-layer coordinates. When the input polygons abut and a buffer distance is specified, the mosaic pieces will overlap.

For example:
```
TISPEC="VECTOR, c:\data\NTS_1_to_50000.shp, NTS_Code, 1, 100"
```
DIMENSIONS, <ho_pixel_count>, [<vert_pixel_count>, <ho_pixel_overlap>, <vert_pixel_overlap>]

Use DIMENSIONS to create tiles of a specific size with optional overlap between tiles.

You can use the ho_pixel_count field to specify the number of pixels and vert_pixel_count to specify the number of lines that define the tile size. If you do not specify a value for vert_pixel_count, the value of ho_pixel_count will define both dimensions.

The union of the extents of all of the source images will be divided into a series of evenly sized rectangular tiles with the specified dimension.

You can use the ho_pixel_overlap field to specify the horizontal overlap of each tile (in pixels).

With the vert_pixel_overlap field, you can specify the vertical overlap of each tile (in pixels). If you do not specify a value for vert_pixel_overlap, the value of ho_pixel_overlap is used to define the size of both overlaps.

Only tiles that actually intersect at least one of the source images will be written to the output. Tiles at the far right and those on the far bottom may overhang the extents of the source images. This is done to ensure that all tiles have the same dimensions.

The TileID values are generated using the convention <column_number>_<row_number>. For example, the upper-left tile will always have a TileID of 1_1, while the one immediately below it will be 1_2, and so on.

For example:
```
TISPEC="DIMENSIONS, 5000, 10000"
```
NUMTILES, <ho_tiles>, <vert_tiles>, [<ho_pixel_overlap>, <vert_pixel_overlap>]

Use NUMTILES to create a specific number of tiles with the size of each computed automatically with optional overlap between tiles.

You can use the ho_tiles, and vert_tiles fields to specify the number of horizontal and vertical tiles respectively to divide the whole mosaic. The union of the extents of all of the source images will be divided into a series of evenly sized rectangular tiles such that the number of tiles requested in each dimension is respected.

You can use the ho_pixel_overlap field to specify the horizontal overlap of each tile (in pixels).

With the vert_pixel_overlap field, you can specify the vertical overlap of each tile (in pixels). If you do not specify a value for vert_pixel_overlap, the value of ho_pixel_overlap is used to define the size of both overlaps.

Only tiles that actually intersect at least one of the source images will be written to the output. Tiles at the far right and those on the far bottom may overhang the extents of the source images. This is done to ensure that all tiles have the same dimensions.

The TileID values are generated using the convention <column_number>_<row_number>. For example, the upper-left tile will always have a TileID of 1_1, while the one immediately below it will be 1_2, and so on.

For example:
```
TISPEC="NUMTILES, 4, 5"
```
SCRIPTFILE, <text_file>, [<coordinate_type>]

Use SCRIPTFILE when you have a text file that defines the coordinates of each tile you want to create. Each line in the text file contains five elements, separated by spaces: the first two define the upper-left coordinate in the x and y dimension, respectively, the next two define the lower-right coordinate in the x and y dimension, respectively, and the last one specifies the output file name of the tile.

When the file name includes an extension, the extension is removed when the value is stored as the TileID attribute in the tile-definition polygon. When the file name includes a path, the entire path is transferred and appended to the value of OUTDIR, if specified, in MOSRUN.
The values in the text file can be in one of these coordinate types:
- RASEXT: Raster extents
- GEOEXT: Geocoded extents
- LNGLATEX: Longitude and latitude extents
- RASOFFSZ: Raster offset and size
- GEOOFFSZ: Geocoded offset and size
RASEXT and RASOFFSZ make use of pixel/line raster as defined by the union of the extents of all input source images. If you do not specify a value for coordinate_type, GEOEXT will be used.

For example:
```
TISPEC="SCRIPTFILE, C:\data\Toronto\Sites.txt, GEOEXT"
```

Regardless of which option you specify for TISPEC, MOSDEF creates a vector file containing polygons that define the tiles using the naming convention MDFILE_tilepoly.pix. The file is written to the folder specified for the MDFILE parameter.

When you specify any option other than VECTOR as the value of TISPEC, the tile polygons are generated by MOSDEF and contain four attributes, as follows:

ShapeID
Area
Perimeter
TileID

When you specify VECTOR as the value of TISPEC, tiles are not generated; rather, they are copied from the specified existing polygon layer. Only the shapes that partially intersect at least one of the source images are transferred to the MDFILE_tilepoly.pix file. Tiles must be in the same projection as the output mosaic: if the provided vector layer is not in the same projection, the tiles are reprojected.

This parameter is optional.

TIPOSTRN

Whether to adjust the starting position of the output tile.

You specify the value by entering a keyword and either two or four values. The keyword indicates whether the remaining values are relative to the upper-left corner of the first pixel in the output tile, CORNER, or relative to the center of the first pixel, CENTER.

After you specify the keyword, the general form of the remaining values are Stride_X, Stride_Y, Ref_X, and Ref_Y. The values define the tile locations in the output mosaic.

You can use keyword RELATIVE to indicate that reference corner point should be the UL point of your input images. Then only Stride_X and Stride_Y can be specified. If they are left blank then output pixel size is used as stride value.

For example, the following statement specifies that the upper-left corner of the upper-left pixel of each tile will be an even 20-meter multiple from the reference point (432345.000, 5438882.000):

TIPOSTRN="CORNER, 20, 20, 432345.000, 5438882.000"

Depending on the distance of the tile from that point, its upper-left corner coordinate can be 432345.000, 432045.000, or any other multiple, but will never be 432346.000 or 432355.000.

MAPUNITS

The projection string or units of the output mosaic.

If you do not specify a value for this parameter, the projection is taken from the first image occurring in the source-image list file. If the projection you specify differs from that of the input data, the data is reprojected. A projection string must fully identify the projection and Earth model you want, such as UTM 17 D000. A projection is written to the output mosaic-definition file in the MapProj metadata tag.

The standard definitions are as follows:

UTM: Universal Transverse Mercator
SPCS: State Plane Coordinate System
LONG/LAT: Longitude and latitude
METER: Image along-row and along-column meters
FOOT: Image along-row and along-column feet
PIXEL: Pixel and line

Note: Projections such as TM or PC that have specific parameters cannot be defined using their generic name (for example, "PC D000"), because the string does not completely define the projection. There may be any number of origins or false east/west for the same projection, depending on your location. You must include the specifics of the projection (true origin, false easting and northing, and scale) by adding a new projection to the userproj.txt file in the $PROHOME/etc folder, and use this new ProjectionName string to define the MAPUNITS parameter.

For a complete list of supported projections and Earth models, see Map projections. For information on the format of the map-units string, see Output units.

PXSZOUT

The horizontal and vertical pixel size, in the units specified for the MAPUNITS parameter. If you specify only one value, it defines the pixel size in both dimensions. If you do not specify any values, the resolution of the output mosaic is determined automatically by examining the resolution of the input images. The resolution occurring most frequently; that is, the mode, will be used as the output resolution. If the mode is not unique, the coarsest of the tied resolutions will be used.

This parameter is optional.

BLEND

The perpendicular distance from the cutlines to which to apply image blending.

Image blending is to average the gray value of each pixel in the blending strip along a cutline from both overlapped input images.

This parameter is optional.

NODATVAL

The pixel values to use as the NoData values in the output mosaic.

Pixels covered by some of the input images will have those values overwrite the initial values of the NODATVAL parameter.

The value of the NODATVAL must be a number within the range defined by the bit depth of the data being mosaicked. For example, when mosaicking 8U data, the value of NODATAVAL must be an integer between 0 and 255.

If you do not specify a value for this parameter, the NoData value of the input channels is used. When NoData is neither specified nor available from any source, the minimum storable value for the channel type is used, by default, except with a channel type of 32R.

For example, when mosaicking 8U data, a default NoData value of 0 is used when no value is specified for NODATVAL and the input channels do not have a defined NoData value. With a 32R channel type, however, a value of -32768 is used, by default, when you do not specify a value for the parameter.

If necessary, you can enter more than one NoData value for your output mosaic. For example, to specify that channel 1 has a NoData value of -9999, channel 2 is 0, and channel 3 is 255, enter -9999,0,255.

This parameter is optional.

FTYPE

The format of the output file.

The format must be one of the following GDB-updatable types:

The default value is PIX.

FOPTIONS

The options specific to the format to apply when creating the output file. With each, the default of no options is allowed (empty string).

Typically, the available options for a format include a compression scheme, format subtype, or other information.

For information about the available options for each supported format, see:

Details

You create mosaics by running several algorithms. With MOSDEF, you use the source-image list file created by the MOSPREP algorithm as input to create a mosaic-definition XML file. You then can use MOSRUN to combine the MOSPREP and MOSDEF outputs.

After running successfully, MOSDEF creates an output file, in XML format, and a polygon-vector file, in PCIDSK format, of the defined tiles.

Output files created by MOSDEF include:

<MDFILE>.xml: mosaic-definition list file. The file contains various settings that describe the mosaic to create with MOSRUN. The file also contains a reference to a polygon layer that defines the mosaic tiles or mosaic layout and information from the parameters entered or from the source images.
<MDFILE>_tilepoly.pix: output file in PCIDSK format. The file contains a polygon-vector segment representing all the mosaic tiles to create with MOSRUN.

Example

This example generates a mosaic-definition file for the specified source-image list file and an existing polygon to create a tile-definition file.

from pci.mosdef import mosdef

silfile = "Halifax.mos"  # Source-image list file created by MOSPREP
mdfile = "Neighborhoods_def.xml" # Mosaic-definition file to create
dbic = [1,2,3]              # Use image channels 1,2,3
tispec = "VECTOR, Neighborhoods.pix, MapCode" # The 'MapCode' attribute will be used as TileID
tipostrn = ""
mapunits = ""
pxszout = [5]               # Output pixel size, same for x and y
blend = [3]                 # Blend will be three pixels from the cutlines
nodatval = []
ftype = "TIF"               # Output mosaic file type
foptions = "TILED256"

mosdef(silfile, mdfile, dbic, tispec, tipostrn, mapunits,
       pxszout, blend, nodatval, ftype, foptions)

Environments	PYTHON :: EASI
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Example :: Related

MOSDEF

Mosaic Definition Preparation

Description

Parameters

Parameter descriptions

Details

Example