Cloud Optimized GeoTIFF File Sources

Martin can also serve raster sources like local COG(Cloud Optimized GeoTIFF) files. For cog on remote like S3 and other improvements, you could track them on issue 875, we are working on and welcome any assistance.

Supported colortype and bits per sample

Supported compression

• None
• LZW
• Deflate
• PackBits

Run Martin with CLI to serve cog files

# Configured with a directory containing `*.tif` or `*.tiff` TIFF files.
martin /with/tiff/dir1 /with/tiff/dir2
# Configured with dedicated TIFF file
martin /path/to/target1.tif /path/to/target2.tiff
# Configured with a combination of directories and dedicated TIFF files.
martin /with/tiff/files /path/to/target1.tif /path/to/target2.tiff

Run Martin with configuration file

keep_alive: 75

# The socket address to bind [default: 0.0.0.0:3000]
listen_addresses: '0.0.0.0:3000'

# Number of web server workers
worker_processes: 8

# Amount of memory (in MB) to use for caching tiles [default: 512, 0 to disable]
cache_size_mb: 8

# Database configuration. This can also be a list of PG configs.

cog:
  paths:
    # scan this whole dir, matching all *.tif and *.tiff files
    - /dir-path
    # specific TIFF file will be published as a cog source
    - /path/to/target1.tif
    - /path/to/target2.tiff
  sources:
    # named source matching source name to a single file
     cog-src1: /path/to/cog1.tif
     cog-src2: /path/to/cog2.tif

About COG

COG is just Cloud Optimized GeoTIFF file.

TIFF is an image file format. TIFF tags are something like key-value pairs inside to describe the metadata about a TIFF file, ike ImageWidth, ImageLength, etc.

GeoTIFF is a valid TIFF file with a set of TIFF tags to describe the ‘Cartographic’ information associated with it.

COG is a valid GeoTIFF file with some requirements for efficient reading. That is, all COG files are valid GeoTIFF files, but not all GeoTIFF files are valid COG files. For quick access to tiles in TIFF files, Martin relies on the requirements/recommendations(like the requirement about Reduced-Resolution Subfiles and the content dividing strategy) so we use the term COG over GeoTIFF in our documentation and configuration files.

You may want to visit these specs:

• TIFF 6.0
• GeoTIFF
• Cloud Optimized GeoTIFF

COG generation with GDAL

You could generate cog with gdal_translate or gdalwarp. See more details in gdal doc.

# gdal-bin installation
# sudo apt update
# sudo apt install gdal-bin

# gdalwarp
gdalwarp src1.tif src2.tif out.tif -of COG

# or gdal_translate
gdal_translate input.tif output_cog.tif -of COG

The mapping from ZXY to tiff chunk

• A single TIFF file could contains many sub-file about same spatial area, each has different resolution
• A sub file is organized with many tiles

So basically there’s a mapping from zxy to tile of sub-file of TIFF.

Clients could read only the header part of COG to figure out the mapping from zxy to the chunk number and the subfile number. Martin get tile to frontend by this mapping.