Scalar-map data contract

Experimental implementation reference · 19 September 2026. This describes the current repository tools and pilot, not a released stable SDK or an OSDU schema. The current scalar-map repository is the ArrayBridge project service. OSDU raster mapping and storage qualification remain separate work.

Storage, exchange and host objects

ResInsight EclipseContourMap
  -> numerical X/Y/value export + explicit scientific metadata
  -> ExternalSnapshot(kind="scalar-map") / ExternalScalarMap
  -> project-scoped SharedAsset and immutable publication revision
  -> original portable bundle -> optional derived CRS representation
  -> QGIS raster + locally generated contour layer

A connector includes capture, identity mapping, publication/recovery, credentials and host integration. An adapter implements a narrower boundary such as reading ResInsight’s API, translating a scientific type, or applying prepared layers through QGIS. A scalar-map transfer does not reproduce the native reservoir model, solver state, faults or hidden editing history.

Three different revision identifiers

Identifier	Meaning
Source revision / fingerprint	Version or digest of the captured external input
Project asset revision	Server-assigned publication order for a project-scoped asset
Bundle / representation revision	Content identity for a particular portable conversion result

Never compare these as though they were the same sequence. Cache by service/project/asset, exact publication revision and representation policy. A new representation of publication 13 must not be confused with publication 14.

Numerical contract

proto/arraybridge.proto defines ExternalScalarMap: width, height, first_x, first_y, positive step_x and step_y, row-major values, metadata_json, and preserved source_text. Columns increase in X; rows decrease in Y. Samples become raster pixel centers. Values are Float64, finite or NaN for missing; infinities are rejected. JSON metadata must not contain non-finite numbers.

The importer accepts complete, regular, axis-aligned grids with at least two samples per axis. Duplicate coordinates, missing rows and irregular spacing are errors, not invitations to interpolate. The text header declares dimensions with # sampling points: nx=N ny=M. Preserve explicit missing values and the source’s sampling topology; a vertex-to-pixel representation does not preserve all native topology.

Required metadata fields are asset_id, property, unit, coordinate_unit, crs_status, source_kind, source_revision and operation. crs_status is unknown, source-declared or verified. A CRS definition is present exactly when status is not unknown. Known coordinate units must match the CRS. Scalar units remain separate.

For reprojection, also provide value_kind (continuous, categorical or elevation). Elevation requires vertical_reference with datum, unit, direction (up or down) and status (source-declared or verified). The vertical unit must match the scalar unit. A declaration is not independent verification.

Portable bundle formats

Format	Files	Meaning
arraybridge.scalar-map/1	source.txt, map.tif, manifest.json	Original numerical export, Float64 raster and identity/meaning/integrity record
arraybridge.scalar-map-representation/1	map.tif, manifest.json	Derived raster, source references and explicit transformation record

The original manifest records metadata, source digest, converter version, grid shape/transform, missing-value count and file hashes. The derived manifest adds source_bundle_revision, source_raster_sha256, source_metadata, normalized policy, coordinate_operation, axis_convention, vertical_operation, and losses. Its metadata describes the delivered coordinates; source_metadata preserves the original claim.

The derived manifest references the original bundle; it does not embed that bundle. Preserve both for complete exit and provenance. SHA-256 verification detects changes relative to a manifest; it is not a digital signature or proof that the source’s scientific claims are true.

Explicit representation policy

{
  "target_crs": "EPSG:3857",
  "resolution": 100,
  "resampling": "nearest"
}

These are the three accepted input keys. Resolution is positive and measured in target coordinate units. The implementation normalizes the CRS and includes PROJ, GDAL, Rasterio, PyProj and EPSG database versions in policy identity. Axis handling is explicit: array coordinates use X/Y (longitude/latitude or easting/northing); the GDAL operation handles authority axis order separately.

Reprojection is horizontal only, within the same geodetic CRS, with no ballpark datum fallback or vertical shift. Categorical maps require nearest neighbor. Target-area and finite-output checks reject unsupported extents. Both source and output are bounded to 100,000 pixels; output dimensions are bounded to 8,192. GDAL uses one warp thread and a 64 MiB warp working-memory setting; this is not a total process-memory cap. The original importer has a separate one-million-sample limit.

Implementation authorities: tools/scalar_maps/bundle.py, spatial.py, project_maps.py and proto/arraybridge.proto. Run the CLI · Publication and reads.