micarrsim/schemas/result.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://micarrsim.local/schemas/result.schema.json",
  "title": "micarrsim simulation result",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion", "kind", "experimentId", "arrayId", "sceneId", "createdAt", "backend",
    "inputHash", "signalStats", "timingMs", "bands"
  ],
  "properties": {
    "schemaVersion": { "const": "1.0.0" },
    "kind": { "const": "micarrsim.result" },
    "experimentId": { "type": "string", "minLength": 1 },
    "arrayId": { "type": "string", "minLength": 1 },
    "sceneId": { "type": "string", "minLength": 1 },
    "createdAt": { "type": "string", "format": "date-time" },
    "backend": { "enum": ["cpu", "webgpu"] },
    "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
    "signalStats": {
      "type": "object", "additionalProperties": false,
      "required": ["preNormalizationPeak", "appliedScale", "clippedSampleCount"],
      "properties": {
        "preNormalizationPeak": { "type": "number", "minimum": 0 },
        "appliedScale": { "type": "number", "minimum": 0 },
        "clippedSampleCount": { "type": "integer", "minimum": 0 }
      }
    },
    "timingMs": {
      "type": "object", "additionalProperties": false, "required": ["total", "beamforming"],
      "properties": {
        "total": { "type": "number", "minimum": 0 },
        "signalGeneration": { "type": "number", "minimum": 0 },
        "beamforming": { "type": "number", "minimum": 0 }
      }
    },
    "environment": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } },
    "bands": {
      "type": "array", "minItems": 1, "maxItems": 8,
      "items": { "$ref": "#/$defs/bandResult" }
    }
  },
  "$defs": {
    "position": {
      "type": "array",
      "prefixItems": [{ "type": "number" }, { "type": "number" }, { "type": "number" }],
      "items": false, "minItems": 3, "maxItems": 3
    },
    "map": {
      "type": "object", "additionalProperties": false,
      "required": ["rows", "columns", "scale", "values"],
      "properties": {
        "rows": { "type": "integer", "minimum": 1, "maximum": 512 },
        "columns": { "type": "integer", "minimum": 1, "maximum": 512 },
        "scale": { "enum": ["power", "normalized", "db"] },
        "values": {
          "type": "array", "minItems": 1, "maxItems": 262144,
          "items": { "type": "number" }
        }
      }
    },
    "peak": {
      "type": "object", "additionalProperties": false,
      "required": ["position", "value"],
      "properties": {
        "sourceId": { "type": "string", "minLength": 1 },
        "position": { "$ref": "#/$defs/position" },
        "value": { "type": "number", "minimum": 0 },
        "beamSpread": { "$ref": "#/$defs/beamSpread" },
        "localizationErrorM": { "type": "number", "minimum": 0 },
        "localizationErrorPixels": { "type": "number", "minimum": 0 }
      }
    },
    "beamSpread": {
      "type": "object", "additionalProperties": false,
      "required": [
        "calibrated", "method", "halfPowerRatio", "thresholdValue", "pixelCount",
        "centroid", "covarianceM2", "ellipse"
      ],
      "properties": {
        "calibrated": { "const": false },
        "method": { "const": "connected-half-power-power-weighted-covariance" },
        "halfPowerRatio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
        "thresholdValue": { "type": "number", "minimum": 0 },
        "pixelCount": { "type": "integer", "minimum": 0, "maximum": 262144 },
        "centroid": { "$ref": "#/$defs/position" },
        "covarianceM2": {
          "type": "object", "additionalProperties": false,
          "required": ["xx", "xy", "yy"],
          "properties": {
            "xx": { "type": "number", "minimum": 0 },
            "xy": { "type": "number" },
            "yy": { "type": "number", "minimum": 0 }
          }
        },
        "ellipse": {
          "type": "object", "additionalProperties": false,
          "required": [
            "axisScale", "angleReference", "majorRmsRadiusM", "minorRmsRadiusM", "angleDeg"
          ],
          "properties": {
            "axisScale": { "const": "rms" },
            "angleReference": { "const": "counterclockwise-from-positive-x" },
            "majorRmsRadiusM": { "type": "number", "minimum": 0 },
            "minorRmsRadiusM": { "type": "number", "minimum": 0 },
            "angleDeg": { "type": "number", "minimum": -180, "maximum": 180 }
          }
        }
      }
    },
    "evaluation": {
      "type": "object", "additionalProperties": false,
      "required": [
        "version", "truthRadiusM", "matchToleranceM", "detectionThresholdRatio",
        "detectionThresholdValue", "minimumPeakDistanceM", "sidelobeExclusionRadiusM",
        "halfPowerRatio", "dynamicRangeDb", "maximumDetections"
      ],
      "properties": {
        "version": { "const": "1.0.0" },
        "truthRadiusM": { "type": "number", "minimum": 0 },
        "matchToleranceM": { "type": "number", "minimum": 0 },
        "detectionThresholdRatio": { "type": "number", "minimum": 0, "maximum": 1 },
        "detectionThresholdValue": { "type": "number", "minimum": 0 },
        "minimumPeakDistanceM": { "type": "number", "minimum": 0 },
        "sidelobeExclusionRadiusM": { "type": "number", "minimum": 0 },
        "halfPowerRatio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
        "dynamicRangeDb": { "type": "number", "minimum": 0 },
        "maximumDetections": { "type": "integer", "minimum": 1, "maximum": 128 }
      }
    },
    "processedMap": {
      "type": "object", "additionalProperties": false, "required": ["algorithm", "map"],
      "properties": {
        "algorithm": { "enum": ["damas", "clean-sc", "custom"] },
        "map": { "$ref": "#/$defs/map" }
      }
    },
    "bandResult": {
      "type": "object", "additionalProperties": false,
      "required": ["id", "color", "rawMap", "peaks", "metrics"],
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
        "rawMap": { "$ref": "#/$defs/map" },
        "displayMap": { "$ref": "#/$defs/map" },
        "evaluation": { "$ref": "#/$defs/evaluation" },
        "processedMaps": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/processedMap" } },
        "peaks": { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/peak" } },
        "metrics": {
          "type": "object", "additionalProperties": false,
          "properties": {
            "peakToSidelobeDb": { "type": "number" },
            "energyInsideTruthRatio": { "type": "number", "minimum": 0, "maximum": 1 },
            "precision": { "type": "number", "minimum": 0, "maximum": 1 },
            "recall": { "type": "number", "minimum": 0, "maximum": 1 },
            "mainLobeWidthM": { "type": "number", "minimum": 0 }
          }
        }
      }
    }
  }
}