@deepblend/dsh-blender-contracts 0.1.0

package/lib/schemas/scene-spec.schema.json

@@ -0,0 +1,791 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://deepblend.local/schemas/scene-spec.schema.json",
+  "title": "DeepBlend SceneSpec v1",
+  "description": "The structural source of truth for one DeepBlend scene (SPEC §8.1: 'SceneSpec 场景结构事实来源'). A .blend file is a compile artifact of this document, never the authority. Scenes are compiled from a SceneSpec and modified only through ScenePatch operations, so that every revision is diffable, replayable and auditable.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "project",
+    "entities",
+    "cameras",
+    "renderProfiles"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "deepblend.scene/v1"
+    },
+    "project": {
+      "$ref": "#/$defs/project"
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/asset"
+      }
+    },
+    "materials": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/material"
+      }
+    },
+    "entities": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/entity"
+      }
+    },
+    "lights": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/light"
+      }
+    },
+    "cameras": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/camera"
+      }
+    },
+    "shots": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/shot"
+      }
+    },
+    "animationTracks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/animationTrack"
+      }
+    },
+    "renderProfiles": {
+      "$ref": "#/$defs/renderProfiles"
+    },
+    "world": {
+      "$ref": "#/$defs/world"
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-zA-Z][a-zA-Z0-9._-]*$"
+    },
+    "world": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The scene's environment illumination: what fills every gap the geometry does not cover. This is the BACKGROUND a viewer sees behind the product, and `color`/`strength` are exactly Blender's World Background node. Omitting the whole block is legal and means the values below, which used to be a constant buried in the compiler (`deepblend_scene.py`) and were therefore unreachable from a SceneSpec: a brief asking for a black background could be honoured only by accident, with a backdrop plane, and any camera that saw past that plane found the hidden grey. An explicit black background is `{\"color\": [0, 0, 0, 1], \"strength\": 0}`.",
+      "properties": {
+        "color": {
+          "$ref": "#/$defs/unitColor",
+          "default": [0.02, 0.021, 0.026, 1]
+        },
+        "strength": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1000,
+          "default": 0.6
+        }
+      }
+    },
+    "vec3": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "type": "number"
+      }
+    },
+    "unitColor": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 4,
+      "items": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "description": "Linear RGB (3) or RGBA (4). Values are scene-linear, not sRGB display values."
+    },
+    "positiveNumber": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "nonNegativeNumber": {
+      "type": "number",
+      "minimum": 0
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "fps",
+        "frameStart",
+        "frameEnd",
+        "aspectRatio"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "goal": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "The operator's natural-language brief. Retained verbatim for audit; it never affects compilation."
+        },
+        "units": {
+          "type": "string",
+          "enum": [
+            "metric",
+            "imperial"
+          ],
+          "default": "metric"
+        },
+        "fps": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 240
+        },
+        "frameStart": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "frameEnd": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "aspectRatio": {
+          "type": "string",
+          "pattern": "^[0-9]+:[0-9]+$",
+          "description": "Informational for M1. Resolution is owned by the render profiles."
+        },
+        "activeCamera": {
+          "type": "string",
+          "description": "Camera id the animation is seen through. The active-camera view of a view plan renders this one; when absent the first declared camera is used."
+        }
+      }
+    },
+    "license": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "commercialUse": {
+          "type": "boolean"
+        },
+        "attribution": {
+          "type": "string",
+          "maxLength": 500
+        }
+      }
+    },
+    "asset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "type",
+        "path"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "glb",
+            "gltf",
+            "fbx",
+            "obj",
+            "usd",
+            "blend"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Project-relative POSIX path. Absolute paths and any '..' segment are rejected by the path guard (SPEC §15.2)."
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "license": {
+          "$ref": "#/$defs/license"
+        }
+      }
+    },
+    "proceduralTexture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "scale"
+      ],
+      "description": "A procedural surface texture. A material with only scalar parameters renders as one flat colour, which is what makes paper, wood and glazed ceramic all read as plastic; this block adds the surface relief and variation that distinguishes them. It is built as a real node graph (texture coordinate -> mapping -> pattern -> bump / roughness / base colour), not a baked image, so it needs no asset ingest and stays resolution-independent.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "noise",
+            "wave",
+            "voronoi"
+          ]
+        },
+        "scale": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Pattern density in object space. Larger is finer."
+        },
+        "detail": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 16
+        },
+        "distortion": {
+          "type": "number",
+          "minimum": 0
+        },
+        "stretch": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          },
+          "description": "Per-axis multiplier on the mapping, so a grain can run along one direction (wood) instead of being isotropic."
+        },
+        "bump": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Strength of the normal perturbation. 0 leaves the surface smooth."
+        },
+        "roughnessVariation": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "How far the pattern swings roughness around its authored value, which is what breaks a highlight up instead of letting it read as plastic."
+        },
+        "colorVariation": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "How strongly the pattern darkens the base colour."
+        }
+      }
+    },
+    "material": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "shader"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "shader": {
+          "type": "string",
+          "enum": [
+            "principled",
+            "emission",
+            "glass"
+          ]
+        },
+        "parameters": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "baseColor": {
+              "$ref": "#/$defs/unitColor"
+            },
+            "metallic": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "roughness": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "ior": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "maximum": 5
+            },
+            "alpha": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "emissionColor": {
+              "$ref": "#/$defs/unitColor"
+            },
+            "emissionStrength": {
+              "$ref": "#/$defs/nonNegativeNumber"
+            },
+            "coatWeight": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "transmissionWeight": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        },
+        "texture": {
+          "$ref": "#/$defs/proceduralTexture"
+        }
+      }
+    },
+    "transform": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "location": {
+          "$ref": "#/$defs/vec3"
+        },
+        "rotationEuler": {
+          "$ref": "#/$defs/vec3",
+          "description": "Radians, XYZ Euler order, matching bpy's rotation_euler."
+        },
+        "scale": {
+          "$ref": "#/$defs/vec3"
+        }
+      }
+    },
+    "generator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "shape"
+      ],
+      "description": "Procedural proxy geometry. M1 has no asset-ingest action yet, so fixtures build their hero objects from generators; asset-instance entities take over as the primary path once blender_asset_ingest lands (SPEC §11).",
+      "properties": {
+        "shape": {
+          "type": "string",
+          "enum": [
+            "cube",
+            "uv_sphere",
+            "cylinder",
+            "cone",
+            "plane",
+            "torus",
+            "rounded_box"
+          ]
+        },
+        "size": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "radius": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "depth": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "segments": {
+          "type": "integer",
+          "minimum": 3,
+          "maximum": 512
+        },
+        "ringCount": {
+          "type": "integer",
+          "minimum": 3,
+          "maximum": 512
+        },
+        "majorRadius": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "minorRadius": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "bevel": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "width": {
+              "$ref": "#/$defs/positiveNumber"
+            },
+            "segments": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 16
+            }
+          }
+        }
+      }
+    },
+    "entity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "asset-instance",
+            "generator",
+            "empty"
+          ]
+        },
+        "assetId": {
+          "type": "string",
+          "description": "Required when type is asset-instance."
+        },
+        "generator": {
+          "$ref": "#/$defs/generator"
+        },
+        "materialId": {
+          "type": "string",
+          "description": "Material applied to this entity's generated mesh."
+        },
+        "transform": {
+          "$ref": "#/$defs/transform"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 64
+          }
+        },
+        "locked": {
+          "type": "boolean",
+          "description": "A locked entity may still be patched explicitly, but the orchestrator must not propose changes to it autonomously (SPEC §12)."
+        },
+        "visible": {
+          "type": "boolean"
+        }
+      }
+    },
+    "light": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "area",
+            "point",
+            "spot",
+            "sun"
+          ]
+        },
+        "transform": {
+          "$ref": "#/$defs/transform"
+        },
+        "energy": {
+          "$ref": "#/$defs/nonNegativeNumber"
+        },
+        "color": {
+          "$ref": "#/$defs/unitColor"
+        },
+        "size": {
+          "$ref": "#/$defs/positiveNumber",
+          "description": "area: light radius; point/spot: shadow soft size."
+        },
+        "spotSize": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 3.14159265358979
+        },
+        "spotBlend": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "angle": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 3.14159265358979
+        }
+      }
+    },
+    "camera": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "active-camera",
+            "three-quarter",
+            "top",
+            "detail"
+          ],
+          "description": "What this camera is FOR. A view plan assigns roles to cameras by name (active camera, 45-degree, top-down, subject close-up) and falls back to declaration order, so a role is what makes a multi-view plan reproducible rather than positional."
+        },
+        "lens": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "sensorWidth": {
+          "$ref": "#/$defs/positiveNumber"
+        },
+        "clipping": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "$ref": "#/$defs/positiveNumber"
+          }
+        },
+        "transform": {
+          "$ref": "#/$defs/transform",
+          "description": "Camera position. When `targetEntityId` or `targetPoint` is present the rotation is DERIVED by aiming -Z at the target, so a hand-written rotationEuler is ignored (and is reported as a validation notice)."
+        },
+        "targetEntityId": {
+          "type": "string"
+        },
+        "targetPoint": {
+          "$ref": "#/$defs/vec3"
+        },
+        "fStop": {
+          "$ref": "#/$defs/positiveNumber"
+        }
+      }
+    },
+    "shot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "cameraId"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "cameraId": {
+          "type": "string"
+        },
+        "frameRange": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 1000
+        }
+      }
+    },
+    "animationKeyframe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "frame",
+        "value"
+      ],
+      "properties": {
+        "frame": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "value": {
+          "type": "number"
+        },
+        "interpolation": {
+          "type": "string",
+          "enum": [
+            "constant",
+            "linear",
+            "bezier",
+            "ease_in",
+            "ease_out",
+            "ease_in_out"
+          ]
+        }
+      }
+    },
+    "animationTrack": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "targetEntityId",
+        "property",
+        "keyframes"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "targetKind": {
+          "type": "string",
+          "enum": ["entity", "camera", "material"],
+          "default": "entity",
+          "description": "What `targetEntityId` names: an entity (default), a camera, or a material. Only entity tracks existed before, which is why \"the camera orbits the product\" and \"the dial lights up\" both had to be faked with entity transforms."
+        },
+        "targetEntityId": {
+          "type": "string",
+          "description": "The id of the target named by `targetKind`. The field name says Entity because every track written before target kinds existed used it and revisions are immutable; renaming it would make r0001-r0023 unreadable. Resolution is against the collection `targetKind` names, which matters because ids are unique per collection, not globally."
+        },
+        "property": {
+          "type": "string",
+          "enum": [
+            "location.x",
+            "location.y",
+            "location.z",
+            "rotationEuler.x",
+            "rotationEuler.y",
+            "rotationEuler.z",
+            "scale.x",
+            "scale.y",
+            "scale.z",
+            "emissionStrength",
+            "roughness",
+            "metallic",
+            "ior",
+            "alpha",
+            "coatWeight",
+            "transmissionWeight",
+            "baseColor.r",
+            "baseColor.g",
+            "baseColor.b",
+            "emissionColor.r",
+            "emissionColor.g",
+            "emissionColor.b"
+          ],
+          "description": "The channel to animate. Transform channels apply to entities and cameras; material parameters apply to materials and use the same names `material.parameter.update` takes."
+        },
+        "keyframes": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "$ref": "#/$defs/animationKeyframe"
+          }
+        }
+      }
+    },
+    "renderProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "engine",
+        "resolution"
+      ],
+      "properties": {
+        "engine": {
+          "type": "string",
+          "enum": [
+            "eevee",
+            "cycles",
+            "workbench"
+          ]
+        },
+        "resolution": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "integer",
+            "minimum": 16,
+            "maximum": 16384
+          }
+        },
+        "samples": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8192
+        },
+        "filmTransparent": {
+          "type": "boolean"
+        },
+        "raytracing": {
+          "type": "boolean",
+          "description": "EEVEE only: enable the raytracing pipeline (screen-space GI, ambient occlusion and reflections). EEVEE defaults this OFF, which renders every surface lit only by direct light - objects lose their contact shadow and appear to float. Ignored by engines that have no such switch."
+        },
+        "colorManagement": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "viewTransform": {
+              "type": "string",
+              "enum": [
+                "Standard",
+                "AgX",
+                "Filmic",
+                "False Color",
+                "Raw"
+              ]
+            },
+            "look": {
+              "type": "string"
+            },
+            "exposure": {
+              "type": "number",
+              "minimum": -10,
+              "maximum": 10
+            }
+          }
+        },
+        "maxSamplesBudget": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Upper bound a render action may use. Guards the render-cost threshold of SPEC §15.4."
+        }
+      }
+    },
+    "renderProfiles": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "preview"
+      ],
+      "properties": {
+        "preview": {
+          "$ref": "#/$defs/renderProfile"
+        },
+        "final": {
+          "$ref": "#/$defs/renderProfile"
+        }
+      }
+    }
+  }
+}