GeoEco Python Reference

Previous: ToArcGISRasterArcGISTable Method Up: HDF Class Next: ToArcGISRasterTable Method

---

ToArcGISRasterList Method

Converts a Scientific Data Set (SDS) in each HDF file in a list to an ArcGIS raster.

Usage

Arguments

inputFileList

Python type:	list of unicode
Minimum length:	0

List of paths of the input HDF files.

At the time this tool was written, two major versions of HDF were under continuing development: HDF, which was at release 4.2r1, and HDF5, which was at release 5-1.6.5. This tool can process HDF files but not HDF5 files. It can also process HDF-EOS, a specialized version of HDF, but not HDF5-EOS.

For more information on HDF formats, please see http://www.hdfgroup.org.

If you provide compressed files in a supported compression format, they will be automatically decompressed. If files are compressed in an archive format (e.g. .zip or .tar), each archive must contain exactly one file, which must not be in a subdirectory.

outputRasterList

Python type:	list of unicode
Minimum length:	0

List of output rasters to create.

sdsName

Python type:	unicode
Minimum length:	1

Name of a Scientific Data Set (SDS) in the HDF file.

If you do not know the name of the SDS, provide your best guess. If an SDS does not exist with that name, a ValueError will be raised. The error message will list the names of all SDSes present in the input file. Select one of these names try again.

You can also use the Extract HDF Header tool to dump the HDF header to a text file. In this file, each SDS will be called a "variable". You can find their names by searching the file for "Variable Name =". For example, the excerpt below from MODIS SST data lists two variables, l3m_data and l3m_qual:

Variable Name = l3m_data
         Index = 0
         Type= 16-bit unsigned integer
         Ref. = 2
         Rank = 2
         Number of attributes = 4
         Dim0: Name=fakeDim0
                 Size = 4320
                 Scale Type = number-type not set
                 Number of attributes = 0
         Dim1: Name=fakeDim1
                 Size = 8640
                 Scale Type = number-type not set
                 Number of attributes = 0
         Attr0: Name = Scaling
                 Type = 8-bit signed char
                 Count= 7
                 Value = linear\\000
         Attr1: Name = Scaling Equation
                 Type = 8-bit signed char
                 Count= 47
                 Value = (Slope*l3m_data) + Intercept = Parameter
                         value\\000
         Attr2: Name = Slope
                 Type = 32-bit floating point
                 Count= 1
                 Value = 0.000717
         Attr3: Name = Intercept
                 Type = 32-bit floating point
                 Count= 1
                 Value = -2.000000

Variable Name = l3m_qual
         Index = 1
         Type= 8-bit unsigned integer
         Ref. = 4
         Rank = 2
         Number of attributes = 1
         Dim0: Name=fakeDim2
                 Size = 4320
                 Scale Type = number-type not set
                 Number of attributes = 0
         Dim1: Name=fakeDim3
                 Size = 8640
                 Scale Type = number-type not set
                 Number of attributes = 0
         Attr0: Name = valid_range
                 Type = 32-bit signed integer
                 Count= 2
                 Value = 0 2

This tool extracts the HDF SDS to an ArcInfo ASCII Grid and converts it to a raster using the ArcGIS ASCII to Raster geoprocessing tool. That tool and the ArcGIS raster format have several limitations that constrain the kinds of SDSes that may be successfully converted to ArcGIS raster format.

SDSes that use the float or double data type must not contain "infinity" (INF) or "not a number" (NAN) values. A ValueError will be raised if these values are discovered.

The ArcGIS raster format supports the 32-bit float data type but not the 64-bit double data type. If you supply an SDS with the double data type, it will be converted to a 32-bit float raster using the ArcGIS ASCII to Raster geoprocessing tool. The tool's behavior in this situation is not documented. In ArcGIS 9.1 it appears to be:

• Values where the exponent ranges from -38 to +38 are properly represented in the resulting 32-bit float raster, although some precision is lost due to the smaller mantissa of the 32-bit float data type.
• Values where the exponent is less than -38 (e.g. -39, -40, and so on) are converted to 0.
• Values where the exponent is greater than +38 are converted to -INF or +INF, depending on the sign of the value (e.g. -5.3083635279597874e-212 appears as -1.#INF in the ArcCatalog GUI, while 2.5502286890301497e+084 appears as 1.#INF).

The ArcGIS 9.1 ASCII to Raster tool also exhibits some quirks when converting integer rasters:

• For 8-bit signed integer data, the tool will create a 16-bit raster if the value -128 appears, unless -128 is designated the NODATA value. Specifying a different NODATA value, such as 0, still yields 16-bit raster if -128 appears.
• Similarly, for 16-bit signed integer data, the tool will create a 32-bit raster if the value -32768 appears in the ASCII file, unless it is designated the NODATA value.
• Worse, for 32-bit signed integer data, the tool will report an error if the value -2147483648 appears unless it is designated the NODATA value. Even stranger, the value -2147483647 is always translated to NODATA, no matter what.
• For all types of integer data, the tool produces strange behavior when you specify a NODATA value that is not the smallest possible value for the data type. For example, if the data range from 0 to 255 and 0 is designated the NODATA value, the tool produces an 8-bit unsigned integer raster. But if 1 is designated the NODATA value, it produces a 16-bit raster, and ArcCatalog shows under Raster Dataset Properties that the NoData Value is -32768, although the Identify tool shows cells that had value 1 are actually NODATA. Similar strange results can be obtained for integer rasters of other data types, when you designate a NODATA that is not the smallest possible value.

xLowerLeftCorner

Python type:

float

X coordinate of the lower-left corner of the raster.

The coordinate is for the corner of the lower-left cell, not the center of that cell. For example, if the raster is a geographic projection of the entire Earth, the coordinate of the lower left corner would be -180.0, corresponding to a longitude of 180 degrees West.

yLowerLeftCorner

Python type:

float

Y coordinate of the lower-left corner of the raster.

The coordinate is for the corner of the lower-left cell, not the center of that cell. For example, if the raster is a geographic projection of the entire Earth, the coordinate of the lower left corner would be -90.0, corresponding to a latitude of 90 degrees South.

cellSize

Python type:

float

Size of each raster cell.

For example, if the raster is a geographic projection of the entire Earth, with 720 columns and 360 rows, it would have a cell size of 0.5, corresponding to 1/2 of a geographic degree.

The underlying data format requires the cells be square. It is not possible to specify a cell size for each dimension.

nodataValue

Python type:	float or None
Default value:	None

Value that indicates a cell has no data.

transpose

Python type:	bool
Default value:	False

If True, the image will be transposed (flipped about the diagonal axis) prior to conversion. Use this option to fix an image that has the east/west axis going up and down instead of left and right.

mirror

Python type:	bool
Default value:	False

If True, the image will be flipped about the vertical axis prior to conversion. Use this option to fix an image that is the "mirror image" of what it is supposed to be.

flip

Python type:	bool
Default value:	False

If True, the image will be flipped about the horizontal axis prior to conversion. Use this option to fix an image that is upside-down.

swapHemispheres

Python type:	bool
Default value:	False

If True, the east and west hemispheres of the image will be swapped. Use this option to change the orientation of a global image from a 0 to 360 orientation centered on the Pacific ocean to a -180 to +180 orientation centered on the Atlantic ocean, or visa versa.

coordinateSystem

Python type:	unicode or None
Default value:	None
Minimum length:	1

Coordinate system to define for the raster.

If a value is not provided, the coordinate system of the raster will remain undefined.

projectedCoordinateSystem

Python type:	unicode or None
Default value:	None
Minimum length:	1

New coordinate system to project the raster to.

The raster may only be projected to a new coordinate system if the original projection is defined. An error will be raised if you specify a new coordinate system without defining the original coordinate system.

The ArcGIS Project Raster tool is used to perform the projection. The documentation for that tool recommends that you also specify a cell size for the new coordinate system.

I have noticed that for certain coordinate systems the ArcGIS 9.2 Project Raster tool seems to clip the projected raster to an arbitrary extent that is too small. For example, when projecting a global MODIS Aqua 4 km chlorophyll image in geographic coordinates to Lambert_Azimuthal_Equal_Area with central meridian of -60 and latitude of origin of -63, the resulting image is clipped to show only one-quarter of the planet. This problem does not occur when Project Raster is invoked interactively from the ArcGIS user interface; it only occurs when the tool is invoked programmatically (the ProjectRaster_management method of the geoprocessor). Thus you may not see it when you use Project Raster yourself but it may happen when you use MGET tools that invoke Project Raster as part of their geoprocessing operations.

If you encounter this problem, you can work around it like this:

• First, run this tool without specifying a new coordinate system, to obtain the raster in the original coordinate system.
• In ArcCatalog, use the Project Raster tool to project the raster to the new coordinate system. Verify that the entire raster is present, that it has not been clipped to an extent that is too small.
• In ArcCatalog, look up the extent of the projected raster by right-clicking on it in the catalog tree, selecting Properties, and scrolling down to Extent.
• Now, before running the MGET tool that projects the raster, set the Extent environment setting to the values you looked up. If you are invoking the MGET tool interactively from ArcCatalog or ArcMap, click the Environments button on the tool's dialog box, open General Settings, change the Extent drop-down to "As Specified Below", and type in the values you looked up. If you're invoking it from a geoprocessing model, right-click on the tool in the model, select Make Variable, From Environment, General Settings, Extent. This will place Extent as a variable in your model, attached to the MGET tool. Open the Extent variable, change it to "As Specified Below" and type in the values you looked up. If you're invoking the MGET tool programmatically, you must set the Extent property of the geoprocessor to the values you looked up. Please see the ArcGIS documentation for more information about this and Environment settings in general.
• Run the MGET tool. The extent of the raster should now be the proper size.

geographicTransformation

Python type:	unicode or None
Default value:	None
Minimum length:	1

A transformation method used to convert between the original coordinate system and the new coordinate system.

This parameter is a new option introduced by ArcGIS 9.2. You must have ArcGIS 9.2 to use this parameter.

This parameter is only needed when you specify that the raster should be projected to a new coordinate system and that new system uses a different datum than the original coordinate system, or there is some other difference between the two coordinate systems that requires a transformation. To determine if a transformation is needed, I recommend the following procedure:

• First, run this tool without specifying a new coordinate system, to obtain the raster in the original coordinate system.
• Next, use the ArcGIS 9.2 Project Raster tool on the raster to project it to the desired coordinate system. If a geographic transformation is needed, that tool will prompt you for one. Write down the exact name of the transformation you used.
• Finally, if a transformation was needed, type in the exact name into this tool, rerun it, and verify that the raster was projected as you desired.

resamplingTechnique

Python type:	unicode or None
Default value:	None
Allowed values:	u'NEAREST', u'BILINEAR', u'CUBIC'

The resampling algorithm to be used to project the original raster to a new coordinate system. The ArcGIS Project Raster tool is used to perform the projection and accepts the following values:

• NEAREST - nearest neighbor interpolation
• BILINEAR - bilinear interpolation
• CUBIC - cubic convolution

You must specify one of these algorithms to project to a new coordinate system. An error will be raised if you specify a new coordinate system without selecting an algorithm.

projectedCellSize

Python type:	float or None
Default value:	None

The cell size of the projected coordinate system. Although this parameter is optional, to receive the best results, the ArcGIS documentation recommends you always specify it when projecting to a new coordinate system.

registrationPoint

Python type:	unicode or None
Default value:	None
Minimum length:	1
Must match regular expression:	([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)

The x and y coordinates (in the output space) used for pixel alignment.

This parameter is a new option introduced by ArcGIS 9.2. You must have ArcGIS 9.2 to use this parameter. It is ignored if you do not specify that the raster should be projected to a new coordinate system.

clippingRectangle

Python type:	unicode or None
Default value:	None
Minimum length:	1
Must match regular expression:	([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)

Rectangle to which the raster should be clipped.

If a projected coordinate system was specified, the clipping is performed after the projection and the rectangle's coordinates should be specified in the new coordinate system. If no projected coordinate system was specified, the coordinates should be specified in the original coordinate system.

The ArcGIS Clip tool is used to perfom the clip. The clipping rectangle must be passed to this tool as a string of four numbers separated by spaces. The ArcGIS user interface automatically formats the string properly; when invoking this tool from the ArcGIS UI, you need not worry about the format. But when invoking it programmatically, take care to provide a properly-formatted string. The numbers are ordered LEFT, BOTTOM, RIGHT, TOP. For example, if the raster is in a geographic coordinate system, it may be clipped to 10 W, 15 S, 20 E, and 25 N with the string:

10 15 20 25

Integers or decimal numbers may be provided.

mapAlgebraExpression

Python type:	unicode or None
Default value:	None
Minimum length:	1
Maximum length:	4000

Map algebra expression to execute on the raster.

WARNING: The ArcGIS Geoprocessing Model Builder may randomly and silently delete the value of this parameter. This is a bug in ArcGIS. Before running a model that you have saved, open this tool and validate that the parameter value still exists.

The expression is executed after the converted raster is projected and clipped (if those options are specified). Use the case-sensitive string inputRaster to represent the raster that you now want to perform map algebra upon. For example, to convert the raster to an integer raster and add 1 to all of the cells, use this expression:

int(inputRaster) + 1

The string inputRaster is case-sensitive. Prior to executing the map algebra expression, the string is replaced with the path to a temporary raster that represents the raster being generated. The final expression must be less than 4000 characters long or ArcGIS will report an error.

The ArcGIS Single Output Map Algebra tool is used to execute the map algebra expression. You must have a license for the ArcGIS Spatial Analyst extension in order to perform map algebra.

Map algebra syntax can be very picky. Here are some tips that will help you succeed with this tool:

• Before using this tool, construct and test out your map algebra expression using the ArcGIS Single Output Map Algebra tool. Then paste the expression into this tool and edit it to use the inputRaster variable rather than the test value you used with Single Output Map Algebra.
• If you do develop your expression directly in this tool, start with a very simple expression. Verify that it works properly, add a little to it, and verify again. Repeat this process until you have built up the complete expression.
• Always separate mathematical operators from raster paths using spaces. In the example above, the / operator contains a space on either side. Follow this pattern. In some circumstances, ArcGIS will fail to process raster algebra expressions that do not separate raster paths from operators using spaces. The reported error message usually does not indicate that this is the problem, and tracking it down can be very frustrating.

buildPyramids

Python type:	bool
Default value:	False

If True, pyramids will be built for the raster, which will improve its display speed in the ArcGIS user interface.

skipExisting

Python type:	bool
Default value:	False

If True, processing will be skipped for rasters that already exist.

overwriteExisting

Python type:	bool
Default value:	False

If True and skipExisting is False, existing rasters will be overwritten.

basePath

Python type:	unicode or None
Default value:	None
Minimum length:	1
Maximum length:	255
Must exist:	No

Base path to prepend to relative paths.

If any of the input paths (or output paths, if this method has outputs) contained in the lists are relative paths, they will be converted to absolute paths prior to processing, as follows:

• If a base path is provided, it will be prepended to the relative path.
• Otherwise, if the ArcGIS geoprocessor has been initialized and the geoprocessing workspace has been set (i.e. the Workspace property of the geoprocessor is not empty), it will be prepended to the relative path.
• Otherwise, the current working directory for the executing process will be prepended to the path. If you have not explicitly changed the working directory, it is usually the directory that contains the Python interpreter (e.g., on Windows computers, it would be C:Python24, if you're running Python 2.4).

---

GeoEco Python Reference

Previous: ToArcGISRasterArcGISTable Method Up: HDF Class Next: ToArcGISRasterTable Method

---

Marine Geospatial Ecology Tools version 0.8