← PicsartCONTENT HISTORY
WHAT CHANGED
Update to Picsart
Snapshot Nov 7, 2026 · 00:09 UTC · version 2.4.0
Collection source: downloaded plugin package.
First saved snapshot
No earlier snapshot is available to establish a change.
Save Picsart and check future changes in Following.
Up to 3 plugins free · no card required.
Compare saved observations
Download comparison JSONFull technical diff · 0 changed fields
Full snapshot data
{
"description": "Build a 3D scene (a composition whose space is 3d) — models, camera, lighting presets, floor, groups and parenting, model parameters, 3D motion presets (drop_in, fly_in_arc, snap_settle, bounce, idle_bob, wiggle, turntable; camera orbit, dolly, push_in, crane, whip_pan) — then render and measure it. Use when making a product or toy showcase, a build-up sequence of parts, an object that builds itself and then moves (drives, walks, unfolds), a turntable, a 3D title or any 3D document, or when 3D motion lands wrong, sinks into the floor or fails to evaluate. Not for a 2D cartoon character, face or mascot (shapes and the cartoon rig templates, in character-rigging), nor for flat layers in depth (photo cards that flip, a camera orbiting cards or panels) — that is a 2D scene with layer depth and the composition camera, in scene-animation-reference.",
"included_files": [
{
"relative_path": "references/model-parameters.md",
"size_in_bytes": 9706
},
{
"relative_path": "references/recipes.md",
"size_in_bytes": 6359
}
],
"name": "scene-3d-authoring",
"skill_md_contents": "---\nname: scene-3d-authoring\ndescription: Build a 3D scene (a composition whose space is 3d) — models, camera, lighting presets, floor, groups and parenting, model parameters, 3D motion presets (drop_in, fly_in_arc, snap_settle, bounce, idle_bob, wiggle, turntable; camera orbit, dolly, push_in, crane, whip_pan) — then render and measure it. Use when making a product or toy showcase, a build-up sequence of parts, an object that builds itself and then moves (drives, walks, unfolds), a turntable, a 3D title or any 3D document, or when 3D motion lands wrong, sinks into the floor or fails to evaluate. Not for a 2D cartoon character, face or mascot (shapes and the cartoon rig templates, in character-rigging), nor for flat layers in depth (photo cards that flip, a camera orbiting cards or panels) — that is a 2D scene with layer depth and the composition camera, in scene-animation-reference.\nmetadata:\n category: authoring\n version: '1.1'\n ported-from: 3d-authoring 1.1 at 55.91.0\n---\n\n# 3D scenes — models, light, motion, render\n\nA 3D scene is a scene whose composition says `space: \"3d\"`: metres, y up, rotations in\ndegrees about x then y then z (intrinsic). Its layers are objects (a `model`, a `media` or 2D-scene card,\na `scene_ref` group, or a `light`), it is seen through one camera, and it plays as a rendered video:\n`picsart_scene_contact_sheet` and `picsart_scene_export` render it, whether the 3D scene is the document\nitself or one a 2D scene plays through a `scene_ref`. **Ask `picsart_scene_capabilities` for\n`schema:Composition3D` and `schema:Layer3D` before writing a field** — a 3D object refuses 2D placement\nfields (`anchor`, `effects`, `looks`, `transforms`) by name.\n\nFlat layers in depth are not a 3D scene. Photo cards that flip in, panels that fan out, a camera\nthat orbits them: keep the 2D scene and give its layers `z`/`rotationX`/`rotationY` under the\ncomposition camera (`picsart_scene_recipe scene-animation-reference`, \"Depth and the camera\"). The catalog\nentries that work that way are tagged `2.5d` (`flip_in`, `flip`, `tilt_3d`, and the camera moves\n`orbit`, `dolly`, `push_in`).\n\nEvery asset a 3D scene names — a model, a picture, a video — is a public https URL. Build the\ndocument inline and change it with `picsart_scene_patch`.\n\n## Start from a frame, a camera and a light\n\n```json\n{ \"version\": \"1.0\",\n \"composition\": { \"space\": \"3d\", \"width\": 1920, \"height\": 1080, \"fps\": 30, \"duration\": 8,\n \"camera\": { \"eye\": [0, 0.75, 1.7], \"target\": [0, 0.08, -0.1], \"shutterAngle\": 180 },\n \"motionBlurSampleCount\": 8 },\n \"assets\": { \"brick\": { \"type\": \"model\", \"uri\": \"https://cdn.example.com/brick.glb\" } },\n \"layers\": [ { \"id\": \"b1\", \"content\": { \"kind\": \"model\", \"assetId\": \"brick\",\n \"materials\": { \"*\": { \"baseColor\": \"#e3000b\", \"roughness\": 0.35, \"clearcoat\": 0.6 } } },\n \"transform\": { \"position\": [0, 0, 0], \"scale\": [10, 10, 10] } } ] }\n```\n\n- **Camera.** `eye` is where it stands, `target` what it looks at, both in metres; `lens.fov`\n is vertical degrees (default 35). Frame the subject by moving the eye, not by scaling the\n subject. `shutterAngle` 180 with 8 samples is film motion blur for the whole frame.\n- **Light.** Set `composition.lighting` (`schema:Composition3D`): a `preset` — `studio`, `dark`,\n `sky` or `white_room` — then tune any one light over it (`key`, `fill`, `rim`, `ambient`: a key's\n `intensity`, `color`, `direction`, `shadow.softness`). `background`, `environment` and `ground`\n finish the look: a warm paper sweep with a soft-shadowed key is `studio`; a low orange key from the\n side with a dusk-gradient `background` reads as sunset; near-black with a bright cool `rim` is dramatic.\n\n- **Post effects.** `composition.effects` is the 3D scene's post stack: `glow`,\n `ambient_occlusion`, `depth_of_field`, `color_grade`, `vignette`, `film_grain`,\n `channel_shift`. Their params, ranges and units are the `space: \"3d\"` entries of\n `picsart_scene_capabilities` `effects` — `sections: [\"effect:ambient_occlusion\"]` for one, or\n the whole `effects` section, keeping the entries whose `space` is `3d`. A glow spreads only emitted light: a lamp or an LED\n (`emissive` with an `emissiveStrength` above the `threshold`), never a lit surface.\n- **Floor.** `ground` is the plane y = 0 and takes the key's shadows. An object stands on it\n when its lowest point is at y = 0 — see *Models* for where that is. Over a drawn floor the\n backdrop shows only where the floor does not: a camera looking down sees floor, not sky. To\n show a gradient or sky, lower the eye or raise the target until the horizon is in frame.\n- **Seamless sweep.** A lit floor never matches an unlit backdrop: the lights shade it, so its\n horizon shows. `ground.shadowOnly: true` over a `background` draws the backdrop itself as the\n floor, with only the shadows on it (`studio` does this), and no horizon at any camera height.\n- **Matte.** `ground.shadowOnly: true` with no `background` renders a matte that carries the\n shadows onto whatever 2D scene plays it.\n- **Casts nothing.** A sky dome or a far backdrop model takes `content.castShadow: false`: it neither shuts\n the key out nor widens the shadow's fit, which follows the casters only, so shadows stay sharp.\n\n## Models\n\nA model is a GLB `model` asset at a public https URL. Asset keys are identifiers: `p3004`, never `3004`.\n\n- **Origin at the base.** The origin is what `position` places, what a turn pivots on and\n what a squash flattens toward. With the origin at the centre of the base the object stands on\n the floor at `[x, 0, z]` and squashes onto it. A model whose origin is elsewhere is lifted by its\n height (the import report gives its bounds), or fixed in the file it came from.\n- **Bring a model in.** `picsart_scene_import_model` takes a GLB, a glTF (buffers and images\n embedded as data: URIs) or a binary FBX from a public https URL, Draco or meshopt compressed\n included, and returns one uncompressed GLB plus a report of its nodes, bones, morph targets,\n materials and clips, with the model parameters it proposes. Reference the `url` it returns (the\n Drive copy when `driveUid` comes back; an `expiring` one must be re-imported before a scene\n depends on it). `expose` picks the parameter kinds (`bones`, `morphs`, `materials`, `clips`);\n a bone a clip already turns is proposed only when `bones` is named, so a walk clip still walks.\n Look at it with `picsart_scene_preview_model` (a still or a turntable) before building on it.\n- **A ready-made model.** `picsart_scene_build_model` builds one GLB: `character` (a rigged toy\n bear with `blink`, `aa`, `happy` and body controls such as `headNod`, `leftUpperArmRaise`) or\n `set` (a meadow of props: path, hills, trees, flowers, blocks, mushrooms, castle, clouds, fence,\n bunting, balloons, sky; the same arguments build the same model). `sky` is an unlit dome: give that\n layer `castShadow: false`. Build the far set (sky, hills, clouds) and the near one (trees, fence,\n flowers) as two models.\n- **Materials.** `content.materials` overrides by material name, `\"*\"` for all of them.\n- **Model parameters.** A knob the model declares (a colour that makes the studs glow, a bone,\n a shape key) is set per layer through `content.parameters` — a constant or a track, so it can flash\n on a beat. What a parameter binds, aggregate mode, response curves, several actions mixed in tiers,\n lip sync, the standard character control names and a car without bones:\n [references/model-parameters.md](references/model-parameters.md).\n- **A face or screen on a model** is a material texture slot, not a card:\n [references/model-parameters.md](references/model-parameters.md), \"Faces and screens on a model\".\n\n## Groups and parenting\n\n- **Group** — several objects that move as one: a `scene_ref` layer whose scene is a 3D\n scene with only `space` (and `duration`) in its composition. The group's `transform` and\n `animations` place the whole; its objects keep their own motion inside, on the group's clock.\n A sub-assembly built beside the main model, then flown in, is a group.\n- **`parentId`** — one object rides a sibling's placement (position, rotation, scale) at\n every instant, keyframes and expressions included; opacity and time stay its own. Use it for\n a part that must stay attached to something that moves.\n- **A carrier** — motion with nothing drawn, for several objects to ride: a group whose scene\n has no layers, holding the motion, and the objects parented to it. An object's own\n `animations` then stay free for its entrance or its loop.\n\n ```json\n \"assets\": { \"rig\": { \"type\": \"scene\", \"scene\": { \"composition\": { \"space\": \"3d\" }, \"layers\": [] } } },\n \"layers\": [\n { \"id\": \"rig\", \"content\": { \"kind\": \"scene_ref\", \"assetId\": \"rig\" },\n \"animations\": { \"position\": { \"keyframes\": [{ \"time\": 0, \"value\": [-1, 0, 0] }, { \"time\": 2, \"value\": [1, 0, 0] }] } } },\n { \"id\": \"car\", \"parentId\": \"rig\", \"content\": { \"kind\": \"model\", \"assetId\": \"car\" } }\n ]\n ```\n\n## Lights\n\n- **A light layer** — `content: { kind: \"light\", type: \"point\" | \"spot\", intensity, color }`: a light that\n stands in the scene, placed by the layer's `transform` and `animations` and parented by `parentId`. The rig's\n `key`, `fill` and `rim` are directional and light everything; a light layer lights what is near it. `scale`\n and `opacity` on it are refused (`light_layer_field`); dim it with `intensity`.\n- **Units.** At 1 m a surface facing it is as bright as under a key of the same `intensity`; it falls off as\n `1 / d^decay` (`decay` 2 by default), and `range` (metres) fades it to nothing there.\n- **A spot** shines along the layer's −z: `rotation: [-90, 0, 0]` shines straight down. `angle` is degrees from\n its axis to the cone's edge (default 30), `penumbra` 0..1 softens the edge.\n- **Shadows.** `shadow: { softness }` makes it cast them (a point light every way; a spot's `angle` at most 85);\n omitted, it casts none. Each one renders a shadow map (six for a point light) every frame: give it to the\n lights that need one.\n- **Its tracks** are on the layer's clock. A colour expression returns `Color.rgb(r, g, b)` (0..1), never a hex\n string. Lights pulsing on a beat: [references/recipes.md](references/recipes.md).\n\n## Cards\n\nA card is a flat picture `width` metres wide (default 1), its height from the picture's aspect,\nfacing +z; `lit: false` shows it at its own colours.\n\n- **Media card** — `content.kind: \"media\"` with an `image`, `svg`, `video` or `video_with_matte`\n asset. A video plays on the layer's clock: at layer time t it shows `trim.in + t × speed`,\n holding its last frame past `trim.out` unless `loop`. A `video_with_matte` is cut out by its\n matte. A card plays no sound: put the audio in the 2D scene around the 3D one.\n- **Scene card** — a `scene_ref` whose scene is 2D (`assetId`, or an inline `asset`): the scene\n drawn flat, its composition `width`/`height` its aspect. `parameters` are its bindings, keyed\n on the card layer's clock: a sign's text, a screen's colour, a track a 2D template animates.\n A card's body is written out: to play a template, the body declares the parameters it takes\n and passes them to one `scene_ref` layer pointing at the template. `width` and `lit` belong to\n a scene card only; a group refuses them.\n- A card is a flat plane: use it for screens, signs, posters and other 2D in 3D. It does not\n follow a bone; a picture painted on a model's surface is a material slot.\n\n```json\n{ \"id\": \"sign\", \"transform\": { \"position\": [0, 1.6, -2] },\n \"content\": { \"kind\": \"scene_ref\", \"width\": 1.2, \"lit\": true,\n \"asset\": { \"type\": \"scene\", \"scene\": { \"composition\": { \"width\": 600, \"height\": 200, \"duration\": 4 },\n \"parameters\": { \"label\": { \"type\": \"text\", \"default\": \"OPEN\" } },\n \"layers\": [{ \"id\": \"t\", \"content\": { \"kind\": \"text\", \"text\": { \"$eval\": \"label\" } } }] } },\n \"parameters\": { \"label\": \"PLAY TIME\" } } }\n```\n\n## Motion presets\n\n`picsart_scene_apply_preset` with `preset: \"motionPreset:<id>\"` puts a preset on a 3D object\n(`layerId`) or on the camera (no `layerId`). Defaults are tuned; pass only what you change. `orbit`,\n`dolly` and `push_in` also name a 2D composition-camera preset; on a 3D scene the 3D one below\napplies. Every `motionPresets` entry of `picsart_scene_capabilities` says its `space`; keep the\nentries whose `space` is `3d`.\n\n| Object preset | What it does | Params (default) |\n|---|---|---|\n| `drop_in` | Falls from above, lands, squashes | `duration` 0.5, `height` 0.6, `squash` 0.12 |\n| `fly_in_arc` | Flies in on a rising arc, spinning, slows into place | `duration` 0.8, `distance` 0.8, `direction` right, `arc` 0.4, `spin` 1 |\n| `snap_settle` | Drawn in, overshoots, swings back, squashes on contact | `duration` 0.3, `distance` 0.15, `direction` down, `intensity` 0.3, `settle` 10, `bounces` 25, `squash` 0.1 |\n| `bounce` | Hops and lands, squashing, every period | `height` 0.15, `period` 0.6, `squash` 0.1 |\n| `idle_bob` | Slow rise, fall and tilt that never resolves | `period` 3, `distance` 0.03, `angle` 2 |\n| `wiggle` | Smooth never-repeating drift and turn | `frequency` 1.5, `amount` 0.02, `angle` 3, `seed` 0 |\n| `turntable` | Turns about the world vertical, keeping its tilt | `period` 8, `direction` counterclockwise |\n\n| Camera preset | What it does | Params (default) |\n|---|---|---|\n| `orbit` | Circles the point it looks at | `start` 0, `duration` 6, `angle` 360, `easing` ease_in_out |\n| `dolly` | Travels along the view, target with it | `start` 0, `duration` 2, `distance` 1 |\n| `push_in` | Closes in on the target, which stays | `start` 0, `duration` 3, `amount` 0.3 |\n| `crane` | Rises, still looking at the target | `start` 0, `duration` 2.5, `height` 1 |\n| `whip_pan` | Swings the view fast, standing still | `start` 0, `duration` 0.3, `angle` 70, `direction` left |\n\nHow they combine:\n\n- **An object's motion is relative to where it rests.** Entrances end exactly at the object's\n `transform`, loops start from it. Move the object afterwards and its motion moves with it.\n Time is the object's own: an entrance starts at the object's `start`.\n- **One channel carries one expression.** Two presets that both drive an object's position\n (say `drop_in`, then `idle_bob`) — the second replaces the first, and the result says so in\n `notes`. To follow an entrance with a loop, give the loop its own object: a group or a\n `parentId` parent holding the loop, the object holding the entrance.\n- **Camera moves chain.** Each move starts where the camera is at its `start`; keyframed moves\n (`dolly`, `push_in`, `crane`) append, so `dolly` 0–2 then `crane` 2–4 runs as one path. A move\n starting inside existing camera keyframes is refused; start it at or after the last one.\n `orbit` and `whip_pan` ride whatever path is there and hold their end angle — so apply them\n **last**: a keyframed move after one cannot tell where the camera is, and is refused. They\n turn about the point the camera looks at (orbit) or stands at (whip pan) as it is at their\n `start`, so that point must have stopped moving by then. Each reads the channel the other\n turns, so a camera takes one of them: orbit through a shot, or whip pan out of one.\n\nWorked sequences — a build of parts on a beat grid, an object that builds itself and then drives\noff, the whole scene pulsing on the beat — are in [references/recipes.md](references/recipes.md).\n\n## Render and verify\n\n- **Validate.** `picsart_scene_validate`; a 3D document always carries a warning that a translated\n target cannot draw it — that warning is expected, nothing else is. Validation does not read a model\n at a URL: a `materials` override or `action` the model lacks shows up only when it renders, so take\n the names from the `picsart_scene_import_model` report.\n- **Render.** `picsart_scene_contact_sheet` with `times` draws the moments you name into one sheet;\n `picsart_scene_export` renders the video, or one frame with `mediaType: \"png\"` and `startTime`. Both\n take the 3D document as it is, or a 2D scene that plays it, and draw the same frame at the same\n time. `parameters` set the scene's declared parameters on both. Look at **one** contact sheet\n through several `times`, not one render per still.\n\n ```jsonc\n // a bare 3D scene at fps 15 declaring `tilt`; times are multiples of 1/15 (the render's frame grid):\n picsart_scene_contact_sheet { \"scene\": <scene>, \"parameters\": { \"tilt\": 30 }, \"times\": [0.4, 1.2, 1.8] }\n ```\n\n- **Text goes over it in 2D.** A 3D object is a model, a card or a group — no text drawn in 3D. A\n title is a 2D scene playing the 3D one through a `scene_ref` whose `parameters` pass the caller's\n values on, with the text layer beside it; render and export that 2D scene as it is.\n- **Measure, don't eyeball.** Render a check view: a side or top `camera`, no `shutterAngle`, a\n small `width`/`height`, and a contact sheet with `times` around the motion — exact frames to\n look at. `picsart_media_track_motion` on the exported video (`targets: [{ bbox }]` on the moving\n part) returns the part's position every frame — of the final composite, so a 2D layer drawn over\n the part, or a background of the part's colour, moves the box too: track a check view with a plain\n contrasting `background` on the 3D document and nothing over it. Check that an entrance lands\n exactly on its `transform`, that nothing sinks below y = 0, that a moving part's box never crosses\n one already placed, and that the camera path is continuous across shot seams.\n- **Pitfalls.**\n - A `parameters` name the scene does not declare is refused, naming the tool and the names it\n does declare: read them from the scene's `parameters` block, not from memory.\n - The render is a video at the scene's `fps`: a time between two of its frames draws one of them.\n Ask for times on the grid (`n / fps`) when comparing moments, or two \"different\" times can show\n the same frame.\n\n## Gotchas\n\n- **A one-number `scale` is one number to an expression.** `transform.scale: 10` makes a\n hand-written expression's `value.y` fail; write `[10, 10, 10]`. Presets convert it for you.\n- **An expression returns `Vec.v3(x, y, z)`, never a Lua table** — `{1, 2, 3}` fails to\n evaluate. Read components as `value.x` or `value[1]`; `value * 2` and `value + Vec.v3(…)` work.\n- **Another layer's depth is `getPlacement():z()`**, beside `position()` and its heading `rotationY()`.\n- **The camera's `eye` and `target` have no resting value**, so an expression on one needs\n keyframes to start from; `orbit` and `whip_pan` write that keyframe for you.\n- **Rotation keyframes interpolate the numbers.** `[0, 0, 0]` to `[0, 360, 0]` is a full turn;\n `[0, 350, 0]` to `[0, 10, 0]` turns 340° back. A turn about the world vertical on a tilted\n object is `turntable`, not a y keyframe.\n- **Final values exactly.** A landing pose written with rounded numbers lands a hair off its\n neighbours; write the same numbers as the resting `transform`.\n- **Something sinks into the floor.** Its origin is not at its base — lift it by its height.\n- **A squash lifts the object off the floor.** Same cause: a squash flattens toward the origin.\n- **The backdrop never shows.** The camera is looking down at a drawn floor; bring the horizon\n into frame, or make the ground `shadowOnly`.\n"
}SHA-256 of public snapshot: 0bf628831911ab7e484ef52ca2856ac81aed9691d7e827a50e013af26ddfd81d