Guide to: Running a Tiled Image Annotation Job

Overview 

The new tiled image annotation tool allows users to request annotation of tiled imagery data according to a custom ontology. If you would like to set up a tiled image annotation job, please contact your Customer Success Manager. 

Figure 1: Preview of Tiled Image Annotation Tool 

The tiled image annotation tool enables contributors to annotate Slippy Map tiles of the earth at various zoom levels. A ‘Slippy Map’ is a modern web map that allows users to zoom and pan to display different parts of the map at different levels of resolution. 

In order to use the tiled image annotation tool, the map data must already be converted into map tiles and hosted using a tile server.  

Building a Job 

CML

Currently, there is no Graphical Editor support for this tool. Here is sample CML to build the job:

Parameters 

Below are the parameters available for the tiled image annotation tool. Some are required in the element, while others are optional. 

• type
  • This parameter allows you to add various types of annotation modes to the tool, including “box”, “polygon”, “line”, and "dot".
• source-data
  • The column from your source data that contains the URLs to the hosted XYZ image tiles. The URLs must be in the following format: https://c.tile.openstreetmap.org/{z}/{x}/{y}.png. 
  • To add multiple tile layers, supply an array containing the URLs in the following format: 
    • [{“url”: “https://...”, “name”: “Layer1”}, {“url”: “https://...”, “name”: “Layer2”, “options”: {“max_zoom”: 20}}] 
  • See below for additional information about using source-data with Cloud-Optimized GeoTiff (COG) files.
  • The following options can be configured independently for each layer: min_zoom, max_zoom, max_native_zoom, min_native_zoom, subdomains 

Figure 2. Contributors will be able to toggle between layers in the tool. 

• canvas-options
  • The column from your source data that contains canvas configuration options.  
  • The following options can be configured independently for each data row:  
    • center (required): the latitude-longitude coordinates at the map center upon tool load 
    • zoom (required): the initial map zoom level upon tool load 
    • maxZoom: the maximum zoom level of the map 
    • minZoom: the minimum zoom level of the map 
    • maxBounds: When this option is set, the map restricts the view to the given geographical bounds. Supply the bottom-left and top-right latitude-longitude coordinates of the rectangular boundary region. 
  • Provide configuration options for each data row as an object with the following format: 
    • {"center":[30.3321,-81.6556],"zoom":11,"min_zoom":4,"max_zoom":18,"max_bounds":[[30.074618,-81.959666],[30.509033,-81.41833]]} 

• name
•  
  • The results header where annotations will be stored. 

• label
•  
  • The question label the contributors will see. 

• validates
•  
  • Whether or not this element is required to be answered. 
  • Accepts 'required' 
  • Defaults to not required if not present 

• review-data 
  • This will read in existing annotations. For this job type, they will need to be URLs or refs, each linked to the annotation file for the original annotation task. 

GeoTiff support

The tiled image annotation tool supports loading Cloud-Optimized GeoTIFF (COG) files remotely. 

• GeoTIFF files are split into bands, each of which has a matrix of data values. The tool can either display a single band of values by mapping the values to a specified color map (e.g. grayscale). Or, three bands can be provided, representing red, green, and blue, which results in a true-color visualization.
• To configure GeoTIFF support, set the source-data parameter. Below is an example configuration in which Layer 1 displays a single band, Layer 2 displays RGB using separate band files, and Layer 3 displays RGB using a single file containing multiple bands.
  Possible values for colormap can be found here.

source_data Format Guide

Option 1: Simple URL String (Auto-Detection)

When source_data is a plain URL string, the type is auto detected by file extension:

// GeoTIFF - extensions: .tif, .tiff, .gtiff, .cog
source_data: 'https://example.com/image.tif'

// NITF - extension: .nitf
source_data: 'https://example.com/image.nitf'

// Tile Layer - any other URL (treated as tile server)
source_data: 'https://example.com/tiles/{z}/{x}/{y}.png'

Option 2: JSON Array of Layers

For more control, use a JSON array. Each layer type has different required/optional properties.

GeoTIFF / COG Layer

source_data: JSON.stringify([
  {
    layer_type: 'geotiff',  // or 'cog'
    name: 'Layer Name',     // Required: display name
    url: 'https://...',     // Required: URL to the tiff file
    
    // Optional properties:
    index: 1,               // Band index (1-based), default: 1
    resolution: 256,        // Tile resolution, default: 256
    min_value: 0,           // Min value for normalization
    max_value: 255,         // Max value for normalization
    empty_value: 0,         // NoData/empty value
    colormap: 'viridis',    // Colormap name (for single-band)
  }
])

Multi-band as separate layers:

source_data: JSON.stringify([
  {
    layer_type: 'geotiff',
    name: 'Band 1 - Red',
    url: 'https://example.com/multiband.tif',
    index: 1,
  },
  {
    layer_type: 'geotiff',
    name: 'Band 2 - Green',
    url: 'https://example.com/multiband.tif',
    index: 2,
  },
  {
    layer_type: 'geotiff',
    name: 'Band 3 - Blue',
    url: 'https://example.com/multiband.tif',
    index: 3,
  },
])

Note: RGB files with exactly 3 bands are automatically rendered as RGB when no index is specified.

NITF Layer

source_data: JSON.stringify([
  {
    layer_type: 'nitf',
    name: 'NITF Image',
    url: 'https://example.com/image.nitf',  // Required
  }
])

Note: NITF layers auto-calculate center from corner coordinates if canvas_options.center is not set.

Tile Layer

source_data: JSON.stringify([
  {
    layer_type: 'tiles',  // or omit layer_type
    name: 'Base Map',
    url: 'https://example.com/{z}/{x}/{y}.png',  // Required
    
    // Optional layer options:
    options: {
      min_zoom: 0,
      max_zoom: 18,
      min_native_zoom: 0,
      max_native_zoom: 18,
    }
  }
])

canvas_options Format

canvas_options: JSON.stringify({
  center: [lat, lng],           // Required for tiles, optional for geotiff/nitf
  zoom: 10,                     // Initial zoom level
  min_zoom: 2,                  // Minimum zoom allowed
  max_zoom: 20,                 // Maximum zoom allowed
  max_bounds: [                 // Optional: restrict panning
    [south, west],
    [north, east]
  ],
})
 

Customizable Hotkeys

• Hotkeys can be assigned to classes by the user. Hotkeys cannot conflict with any other browser or tool shortcuts.

Ontology 

Ontology is mandatory for a tiled image annotation job. Similar to our other image annotation tools, you will be able to create a customized ontology with 4 levels maximum of nesting. 

Please see this article for more information on the Ontology Manager. 

Output Format 

The tiled image annotation tool output is in standard GeoJSON format. See below for an example: 

output-tiled-imagery.json 

Additional Notes 

This product is in BETA, so please consider the following important notes: 

1. The job must be set-up in the Code Editor; the tool is not supported in the Graphical Editor yet. 

1. Tiled image annotation jobs do not support test questions or aggregation at this stage. As a result, aggregated reports are not supported at this stage. 

1. Launching this type of job requires one of our trusted tiled image annotation contributor channels. Please reach out to your Customer Success Manager to set this up.