visualspec.1.0 RC
GitHub
Module

Camera

How the scene is seen

Camera records the optical and compositional intent: where the viewer stands, how wide the view is, and what the lens is trying to do. The same idea covers a photograph and a realtime 3D view.

Use this module when Framing, lens, or viewpoint is part of the result rather than a default the tool happened to use.

Keep in mind. A camera does not create the subject. The subject lives in the world or the scene. The camera only decides how it is seen.

Raw schema:/schema/1.0/modules/camera.schema.json · https://visualspec.dev/schema/1.0/modules/camera.schema.json

How to read a definition.The paragraphs say what to write and why. “Exact constraints” opens the schema keywords (type, pattern, bounds) for people checking a validator. A sample at the bottom of each definition is the smallest JSON that shows the required shape. Values such as $ref inside a sample point at another definition. They are not fields you copy into a document.

camera

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and type.

20 other fields are optional. Include one only when you have a real value for it.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

typerequired"perspective" | "orthographic" | "panoramic" | "photographic" | "realtime"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "perspective"
  • "orthographic"
  • "panoramic"
  • "photographic"
  • "realtime"
positionvector3

This is not a new shape. It reuses vector3 from the common module. Open that definition for the fields you can write.

orientationvector3 | quaternion

More than one shape is accepted. Use exactly one of the 2 alternatives below. They are different ways to say the same kind of value.

anyOf 1vector3

This is not a new shape. It reuses vector3 from the common module. Open that definition for the fields you can write.

anyOf 2quaternion

This is not a new shape. It reuses quaternion from the common module. Open that definition for the fields you can write.

targetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

fieldOfViewnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
exclusive maximum
180
focalLengthnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
sensorWidthnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
aperturenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
nearnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
farnumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
orthographicSizenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
exclusive minimum
0
focusobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit targetRef, distance, and mode. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
targetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

distancenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
mode"manual" | "auto" | "follow"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "manual"
  • "auto"
  • "follow"
depthOfFieldobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit enabled, focusDistance, and blur. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
enabledboolean

Write true or false.

Exact constraints
type
boolean
focusDistancenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
blurnumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
framing"extreme-close-up" | "close-up" | "medium" | "medium-wide" | "wide" | "extreme-wide" | "establishing" | "over-shoulder" | "point-of-view" | "custom"

Pick one of the 10 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "extreme-close-up"
  • "close-up"
  • "medium"
  • "medium-wide"
  • "wide"
  • "extreme-wide"
  • "establishing"
  • "over-shoulder"
  • "point-of-view"
  • "custom"
shotTypetaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

movementarray<taxonomy>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemstaxonomy

This is not a new shape. It reuses taxonomy from the common module. Open that definition for the fields you can write.

intentstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
actionRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

exposurenumber

Write a number. Decimals are allowed.

Exact constraints
type
number
whiteBalancenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

cameraJSON
{  "id": {    "$ref": "common#id"  },  "type": "perspective"}