ECW -- ERDAS Compress Wavelets (.ecw)

GDAL supports .ecw format for read access and write. The current implementation reads any number of bands but returns only as eight bit image data. Coordinate system and georeferencing transformations are read, but in some cases coordinate systems may not translate.

Support for the ECW driver in GDAL is optional, and requires linking in external ECW SDK libraries provided by Intergraph (previously ERDAS).

In addition to ECW files, this driver also supports access to network image services using the "ECWP" protocol. Use the full ecwp:// url of the service as the dataset name. When built with SDK 4.1 or newer it is also possible to take advantage of RFC 24 style asynchronous access to ECWP services.

Starting with GDAL 1.9.0, XMP metadata can be extracted from JPEG2000 files, and will be stored as XML raw content in the xml:XMP metadata domain.

ECW metadata domain / Georeferencing update

(Starting with GDAL 1.9.0)

The PROJ, DATUM and UNITS found in the ECW header are reported in the ECW metadata domain. They can also be set with the SetMetadataItem() method, in order to update the header information of an existing ECW file, opened in update mode, without modifying the imagery.

The geotransform and projection can also be modified with the SetGeoTransform() and SetProjection() methods. If the projection is set with SetProjection() and the PROJ, DATUM or UNITS with SetMetadataItem(), the later values will override the values built from the projection string.

ECW Version 3 Files

(Starting with GDAL 1.10.0)

ECW 5.x SDK provides amended file format which allows to store data statistics, histograms, metadata, rpc metadata and supports UInt16 as band data type. Currently not everything is implemented:

Statistics and Histograms - full implementation for writing and reading. No ECW_OEM_KEY neccessary.
File Metadata - read only support. Statistics will also be preserved/updated during CreateCopy.
RPC Metadata - supported by file format, not supported by driver.
Header Metadata - written by SDK itself. Reported by gdalinfo.

File Metadata Keys:

FILE_METADATA_ACQUISITION_DATE
FILE_METADATA_ACQUISITION_SENSOR_NAME
FILE_METADATA_ADDRESS
FILE_METADATA_AUTHOR
FILE_METADATA_CLASSIFICATION
FILE_METADATA_COMPANY - should be set to ECW_OEM_KEY
FILE_METADATA_COMPRESSION_SOFTWARE - updated during recompression
FILE_METADATA_COPYRIGHT
FILE_METADATA_EMAIL
FILE_METADATA_TELEPHONE

Following Header Metadata will be reported:

CLOCKWISE_ROTATION_DEG
COLORSPACE (reported for V2 files as well)
COMPRESSION_DATE
COMPRESSION_RATE_ACTUAL
COMPRESSION_RATE_TARGET (reported for V2 files as well)
VERSION (reported for V2 files as well)

Creation Issues

The ECW 4.x SDK from ERDAS is only free for image decompression. To compress images it is necessary to build with the read/write SDK and to provide an OEM licensing key at runtime which may be purchased from ERDAS.

For those still using the ECW 3.3 SDK, images less than 500MB may be compressed for free, while larger images require licensing from ERDAS. See the licensing agreement and the LARGE_OK option.

Files to be compressed into ECW format must also be at least 128x128. ECW currently only supports 8 bits per channel for ECW Version 2 files. ECW Version 3 files supports 16 bits per channel (as Uint16 data type). Please see Creation options to enable ECW V3 files writing

When writing coordinate system information to ECW files, many less common coordinate systems are not mapped properly. If you know the ECW name for the coordinate system you can force it to be set at creation time with the PROJ and DATUM creation options.

Creation Options:

TARGET=percent: Set the target size reduction as a percentage of the original. If not provided defaults to 90% for greyscale images, and 95% for RGB images.
PROJ=name: Name of the ECW projection string to use. Common examples are NUTM11, or GEODETIC.
DATUM=name: Name of the ECW datum string to use. Common examples are WGS84 or NAD83.
UNITS=name: (GDAL >= 1.9.0) Name of the ECW projection units to use : METERS (default) or FEET (us-foot).
LARGE_OK=YES: When built with the ECW 3.x SDK this option can be set to allow compressing files larger than 500MB. It is the users responsibility to ensure that the licensing requirments for large file compression are being adhered to.
ECW_ENCODE_KEY=key: Provide the OEM encoding key purchased from Erdas which permits encoding images. The key is is approximately 129 hex digits long. It may also be provided globally as a configuration option.
ECW_ENCODE_COMPANY=name: Provide the name of the company ERDAS issued the OEM encoding key (see ECW_ENCODE_KEY) to. This must exactly match the name used by ERDAS in issuing the OEM key. It may also be provided globally as a configuration option.
ECW_FORMAT_VERSION=2/3: (GDAL >= 1.10.0) When build with the ECW 5.x SDK this option can be set to allow ECW Version 3 files to be created. This would allow to write UInt16 data type rasters (new feature of ECW Version 3 files) . Default is 2 which will write ECW Version 2 files.

ECW format does not support creation of overviews since the ECW format is already considered to be optimized for "arbitrary overviews".

Configuration Options

The ERDAS ECW SDK supports a variety of runtime configuration options to control various features. Most of these are exposed as GDAL configuration options. See the ECW SDK documentation for full details on the meaning of these options.

ECW_CACHE_MAXMEM=bytes: maximum bytes of RAM used for in-memory caching. If not set, up to one quarter of physical RAM will be used by the SDK for in-memory caching.
ECWP_CACHE_LOCATION=path: Path to a directory to use for caching ECWP results. If unset ECWP caching will not be enabled.
ECWP_CACHE_SIZE_MB=number_of_megabytes: The maximum number of megabytes of space in the ECWP_CACHE_LOCATION to be used for caching ECWP results.
ECWP_BLOCKING_TIME_MS: time an ecwp:// blocking read will wait before returning - default 10000 ms.
ECWP_REFRESH_TIME_MS: time delay between blocks arriving and the next refresh callback - default 10000 ms. For the purposes of GDAL this is the amount of time the driver will wait for more data on an ecwp connection for which the final result has not yet been returned. If set small then RasterIO() requests will often produce low resolution results.
ECW_TEXTURE_DITHER=TRUE/FALSE: This may be set to FALSE to disable dithering when decompressing ECW files. Defaults to TRUE.
ECW_FORCE_FILE_REOPEN=TRUE/FALSE: This may be set to TRUE to force open a file handle for each file for each connection made. Defaults to FALSE.
ECW_CACHE_MAXOPEN=number: The maximum number of files to keep open for ECW file handle caching. Defaults to unlimited.
ECW_RESILIENT_DECODING=TRUE/FALSE: Controls whether the reader should be forgiving of errors in a file, trying to return as much data as is available. Defaults to TRUE. If set to FALSE an invalid file will result in an error.
ECW_ENCODE_KEY, ECW_ENCODE_COMPANY: These values, as described in the creation options, may also be set as configuration options. See above.