Posed RGBD generation
Generate posed views from image, depth, and camera context.
atlasGenerate generates posed RGB views at target cameras from one or more
posed RGBD context frames. Each context frame supplies an image, depth buffer,
and camera. Marble uses these views as references for the generated scene.
Account availability:
POST /api/v2/tasks:atlasGeneraterequires access to this task on your account.
Prepare RGBD context
Every contextFrames entry requires an imageAsset, depth, and camera.
Keep those three values aligned to the same view and coordinate system. Target
cameras determine how many frames are generated and their order in the
response. All context cameras must declare the same width and height; that
resolution may differ from the target cameras' resolution.
depth takes the same two encodings as atlasChisel context depth: a
linear-depth EXR in depthAsset, or an 8-bit inverted log-depth PNG in
logDepthAsset with its zMin and zMax. Mark sky and other pixels with no
surface as 0 (or NaN or infinity in an EXR), not as a distant surface; any
finite positive depth is read as geometry. See
Encode context depth.
Targets must use a 1280 × 720 camera grid. Marble selects the model
automatically based on the number of context frames and target cameras;
atlasGenerate does not accept a model selector.
Context depth is required, but does not guide generation in every request. Requests with 32 or more targets generate from the context images and cameras without using their depth. Smaller requests can do the same when their combined context and target counts exceed the depth-guided model's capacity.
Prompt enhancement is enabled by default. Atlas writes a scene description from
your prompt and context images before generating. Preserve promptUsed from the
response to audit the description, or reuse it with enhancePrompt: false on a
later request.
Omit modelParameters.numSteps to use the selected model's default number of
generation steps.
Generate a video or camera path
Sample the camera path at the final frame rate and submit the complete ordered
trajectory as targetCameras in one atlasGenerate request. Atlas handles the
sequence internally, generating keyframes and using them as context for the
frames between them. Assemble the returned images in response order at that
frame rate. Set returnDepth: false when only video frames are needed.
Do not split a continuous trajectory into independent frame requests or small batches as a performance optimization. Separate requests do not share generated sequence context, and changing the target count can change model routing. Reusing the same seed does not make separate requests equivalent to one sequence; stitching their outputs can introduce flicker and layout jumps. If a trajectory exceeds the supported request limits, shorten it or plan separate shots rather than assuming independently rendered batches will join continuously.
Use sparse preview renders to inspect framing, then regenerate those camera positions as part of the complete final sequence. Do not splice preview outputs into the final video. If waiting times out, resume the existing operation rather than resubmitting its frames separately; see Operations.
Choose context views for consistent geometry and useful coverage of the path. One posed image is valid context. Add generated RGBD views when they reveal needed areas and remain consistent with the scene; do not automatically include every generated view. More context is not a guarantee of better continuity.
Request output depth
Set returnDepth: true to reconstruct depth for the generated views and attach
it to each returned frame. The depth scale comes from the camera centers, so a
request whose context and target cameras all share one center (a pure-rotation
rig) is rejected with HTTP 422 at submission. Translate at least one camera,
or set returnDepth to false.
When generation uses only images and cameras, or when you supply more than 19 context frames, a context frame helps reconstruct depth only when its image has the same dimensions as the generated images and its camera's principal point is centered.
Returned depth can contain NaN where the reconstruction found no reliable
geometry; see
Missing values in returned depth.
Get the frames in the submission response
A request sent with ?wait=true and enhancePrompt set to false can come
back from its submission already done: true. By default that response names
each output file by assetId and url. Set base64Outputs to true to
receive each file in that response as a base64 data URL instead. The service
then skips storing the files before it answers, and you skip downloading them. A
later read of the operation names the files by assetId and url either way.
Frames answered at submission are JPEG; frames the operation generates later are
PNG. Depth answered at submission is half-float EXR, which reads any depth above
65504 as infinity; depth the operation produces later is float32 EXR. See
Operations.
Example completed output
After the operation reports done: true, its task-specific result is in
operation.response. This example requested output depth:
When returnDepth is false, each frame contains only its generated
imageAsset and camera. Open the
atlasGenerate reference for
the live request limits and complete schemas.