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",                      // Identifier indicating the system or format used, it should be dataloop only and mandatory.
	"metadata": {
		"dltype": "gis"                     // Defines the dataset type as GIS, it should be gis only and mandatory.
	},

	"layer": {                                      // Defines the primary GIS layer details.
        "name": "geoTiff image",            // Name of the layer, indicating it's a TIFF (GeoTIFF) file.
		"type": "geoTiff",                      // Specifies that this layer is of type GeoTIFF (a raster GIS format).
		"ref": "<item_id>"                      // Reference to the item ID associated with this layer. 
	},

	"optionalLayers": [                             // List of additional optional layers that can be overlaid on the main layer.
		{
            "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).
		}
	],
	"proj": "4326",                              // Specifies the projection system (EPSG:4326, which represents WGS 84, a standard coordinate system for latitude and longitude).
	"bounds": [                                  // Bounding box defining the geographic area in which the layer is valid and can be visualized.
		[5.046927, 51.9243133],                  // Top-left corner of the bounding box (longitude, latitude).
		[5.126927, 51.8243163]                   // Bottom-right corner of the bounding box (longitude, latitude).
	],
	"aoi": [                                     // Area of Interest (AOI), defining a specific region within the bounds where annotations are allowed.
		[5.096927, 51.8843133],                  // First coordinate of the AOI polygon (longitude, latitude).
		[5.076927, 51.8843133],                  // Second coordinate defining the shape of the AOI.
		[5.076927, 51.8643163],                  // Third coordinate of the AOI.
		[5.096927, 51.8643163],                  // Fourth coordinate of the AOI.
		[5.096927, 51.8843133]                   // Closing coordinate (same as the first), ensuring the polygon is closed.
	]
}

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.