# Scalar Document

## Purpose
Represents a single numeric measurement or a small set of key/value metrics at a location or over an area (e.g., coherence mean, water level, area statistics).

## GeoJSON (DB metadata)
```json
{
  "type": "Feature",
  "geometry": {"type": "Point", "coordinates": [30.15, 59.95]},
  "properties": {
    "type": "Scalar",
    "title": "Mean Coherence",
    "created_at": "2025-09-02T12:00:00Z",
    "updated_at": "2025-09-02T12:00:00Z",
    "source": {
      "url": "/tiler/tiles/{z}/{x}/{y}@2x",
      "type": "Raster",
      "max_zoom": 16,
      "tileSize": 512,
      "url_params": {
        "url": "s3://<bucket>/<ResultKey>/<filename>"
      }
    },
    "values": {
      "coh_mean": 0.62,
      "coh_std": 0.12
    },
    "legend": {"title": "Coherence"},
    "metadata": {"window": "3x3", "sensor": "S1A"}
  }
}
```

## Required properties
- `properties.type` = `Scalar`
- `properties.source.url` and `properties.source.type`
- Either `properties.values` with inline scalars or an external JSON/CSV pointed by `properties.source.url`

## Publishing workflow
1. Produce metric values (JSON/CSV).
2. Upload payload to storage and record its URL.
3. Create a GeoJSON Feature with type `Scalar` and link via `properties.source.url`.
4. Insert/update the Feature row in the `features` table.

## Validation checklist
- Coordinates are valid (WGS84) and geometry type matches use case.
- Values are numeric and units are documented in `metadata`.
- `properties.source.type` matches the data kind.

See [Common properties](../common.md) for shared fields like legend, metadata, and classification.

## Alternate (DB-aligned) Scalar as single-band raster index
In production OCLI, many Scalar layers are delivered as single-band rasters with `bands/band_meta` and a tiler-backed `source`.

Example:
```json
{
  "type": "Feature",
  "geometry": {"type": "Polygon", "coordinates": [[[-7.5455984, 37.2931467], [-7.5487709, 37.1277062], [-7.2748512, 37.1240356], [-7.2710805, 37.2894542], [-7.5455984, 37.2931467]]]},
  "properties": {
    "type": "Scalar",
    "roles": ["demo_read", "draft_read"],
    "Bucket": "staging",
    "source": {
      "url": "/tiler/tiles/{z}/{x}/{y}@2x",
      "type": "Raster",
      "max_zoom": 20,
      "tileSize": 512,
      "url_params": {
        "url": "s3://<bucket>/<ResultKey>/<filename>"
      }
    },
    "version": 1.4,
    "Endpoint": "http://rook-ceph-rgw-geo.rook-ceph.svc:80",
    "ResultKey": "marine/faro_capella_index/faro_capella/ext_index_09gec",
    "friendly_name": "Faro/Capella/C09_GEC",
    "bands": {
      "band_ids": ["Band_0"],
      "band_meta": [
        {"band": 1, 
          "name": "Band_0", 
          "type": "UInt16", 
          "min": 1.0, 
          "max": 65535.0, 
          "domain_min": 1.0, 
          "domain_max": 65535.0, 
          "color_map": {"name": "transform_space", "type": "preset"}}
      ]
    },
    "classification": {"ocli": [5], "metadata_preset": [6]}
  }
}
```
See [Common properties](../common.md) for shared fields like legend, metadata, and classification.
See also: [GeoJSON Strategy](../../Geojson_strategy.md) and [Upload Strategy](../../Upload_strategy.md).