# 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 ERDAS.

## 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. Non-eight bit source data will be rescaled by the ECW SDK in some manner that I don't understand ... the resulting image is effectively eight bit.

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.

- 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 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.

- 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.

## See Also:

- Implemented as `gdal/frmts/ecw/ecwdataset.cpp`.
- ECW SDK available at erdas.com.
- GDAL ECW Build Hints