GIS item JSON

Overview

The GIS Item JSON structure in Dataloop provides a comprehensive format that encapsulates all necessary data and metadata for each annotated entity within the system. This structure is designed to represent an 'Item' — a core data unit in Dataloop's platform — and its associated information for annotation purposes. Here’s a breakdown based on the provided content:

JSON Structure

Each data entity in Dataloop’s system has a dedicated JSON format that encapsulates the item’s data and metadata, enabling efficient tracking, access, and management within the platform. This JSON file is essential for exporting or downloading item annotations and can be accessed for detailed inspection or integration purposes.

GIS Item JSON Formats

Type: XYZ

XYZ is a tiled web map format that loads map tiles dynamically from a specified URL using the {z}/{x}/{y} pattern. It is commonly used for raster-based layers like OpenStreetMap (OSM) and supports zoom levels for smooth navigation. Optional layers (XYZ, OSM, COG) can be added for enhanced visualization.

{
    "shebang": "dataloop",                      //For the type of Web Map Item, it should be dataloop only and mandatory
    "metadata": {
        "dltype": "gis"                         //For the type of Web Map Item, it should be gis only and mandatory
    },
    "layer": {                                  // Representing the Tile Layer - it's a mandatory layer object
        "name": "XYZ Image",                    // User-defined name for the GIS item
        "type": "xyz",                          // Currently supporting "xyz", "osm" and "cog" types only
        "url": "https://dummy-tile.com/surveys/1723928/tiles/{z}/{x}/{y}?auth_token=fM68PVOJO8p5m2sPo4Cqdcoi4sLSsecR&datatype_name=vexcel_urban_vertical_jpg"
    },
    "optionalLayers":                           // Representing the Optional Layers array, which can have multiple layers("xyz", "osm" and "cog")
    [ 
        {
            "name": "OpenStreetMap",            // Name of the optional layer (OpenStreetMap in this case).
            "type": "osm",                      // Specifies that this optional layer is an OpenStreetMap (OSM) layer.
            "url": "",                          // URL for the optional layer (empty in this case, meaning default OSM tiles may be used).                      
            "ref": "<item_id>"                  // Reference to the item ID associated with this optional layer.
	},
        }
    ],
    "zoom":20,                                  // It's an optional zoom level, which can be between 0 to 28
    "minZoom":0,                                // It's an optional min zoom level, which can be between 0 to 28
    "maxZoom":30,                               // It's an optional max zoom level, which can be between 1 to 28
    "epsg":"4326",                              // Representing the file's Coordinate System . (3857, 3035, 4326)
    "bounds": [                                 // The coordinates that represents the (square) area within the map that the user can view, and should add/edit the annotations. I.e. the bounds where the projection is valid. Optional field.
        [-118.33559370040894, 33.82662439264756],//top left
        [-118.33497619628906, 33.82610016009953]//bottom    right
    ],
    "aoi": [                                    // Coordinates representing the Area of Interest -- The areas within the bounds of the tile layer, where I allow to create annotations. I.e. the “boarders of the canvas”. Optional field. 
        [-118.33545684814453, 33.826504880358854],
        [-118.33545684814453, 33.82621967238824],
        [-118.33511352539062, 33.82621967238824],
        [-118.33511352539062, 33.826504880358854],
        [-118.33545684814453, 33.826504880358854]
    ]
}

Field Definitions

Type: geoTiff

GeoTIFF is a raster-based GIS format that stores geospatial metadata, making it ideal for geo-referenced imagery such as satellite images and aerial photography. It can be accessed via a URL or item ID and supports different projections (EPSG: 3035, 4326, 3857) with optional overlays like OpenStreetMap for better visualization.

{
    "shebang": "dataloop",                      //For the type of Web Map Item, it should be dataloop only and mandatory
	"metadata": {
        "dltype": "gis"                         //For the type of Web Map Item, it should be gis only and mandatory
    },
    "layer": {  
        "name": "GeoTIFF Image",  // User-defined name for the main GIS layer.
        "type": "geoTiff",  // Specifies the layer type. Options: "geoTiff" (raster-based GIS format), "xyz", "osm".
        "ref": "67d14487f561d469323d8996"  // Reference ID for the GIS item stored in Dataloop. ** It can be either `ref` or `url`.
    },
    "optionalLayers": [  
        {
            "name": "OpenStreetMap",  // Name of the optional overlay layer.
            "type": "osm",  // Type of the optional layer. Can be "osm", "xyz", or "cog".
            "url": ""  // URL source for the optional layer (empty means default OSM tiles will be used).
        }
    ],
    "epsg": "4326",  // Representing the file's Coordinate System (EPSG). Currently we only support epsg 4326 (WGS84).
    "bounds": [  
        [5.046927, 51.9243133],  // Top-left coordinate of the bounding box (longitude, latitude).
        [5.126927, 51.8243163]   // Bottom-right coordinate of the bounding box (longitude, latitude). Defines the visible area where annotations can be created.
    ],
    "aoi": [  
        [5.096927, 51.8843133],  // First coordinate of the Area of Interest (AOI).
        [5.076927, 51.8843133],  // Second coordinate of the AOI polygon.
        [5.076927, 51.8643163],  // Third coordinate of the AOI polygon.
        [5.096927, 51.8643163],  // Fourth coordinate of the AOI polygon.
        [5.096927, 51.8843133]   // Closing coordinate (same as the first), forming a closed polygon. Defines the area where annotations are allowed.
    ]
}

Note: The url or ref must be provided.

Field Definitions

Note: Using either url or ref is optional.

Coordinate system and projection

Users can modify the map coordinate system and projection within the app.

• Coordinate System: Defines locations using numerical values.
• Geographic Coordinate System (GCS): Uses latitude and longitude (e.g., WGS 84 / EPSG:4326).
• Projection: Converts the Earth's curved surface into a flat map, causing some distortions.
  • Mercator – Preserves shape, distorts area.
  • Albers Equal-Area – Preserves area, distorts shape.
  • UTM – Minimizes distortion for small areas.