Composition and view

Composition and view are the two global settings that define how a Neonix JSON V2 document becomes a visual output. Composition defines the canvas and time base. View defines how world coordinates are projected into that canvas.

The mental model

The order is intentional: authoring defines the composition, layers are placed in world space, and the view projects that world into the declared output rectangle.

Complete composition example

The composition object is required. This is a valid 1920×1080, 30 FPS document envelope:

{
  "format": "motion-protocol",
  "formatVersion": 2,
  "composition": {
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "background": "#101820",
    "colorSpace": "srgb",
    "view": {
      "projection": {
        "kind": "orthographic",
        "zoom": 1,
        "near": 1,
        "far": 4000
      },
      "transform": {
        "translate": { "x": 0, "y": 0, "z": 0 },
        "rotate": { "x": 0, "y": 0, "z": 0 }
      }
    }
  },
  "layers": []
}

The JSON field format remains the schema compatibility value. The public name of the document format is Neonix JSON V2.

Output dimensions

width and height are positive composition units. For standard 2D work they behave like output pixels, with the origin at the top-left, X increasing to the right and Y increasing downward.

The aspect ratio is determined by these two values:

Changing a layer frame does not change the composition size. Changing the browser viewport does not change it either. In an HTML document, the composition metadata is authoritative; body CSS only controls how the authoring page is laid out.

Frame rate and time

fps is the positive number of frames per second. Export samples the composition at this cadence:

30 fps  ->  frame 0 at 0 ms
           frame 1 at 33.333... ms
           frame 2 at 66.666... ms
           frame 3 at 100 ms

Layer timing, keyframes and audio clip timing use milliseconds. The composition does not resize or stretch time when the output FPS changes; it changes the frame sampling cadence. Keep the same FPS in preview and export when comparing motion.

Background and color space

background is the base color of the composition behind transparent or uncovered pixels. It is a color value, not an image asset and not a layer.

colorSpace is currently required to be srgb. Keeping this explicit makes color interpretation deterministic across browsers, preview surfaces and exported video.

View and projection

The view is required and contains two parts:

1. projection maps world coordinates into the composition rectangle.
2. transform moves and rotates the view before projection.

Orthographic projection

Orthographic projection is the default for ordinary 2D motion. Objects do not become smaller just because their Z position changes.

{
  "kind": "orthographic",
  "zoom": 1,
  "near": 1,
  "far": 4000
}

• zoom is a positive scale factor. A larger value zooms into the world.
• near and far define the visible depth range.
• far must be greater than near.

Use orthographic projection for titles, cards, UI motion, illustrations and most HTML-to-video compositions.

Perspective projection

Perspective projection makes depth affect apparent size. Objects with different Z positions can appear closer or farther from the view.

{
  "kind": "perspective",
  "fov": 60,
  "near": 1,
  "far": 4000
}

• fov is the vertical field of view in degrees and must be between 0.001 and 179.999.
• near and far are positive depth planes.
• Keep far > near and keep visible objects inside the depth range.

Perspective belongs at the composition view level. A local group can also have its own 3D perspective semantics; that is documented under Layers and hierarchy.

View transform

The view transform has finite 3D translation and rotation values:

{
  "transform": {
    "translate": { "x": 0, "y": 0, "z": 0 },
    "rotate": { "x": 0, "y": 0, "z": 0 }
  }
}

• translate moves the view in world units. Because it is a view transform, moving the view in one direction makes the scene appear to move in the opposite direction.
• rotate rotates the view around X, Y and Z in degrees.
• z is meaningful when using 3D layer positions or perspective projection.

For a normal 2D composition, keep the view at zero translation and rotation, use orthographic projection and place content with layer transforms instead.

Composition, view and layer frame are different

Consider a 1920×1080 composition with a 640×360 card:

composition.width / height  -> output canvas: 1920 × 1080
card.frame.width / height   -> local geometry: 640 × 360
card.transform.translate    -> where the card is placed
composition.view             -> how the whole world is projected

Changing the card frame changes only the card. Changing the view can affect every layer. Changing the composition dimensions changes the final output contract and may require repositioning content.

Validation rules and common mistakes

• Composition must include positive width, height and fps.
• background must be a valid color and colorSpace must be srgb.
• view, projection and transform are required objects.
• Orthographic projection requires zoom, near and far.
• Perspective projection requires fov, near and far.
• far must be greater than near.
• Do not use body CSS, a browser window size or a layer frame as a substitute for composition dimensions.

Continue with Transform and Matrix4 for layer transforms, Layers and hierarchy for parent-child coordinates, and Animation and timing for time-based changes.