Skip to content

Builder API

Jump to bottom
Karishma Chandnani edited this page Aug 5, 2022 · 7 revisions
Clone this wiki locally

The builder class is used to build the raster products and the items to be added to a mosaic dataset.

The name of the builder class must be the same as what is defined in the Raster Type definition for a raster type as returned by the RasterTypeFactory.getRasterTypesInfo method.

The builder class must contain the following methods:

__init__(self, **kwargs)

This method is used to initialize the builder class.

Arguments

kwargs is a dictionary that contains additional information required to construct an item.

It contains a key called rasterTypeInfo whose value is a dictionary containing basic information specific to the raster type like the raster type name etc. It also contains the auxiliary inputs key-value pairs defined in the RasterTypeFactory class. If the raster type supports orthorectification, the orthorectifictaion parameters (eg - DEM, ZFactor) are also added to the dictionary.

Returns

None

canOpen(self, datasetPath)

This method, if defined, is used to indicate whether the builder class recognizes a given dataset and if its capable of building an item from the provided dataset.

Arguments

datasetPath is the full path to the file that represents the main dataset file. This can be the file that contains pixel data or contains metadata and references external pixel data. Typical examples of files that contain metadata and reference external pixel data is data that is distributed as Sensor Datasets - examples include Landsat, Worldview, SPOT etc.

Returns

A boolean value indicating whether the builder identifies the dataset pointed to by datasetPath or not.

build(self, itemURI)

This method is used to construct builder item(s) which consists of the dataset, metadata, footprint etc.

Arguments

itemURI is a dictionary which contains a list of parameters which can be used to construct a given dataset. If the raster type has a crawler class defined, then itemURI is a dictionary returned by the next method of the crawler. The dictionary will contain the following items:

  • path String - The URI to the resource that should be built; for file based datasets, this will be the path to the metadata file
  • tag String - This is a comma separated string of tags for the items to be built. If a 'Crawler' class is defined that can crawl a data source container and return URI's, then tag contains a single tag returned by the crawler as part of the itemURI dictionary. For more information on what the crawler returns, please refer to the Crawler API documentation. If a crawler is not defined, then tag contains all the tags that are defined.
  • displayName String - The name of the file that is displayed in various user interface controls.
  • productName String - The product type of the item.
  • groupName String - The name of the collection group to which the item belongs.
  • uriProperties Dictionary - The properties of the item URI.

Returns

A list of dictionaries. Each dictionary describes a builder item.
The properties of a builder item are described below:

Required properties of a builder item

  • raster

    Dictionary

    This property will be used to construct the builder item's raster dataset. This dataset can be function raster dataset (FRD) or a simple raster dataset.

    If it is a single dataset the raster dictionary should contain a key called uri and its value should be the path to corresponding dataset.

    If it is a FRD, the raster dictionary should contain a key called functionDataset. functionDataset is a dictionary which contains the following members

    • rasterFunction (string) - path to raster function template persisted in xml form
    • rasterFunctionArguments (dictionary) - this dictionary contains the names and values of unresolved dataset variables.

    When adding a large number of rasters to a mosaic, the python raster type framework supports a 'quick open' mechanism where if the developer provides all the required raster info for the input rasters, the input rasters will not be opened. This speeds up the Add Rasters process.

    The rasterInfo can be specified as part of the raster dictionary if its a single dataset. If its a FRD, the raster info can be specified in the rasterFunctionArguments dictionary. If the variable name for a dataset is "Raster", its raster info should be provided under the key name "Raster_rasterInfo". The required properties of the raster info dictionary are as follows:

The geodataXform is an optional property of the rasterInfo. Please see documentation below to see how to specify the Xform.

Optional properties of a builder item

  • itemURI

    dictionary

    The itemURI dictionary contains the path, tag, displayName and groupName property. This should be the same itemURI passed to the build function as argument.

  • spatialReference

    This property is used to define the spatial reference of the dataset. The SRS can be returned in one of the following forms:

    • arcpy.spatialReference object
    • EPSG code (of type 'int')
    • PRJ/WKT string
    • Path to a PRJ file

    If the spatial reference is not specified, the default spatial reference of the builder item's raster is used.

  • footprint

    arcpy.geometry or a list

    arcpy.geometry polygon object or a list of [X,Y] coordinates representing the footprint of the dataset. Example of a list of coordinates is [[x1, y1], [x2, y2], [x3, y3], [x4, y4]…]. When the footprint geometry is a coordinate list, the SRS of the geometry is the same as the 'spatialReference' item of the returned dictionary.

    If the builder item footprint is not specified, the extent of the raster is used as the footprint.

  • variables

    dictionary

    This dictionary contains key-value pairs which will be used to resolve the raster function variables in the raster's function chain.

    Default variables that can be used to set statistics - 'DefaultMinimumInput', 'DefaultMaximumInput' and 'DefaultGamma'.

  • keyProperties

    dictionary

    This dictionary contains key-value pairs representing metadata to be set on the builder item's dataset.

    In addition to the dataset level key properties, this dictionary can contain a key called bandProperties whose value will be a list of dictionaries, each dictionary containing band specific key properties of a single band.

    Each band dictionary can optionally contain a key called statistics whose value will be a dictionary containing minimum(double), maximum (double), mean(double), standardDeviation(double), skipFactorX(double), skipFactorY(double). These band statistics will be set on the FRD constructed from the builder item.

    Some of the well known dataset level key properties and band properties are documented here.

  • noData

    list

    The list contains one value per raster band representing NoData. The NoData values are set on the bands of the function raster dataset constructed by the builder item.

  • geodataXform

    string

    This is a JSON array containing the Geodata transformation objects.

    'GeodataTransforms': [
  {
   "geodataTransform" : "<geodataTransformName1>",
   "geodataTransformArguments" : {<geodataTransformArguments1>}
  },
  {
   "geodataTransform" : "<geodataTransformName2>",
   "geodataTransformArguments" : {<geodataTransformArguments2>}
  }
 ]

    The JSON representations of the supported Geodata Transformation objects are documented here.

    Rational Polynomial Coefficients

    In addition to the Geodata Transformation objects listed above, RPC transformation object can be specified using the following JSON:

    { 
  "geodataTransform" : 'RPC',
  "geodataTransformArguments" : {'coeff' : [comma separated coefficients]}
}

    The Rational Polynomial Coefficients are packed in an array of 90 double values in the following order:

    0     - LINE_OFF
1     - SAMPLE_OFF
2     - LAT_OFF
3     - LONG_OFF
4     - HEIGHT_OFF
5     - LINE_SCALE
6     - SAMP_SCALE
7     - LAT_SCALE
8     - LONG_SCALE
9     - HEIGHT_SCALE
10-29 - LINE_NUM_COEFF_1, ..., LINE_NUM_COEFF_20
30-49 - LINE_DEN_COEFF_1, ..., LINE_DEN_COEFF_20
50-69 - SAMP_NUM_COEFF_1, ..., SAMP_NUM_COEFF_20
70-89 - SAMP_DEN_COEFF_1, ..., SAMP_DEN_COEFF_20