Skip to content

Add max_z_error parameter for lossy LERC compression#1513

Merged
brendancol merged 1 commit intoxarray-contrib:mainfrom
brendancol:lerc-max-z-error
May 7, 2026
Merged

Add max_z_error parameter for lossy LERC compression#1513
brendancol merged 1 commit intoxarray-contrib:mainfrom
brendancol:lerc-max-z-error

Conversation

@brendancol
Copy link
Copy Markdown
Contributor

Closes #1510.

LERC takes a maxZErr argument: 0.0 is lossless, larger values let the encoder approximate within that bound. The codec wrapper in _compression.py already accepted it, but every writer above it hard-coded 0.0, so there was no way to ask for a lossy LERC write from the public API.

to_geotiff now takes max_z_error: float = 0.0 and threads it through the eager write, the dask streaming write, the VRT path, the COG/overview path, and every helper that calls lerc_compress.

Validation runs up front in to_geotiff:

  • max_z_error < 0 raises ValueError.
  • max_z_error != 0 with any codec other than 'lerc' raises ValueError, so a non-zero budget never gets silently dropped.
  • max_z_error != 0 on the GPU writer raises ValueError. nvCOMP has no LERC backend.

Tests in a new test_lerc_max_z_error.py cover: bit-exact lossless round-trip at 0.0; 0.05 on a smooth float32 surface yields a strictly smaller file with abs(decoded - original) <= 0.05 everywhere; dask streaming with a non-zero budget; negative values and non-LERC codecs raising ValueError; and max_z_error=0.0 with zstd still working (the default must not break other codecs).

Test plan

  • pytest xrspatial/geotiff/tests/test_lerc_max_z_error.py -v (6 passed)
  • pytest xrspatial/geotiff/tests/test_lerc.py -v (13 passed)
  • pytest xrspatial/geotiff/tests/ (673 passed, 4 skipped). Three matplotlib TestPalette recursion errors reproduce on origin/main and are unrelated.

LERC takes a maxZErr argument: 0.0 is lossless, larger values let the
encoder approximate within that bound. The codec wrapper already
accepted it, but every writer above it hard-coded 0.0.

to_geotiff now takes max_z_error and threads it through the eager
write, the dask streaming write, the VRT path, the COG/overview path,
and every helper that calls lerc_compress.

Validation runs up front in to_geotiff:
- max_z_error < 0 raises ValueError.
- max_z_error != 0 with any codec other than 'lerc' raises ValueError.
- max_z_error != 0 on the GPU writer raises ValueError (nvCOMP has no
  LERC backend).

Closes xarray-contrib#1510.
@github-actions github-actions Bot added the performance PR touches performance-sensitive code label May 7, 2026
@brendancol brendancol merged commit 3b22166 into xarray-contrib:main May 7, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

performance PR touches performance-sensitive code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

to_geotiff has no way to set LERC max_z_error

1 participant