CLIP

Description

CLIP collects raster, vector, or bitmap layers to create a new file from dataset regions you specify. You can define clip regions with a clip file, clip layer, or coordinates you define. The formats of the input and output files are supported by the generic database (GDB).

The CLIP algorithm performs clipping similar to doing so in CATALYST Professional Focus.

Parameters

clip(fili, dbic, dbsl, sltype, filo, ftype, foptions, clipmeth, clipfil, cliplay, laybnds, coordtyp, clipul, cliplr, clipwh, initvalu, setnodat, oclipbdy)

Name	Type	Caption	Length	Value range
FILI *	str	Input file path	1 -
DBIC	List[int]	Input raster channels or layers	0 -
DBSL	List[int]	Input segments	0 -
SLTYPE	str	Input segment type	0 -	ALL, VEC, BIT, PCT, LUT, GCP, SIG, TEX, BIN, ORB, ARRAY Default: ALL
FILO *	str	Output file name	1 -
FTYPE	str	Format of output file	0 - 4	Default: PIX
FOPTIONS	str	Options for output file	0 - 64
CLIPMETH	str	Clip definition method and output file field name	0 -	FILE, LAYERRAS, LAYERVEC, LAYERVEC_FILES, LAYERBIT, USERCRD Default: FILE
CLIPFIL	str	Clip file name	0 -
CLIPLAY	List[int]	Clip channel or segment	0 - 1
LAYBNDS	str	Layer boundaries	0 -	EXTENTS, SHAPES Default: Extents
COORDTYP	str	Coordinate type	0 - 8	RASEXT, GEOEXT, LNGLATEX, RASOFFSZ, GEOOFFSZ Default: GEOEXT
CLIPUL	str	Upper-left clip coordinates	0 -
CLIPLR	str	Lower-right clip coordinates	0 -
CLIPWH	str	Clip region width and height	0 -
INITVALU	List[float]	Initialization pixel value	0 - 1	Default: 0.0
SETNODAT	str	Sets a "NoData" pixel value	0 - 1	Y, N Default: N
OCLIPBDY	str	Output clip-region boundary	0 - 1	Y, N Default: N

* Required parameter

Parameter descriptions

FILI

The PCIDSK or GDB-supported file that contains the input data.

DBIC

The input channels or layers to process.

DBSL

The input segment or segments to process.

In conjunction with the SLTYPE parameter, this parameter identifies the input file segments that contain data to clip, if applicable, and writes the segments to the output dataset. Bitmap and vector segments are clipped, whereas other segment types are transferred in their entirety.

The contents of all segments that have one of the specified numbers and are of one of the types specified with the SLTYPE parameter are clipped and written to the output dataset.

If no value is specified for this parameter, the contents of segments that have any number and one of the specified types are clipped and written to the output dataset.

SLTYPE

The GDB-supported data types that are used for any segments specified for the DBSL parameter.

Supported types include:

ALL: matches any segment type
VEC: vector segment
BIT: bitmap segment
PCT: pseudocolor-table segment
LUT: lookup-table segment
GCP: ground-control-point segment
SIG: signature segment
TEX: text segment
BIN: binary segment
ORB: orbit segment
ARRAY: array segment

The range of types is specified with a comma-delimited string list. This list, together with the list of segment numbers (see DBSL) identifies the input segments that contain data to clip and write to the output dataset.

For example:

EASI > DBSL = 1, 3, 5
EASI > SLTYPE = VEC, LUT

The preceding example uses segments 1, 3, and 5 for each vector and lookup table segment type. If a vector data type (VEC) exists in segments 1 and 3 only, and a LUT type in segment 5, the result is VEC 1, 3 and LUT 5. A standard PIX file does not support more than one segment type per segment; however, other file types may support multiple segment types per segment. In such cases, if vector data exists in segments 1, 3, and 5 and LUT data exists in segment 3, the result is VEC 1, 3, 5 and LUT 3.

If no value is specified for this parameter, or if ALL is specified, the contents of segments of any type and having one of the numbers specified in DBSL are clipped and written to the output dataset.

FILO

The name of the output file.

FTYPE

The format, or file name extension, of the output file.

Some examples of supported formats include:

PIX: PCIDSK format
TIF: Tagged Image File format
XWD: X Window Dump format

The default value is PIX.

For a complete list of GDB-recognized file types, see GDB-supported file formats.

FOPTIONS

The options to apply on creating the output file, specific to the file format. In each case, the default of no options is allowed. You can use the FOPTIONS parameter to specify compression schemes, file-format subtypes, and other information.

For more information about the options for a format, see the topic for the relevant type in GDB-supported file formats.

CLIPMETH

The method to use.

Values include:

FILE: uses the overall spatial extent associated with a specified file as the clip region
LAYERRAS: uses a raster as the clip layer
LAYERVEC: uses a vector segment as the clip layer
LAYERVEC_FILES, [<Suffix_Field>]: uses a vector segment as the clip layer and creates a separate output file for each shape. If the optional Suffix_Field is specified, it must be the name of an existing field in the provided vector segment. The names of the output files will be taken from the values in the specified field. By default, when Suffix_Field is not set explicitly, the output files will be derived from the ShapeID field.
LAYERBIT: uses a bitmap segment as the clip layer
USERCRD: uses a set of coordinates you specify

The default value is FILE.

CLIPFIL

The input file that defines the rectangular clip region, based on the georeferencing extents of the file.

You can use any GDB-supported file format. CLIPFIL can work in conjunction with the CLIPLAY parameter, depending on the defined clip method (CLIPMETH). If USERCRD is specified for the CLIPMETH parameter, this parameter is ignored.

CLIPLAY

The layer in the clip file that determines the clip region.

If for the CLIPMETH parameter you specified LAYERRAS, this parameter identifies a channel. If you specified LAYERVEC or LAYERBIT, this parameter defines a segment.

CLIPLAY is mandatory when you specify LAYERRAS, LAYERVEC, or LAYERBIT for CLIPMETH.

LAYBNDS

Specify whether to use the extents of a layer to define clip bounds, or use the boundaries of shapes defined in the layer.

Acceptable values include:

EXTENTS: Uses the extents of the input layer to define the clip boundaries.
SHAPES: Uses the boundaries of shapes specified in the input layer to define the clip boundaries.

The default value is EXTENTS.

For both accepted values, an optional parameter ALLPIXELS is supported: e.g. EXTENTS,ALLPIXELS or SHAPES,ALLPIXELS. When specified, the clipped region of any raster layers will be expanded so that all pixels intersecting the clipping layer are included in the output. The default behaviour, when ALLPIXELS is omitted, will exclude some raster pixels that have only a small amount of overlap with the clipping layer.

COORDTYP

When you specify USERCRD for the CLIPMETH parameter, use this parameter to specify the type of coordinates.

Accepted values include:

RASEXT: uses raster extents
GEOEXT: uses geocoded extents
LNGLATEX: uses longitude/latitude extents
RASOFFSZ: uses raster offset/size
GEOOFFSZ: uses geocoded offset/size

The default value is GEOEXT.

CLIPUL

The upper-left x and y coordinates of the clip region.

When you specify User-entered coordinates (USERCRD) as the value of the Clip Definition Method (CLIPMETH) parameter, you must specify a value for this parameter.

The coordinate units are based on the value specified for the Coordinate Type (COORDTYP) parameter.

CLIPLR

The lower-right x and y coordinates of the clip region.

When you specify User-entered coordinates (USERCRD) as the value of the Clip Definition Method (CLIPMETH) parameter, you must specify a value for this parameter.

The coordinate units are based on the value specified for the Coordinate Type (COORDTYP) parameter.

CLIPWH

The width and height of the clip region you have defined.

When you specify User-entered coordinates (USERCRD) as the value of the Clip Definition Method (CLIPMETH) parameter, and Raster Offset/Size or Geocoded Offset/Size for the Coordinate Type (COORDTYP) parameter, you must specify a value for this parameter.

INITVALU

The initialization value for the raster output. The full extent of the output rasters will be initialized to this value before the clipped data is written to them.

Acceptable values include any coordinate value in the projection system of the data. The default value is 0.0.

SETNODAT

Specify whether a value of "NoData" is assigned as initialization value for raster output.

If Y, the value of INITVALU is recorded as the "NoData" pixel value in the image metadata.

If N, no initialization value is set. The default value is N.

OCLIPBDY

Specify whether to generate a clip-region boundary.

If you specify Y (yes), the clip-region boundary is written to the output file. However, the boundary is written only if the output file you specified for the FILTYPE parameter can store vector data.

If you specify N (no) or do not specify a value, no boundary is generated. The default value is N.

Return Value

Returns: Execution status

Type: PCI_INT

The return value is 0. This function returns only if it executes successfully; otherwise, it throws an exception.

Details

CLIP extracts the subset of a dataset that intersects a specified spatial region–the clip region–and writes the extracted, or clipped, dataset to a new file. Only raster, vector, and bitmap layers in the original dataset are clipped. Auxiliary data types, such as PCT, LUT, or orbit segments, may be copied in their entirety to the output file. You can specify which parts of the input dataset to clip, where applicable, and, subsequently, write to the output file.

The clip-definition method determines the type of data that specifies the clip region. You must enter valid clip-region details for the selected clip definition.

You define a clip region by specifying the following:

Clip file:The overall spatial extent associated with the specified file is used as the clip region. The definition file must be smaller than the source file.
Clip layer:A specified data layer that intersects spatially the dataset to clip defines the clip region. The clip region is defined either by the overall extent of the clip layer or by the boundary of the "shapes" defined within the clip layer.

Only raster, bitmap, or vector layers can contain shapes. A raster layer must contain a thematic classification and a vector layer must contain topological polygon data for those layers to contain shapes. A shape boundary is always an extent for a point, line, unstructured vector layer, or raster (non-thematic).

The clip layer is read from a specified data file.
User-defined coordinates: Coordinates you specify that define a bounding box to use as the clip region.

The coordinates you specify are assumed to reference the input file to clip. For example, when you specify raster extents, the origin is taken from the upper-left corner of the input file.

User-defined coordinates supports many formats and can be:
- Raster extents, where the upper-left and lower-right corners are specified with pixel and line coordinates.
- Raster offset and size, where the upper-left starting point is specified as a pixel and line coordinate, and the width and height of the clip are specified in the number of pixels by the number of lines.
- Geocoded extents or geocoded offset and size are the same as for a raster, except that the units are in the coordinate type of the layers; for example, in meters or feet.
- Latitude and longitude uses extents only, and can be specified in a variety of formats. For example, all of the following strings for longitude are interpreted as 110.258333 degrees (or 110d 15' 30.00" W):
  - 110d 15' 30.00 W
  - 110d15'30.0W
  - 110 15.5' W
  - 110.258333 W
  - -110.258333
  - 110 15 30 W
  - -110 15 30
  - W 30 15' 110d
  - w 15' 30 110d

Note:

You must omit the symbol for seconds (") when specifying longitudes or latitudes; otherwise, CLIP interprets it as the end of a string; if there is a hemisphere, it is ignored.

For example:
```
CLIPUL="110d15'30"W"
```
is processed as
```
110.2583333 (instead of -110.2583333)
```
CLIPUL="110d15'30W" is processed correctly.
If you select the Set as NoData value check box, the initialization value is flagged as a 'NoData Value' in the metadata.

If you specify Y (yes) as the value of the SETNODAT parameter, the initialization value is flagged as a 'NoData Value' in the metadata.

Example

Clip the image in channel 1 of the file test.pix and copy the clipped image to a newly created PCIDSK file with the file name clip.pix. Use the shapes in vector layer 1 in clip-region.pix to define the clip region. In the output raster, use 0 as the NoData value, and write the clip-region boundary to clip.pix.

from pci.clip import clip

fili = "test.pix"
dbic = [1]
dbsl = []
sltype = ""
filo = "clip.pix"
ftype = "PIX"
foptions = ""
clipmeth = "LAYERVEC"
clipfil = "clip-region.pix"
cliplay = [1]
laybnds = "SHAPES"
coordtyp = ""
clipul = ""
cliplr = ""
clipwh = ""
initvalu = [0]
setnodat = "Y";
oclipbdy = "Y"

clip (fili, dbic, dbsl, sltype, filo, ftype, \
foptions, clipmeth, clipfil, cliplay, \
laybnds, coordtyp, clipul, cliplr, \
clipwh, initvalu, setnodat, oclipbdy )

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Return Value :: Details :: Example