# ISIS3 -- USGS Astrogeology ISIS Cube (Version 3)

Driver short name

ISIS3

Driver built-in by default

This driver is built-in by default

ISIS3 is a format used by the USGS Planetary Cartography group to store and distribute planetary imagery data. GDAL provides read/creation/update access to ISIS3 formatted imagery data.

ISIS3 files often have the extension .cub, sometimes with an associated .lbl (label) file. When a .lbl file exists it should be used as the dataset name rather than the .cub file. The driver also supports imagery stored in a separate GeoTIFF file.

In addition to support for most ISIS3 imagery configurations, this driver also reads georeferencing and coordinate system information as well as selected other header metadata.

A mask band is attached to each source band. The value of this mask band is 0 when the pixel value is the NULL value or one of the low/high on-instrument/processed saturation value, or 255 when the pixel value is valid.

Implementation of this driver was supported by the United States Geological Survey.

ISIS3 is part of a family of related formats including PDS and ISIS2.

## Driver capabilities

Supports CreateCopy()

This driver supports the `GDALDriver::CreateCopy()` operation

Supports Create()

This driver supports the `GDALDriver::Create()` operation

Supports Georeferencing

This driver supports georeferencing

Supports VirtualIO

This driver supports virtual I/O operations (/vsimem/, etc.)

## Metadata

The ISIS3 label can be retrieved as JSON-serialized content in the json:ISIS3 metadata domain.

For example:

    $ python 3
    from osgeo import gdal
    ds = gdal.Open('../autotest/gdrivers/data/isis3_detached.lbl')
    print(ds.GetMetadata_List('json:ISIS3')[0])
    {
      "IsisCube":{
        "_type":"object",
        "Core":{
          "_type":"object",
          "StartByte":1,
          "^Core":"isis3_detached.cub",
          "Format":"BandSequential",
          "Dimensions":{
            "_type":"group",
            "Samples":317,
            "Lines":30,
            "Bands":1
          },
          "Pixels":{
            "_type":"group",
            "Type":"UnsignedByte",
            "ByteOrder":"Lsb",
            "Base":0.000000,
            "Multiplier":1.000000
          }
        },
        "Instrument":{
          "_type":"group",
          "TargetName":"Mars"
        },
        "BandBin":{
          "_type":"group",
          "Center":1.000000,
          "OriginalBand":1
        },
        "Mapping":{
          "_type":"group",
          "ProjectionName":"Equirectangular",
          "CenterLongitude":184.412994,
          "TargetName":"Mars",
          "EquatorialRadius":{
            "value":3396190.000000,
            "unit":"meters"
          },
          "PolarRadius":{
            "value":3376200.000000,
            "unit":"meters"
          },
          "LatitudeType":"Planetographic",
          "LongitudeDirection":"PositiveWest",
          "LongitudeDomain":360,
          "MinimumLatitude":-14.822815,
          "MaximumLatitude":-14.727503,
          "MinimumLongitude":184.441132,
          "MaximumLongitude":184.496521,
          "UpperLeftCornerX":-4766.964984,
          "UpperLeftCornerY":-872623.628822,
          "PixelResolution":{
            "value":10.102500,
            "unit":"meters\/pixel"
          },
          "Scale":{
            "value":5864.945312,
            "unit":"pixels\/degree"
          },
          "CenterLatitude":-15.147000,
          "CenterLatitudeRadius":3394813.857978
        }
      },
      "Label":{
        "_type":"object",
        "Bytes":65536,
      },
      "History":{
        "_type":"object",
        "Name":"IsisCube",
        "StartByte":1,
        "Bytes":957,
        "^History":"r0200357_10m_Jul20_o_i3_detatched.History.IsisCube",
        "_data": {
           "ASCII" : "[...snip...]"
        },
      },
      "OriginalLabel":{
        "_type":"object",
        "Name":"IsisCube",
        "StartByte":1,
        "Bytes":2482,
        "^OriginalLabel":"r0200357_10m_Jul20_o_i3_detatched.OriginalLabel.IsisCube",
        "_data": {
           "HEX" : "0102[...snip...]"
        },
      }
    }

or

    $ gdalinfo -json ../autotest/gdrivers/data/isis3_detached.lbl -mdd all

On creation, a source template label can be passed to the SetMetadata() interface in the "json:ISIS3" metadata domain.

## Creation support

The ISIS3 driver supports updating imagery of existing datasets, creating new datasets through the CreateCopy() and Create() interfaces.

When using CreateCopy(), gdal_translate or gdalwarp, an effort is made to preserve as much as possible of the original label when doing ISIS3 to ISIS3 conversions. This can be disabled with the USE_SRC_LABEL=NO creation option.

Creation options can be specified in command-line tools using the syntax `-co <NAME>=<VALUE>` or by providing the appropriate arguments to `GDALCreate()` (C) or `Driver.Create` (Python). The available creation options are:

- DATA_LOCATION=[LABEL​/​EXTERNAL​/​GEOTIFF.]: Defaults to `LABEL`. To specify the location of pixel data. The default value is LABEL, ie imagery immediately follows the label. If using EXTERNAL, the imagery is put in a raw file whose filename is the main filename with a .cub extension. If using GEOTIFF, the imagery is put in a separate GeoTIFF file, whose filename is the main filename with a .tif extension.

- GEOTIFF_AS_REGULAR_EXTERNAL=[YES​/​NO]: Defaults to `YES`. Whether the GeoTIFF file, if uncompressed, should be registered as a regular raw file. Defaults to YES, so as to maximize the compatibility with earlier version of the ISIS3 driver.

- GEOTIFF_OPTIONS=value: Comma separated list of KEY=VALUE tuples to forward to the GeoTIFF driver. e.g. `GEOTIFF_OPTIONS=COMPRESS=LZW`.

- EXTERNAL_FILENAME=[<filena​/​e>]: Override default external filename. Only for DATA_LOCATION=EXTERNAL or GEOTIFF.

- TILED=[YES​/​NO]: Defaults to `NO`. Whether the pixel data should be tiled. Default is NO (ie band sequential organization).

- BLOCKXSIZE=value: Defaults to `256`. Tile width in pixels. Only used if `TILED=YES`.

- BLOCKYSIZE=value: Defaults to `256`. Tile height in pixels. Only used if `TILED=YES`.

- COMMENT=value: Comment to add into the label.

- LATITUDE_TYPE=[Planetocentric​/​Planetographic]: Defaults to `Planetocentric`. Value of Mapping.LatitudeType. If specified, and `USE_SRC_MAPPING` is in effect, this will be taken into account to override the source LatitudeType.

- LONGITUDE_DIRECTION=[PositiveEast​/​PositiveWest]: Defaults to `PositiveEast`. Value of Mapping.LongitudeDirection. If specified, and `USE_SRC_MAPPING` is in effect, this will be taken into account to override the source LongitudeDirection.

- TARGET_NAME=value: Value of Mapping.TargetName. This is normally deduced from the SRS datum name. If specified, and `USE_SRC_MAPPING` is in effect, this will be taken into account to override the source TargetName.

- FORCE_360=[YES​/​NO]: Defaults to `NO`. Whether to force longitudes in the [0, 360] range.

- WRITE_BOUNDING_DEGREES=[YES​/​NO]: Defaults to `YES`. Whether to write Min/MaximumLong/ Latitude values.

- BOUNDING_DEGREES=<min_long,min_lat,max_long,max_lat>: Manually set bounding box (values will not be modified by `LONGITUDE_DIRECTION` or `FORCE_360` options).

- USE_SRC_LABEL=[YES​/​NO]: Defaults to `YES`. Whether to use source label in ISIS3 to ISIS3 conversions.

- USE_SRC_MAPPING=[YES​/​NO]: Defaults to `NO`. Whether to use Mapping group from source label in ISIS3 to ISIS3 conversions. Defaults to NO (that is to say that the content of Mapping group will be created from new dataset geotransform and projection). Only used if `USE_SRC_LABEL=YES`

- USE_SRC_HISTORY=[YES​/​NO]: Defaults to `YES`. Whether to use the content pointed by the source History object in ISIS3 to ISIS3 conversions, and write it to the new dataset. Only used if `USE_SRC_LABEL=YES`. If `ADD_GDAL_HISTORY` and `USE_SRC_HISTORY` are set to YES (or unspecified), a new history section will be appended to the existing history.

- ADD_GDAL_HISTORY=[YES​/​NO]: Defaults to `YES`. Whether to add GDAL specific history in the content pointed by the History object in ISIS3 to ISIS3 conversions. Only used if `USE_SRC_LABEL=YES`. If `ADD_GDAL_HISTORY` and `USE_SRC_HISTORY` are set to YES (or unspecified), a new history section will be appended to the existing history. When `ADD_GDAL_HISTORY=YES`, the history is normally composed from current GDAL version, binary name and path, host name, user name and source and target filenames. It is possible to completely override it by specifying the `GDAL_HISTORY` option.

- GDAL_HISTORY=value: Manually defined GDAL history. Must be formatted as ISIS3 PDL. If not specified, it is automatically composed. Only used if `ADD_GDAL_HISTORY=YES` (or unspecified).

## Open options

Added in version 3.12.

Open options can be specified in command-line tools using the syntax `-oo <NAME>=<VALUE>` or by providing the appropriate arguments to `GDALOpenEx()` (C) or `gdal.OpenEx` (Python). The available open options are:

- INCLUDE_OFFLINE_CONTENT=[YES​/​NO]: Defaults to `YES`. Whether to include a `_data` member in `json:ISIS3` metadata with offline content of label objects. Defaults to YES

- MAX_SIZE_OFFLINE_CONTENT=<integer>: Defaults to `1000000000`. Maximum size of offline content to include in `_data` member, in bytes.

## Examples

How to create a copy of a source ISIS3 dataset to another ISIS3 dataset while modifying a parameter of IsisCube.Mapping group, by using GDAL Python :

    import json
    from osgeo import gdal

    src_ds = gdal.Open('in.lbl')
    # Load source label as JSON
    label = json.loads( src_ds.GetMetadata_List('json:ISIS3')[0] )
    # Update parameter
    label["IsisCube"]["Mapping"]["TargetName"] = "Moon"

    # Instantiate new raster
    # Note the USE_SRC_MAPPING=YES creation option, since we modified the
    # IsisCube.Mapping section, which otherwise is completely rewritten from
    # the geotransform and projection attached to the output dataset.
    out_ds = gdal.GetDriverByName('ISIS3').Create('out.lbl',
                                                  src_ds.RasterXSize,
                                                  src_ds.RasterYSize,
                                                  src_ds.RasterCount,
                                                  src_ds.GetRasterBand(1).DataType,
                                                  options = ['USE_SRC_MAPPING=YES'])
    # Attach the modified label
    out_ds.SetMetadata( [json.dumps(label)], 'json:ISIS3' )

    # Copy imagery (assumes that each band fits into memory, otherwise a line-by
    # line or block-per-block strategy would be more appropriate )
    for i in range(src_ds.RasterCount):
        out_ds.GetRasterBand(1).WriteRaster( 0, 0,
                                            src_ds.RasterXSize,
                                            src_ds.RasterYSize,
                                            src_ds.GetRasterBand(1).ReadRaster() )
    out_ds = None
    src_ds = None

## See Also

- Implemented as isis3dataset.cpp.

- GDAL PDS Driver

- GDAL ISIS2 Driver