odc.geo.cog.write_cog

odc.geo.cog.write_cog(geo_im, fname, *, overwrite=False, blocksize=None, ovr_blocksize=None, overviews=None, overview_resampling=None, overview_levels=None, use_windowed_writes=False, intermediate_compression=False, tags=None, nodata='auto', **extra_rio_opts)[source]

Save xarray.DataArray to a file in Cloud Optimized GeoTiff format.

Parameters:

  • geo_im (DataArray) – xarray.DataArray with crs

  • fname (Union[str, Path]) – Output path or ":mem:" in which case compress to RAM and return bytes

  • overwrite (bool) – True – replace existing file, False – abort with IOError exception

  • blocksize (Optional[int]) – Size of internal tiff tiles (512x512 pixels)

  • ovr_blocksize (Optional[int]) – Size of internal tiles in overview images (defaults to blocksize)

  • overviews (Optional[Iterable[DataArray]]) – Write pre-computed overviews if supplied

  • overview_resampling (Optional[str]) – Use this resampling when computing overviews

  • overview_levels (Optional[List[int]]) – List of shrink factors to compute overiews for: [2,4,8,16,32], to disable overviews supply empty list []

  • nodata (Union[float, int, str, None, Literal['auto']]) – Set nodata flag to this value if supplied, by default nodata is read from the attributes of the input array (geo_im.odc.nodata).

  • use_windowed_writes (bool) – Write image block by block (might need this for large images)

  • intermediate_compression (Union[bool, str, Dict[str, Any]]) – Configure compression settings for first pass write , default is no compression

  • tags (Optional[Dict[str, Any]]) – Dictionary of tags to write into the output file. These are written as GDAL Metadata items in the GeoTIFF file.

  • extra_rio_opts – Any other option is passed to rasterio.open

Return type:

Union[Path, bytes]

Returns:

Path to which output was written

Returns:

Bytes if fname=":mem:"

Note

memory requirements

This function generates a temporary in memory tiff file without compression to speed things up. It then adds overviews to this file and only then copies it to the final destination with requested compression settings. This is necessary to produce a compliant COG, since the COG standard demands overviews to be placed before native resolution data and double pass is the only way to achieve this currently.

This means that this function will use about 1.5 to 2 times memory taken by geo_im.