picsart_media_query_layout

com.picsart.api/gen-ai · Verify this server

Resolves where every layer ACTUALLY LANDS in the root composition at a given time — without rendering pixels. Runs the engine's Scene Query System and returns each layer's final geometry in root-composition space: `box {x,y,width,height}` (top-left pixels), `center`, `rotationDeg`, paint-order `zIndex`, `visible`/`active`, an `onCanvas` coverage flag (`full`/`partial`/`off`), `timing`, and composition/parent/nesting. This is the cheap, structured answer to 'what does my composition look like, spatially?' — use it instead of (or before) checking a rendered frame (`picsart_media_contact_sheet`) to verify positions, sizes, overlap, off-canvas layers, and stacking order, since reasoning over numbers beats eyeballing a PNG. Coordinates are ALWAYS top-left pixels in root space for BOTH engines — the query layer unifies Jet's pixel coords and V3's internal normalized coords, so a layer WITH RESOLVED GEOMETRY reports the same box on `jet` or `v3` (the `engine` arg only changes the translation path). Text is the exception (see limitations). Nested children (scene_ref/look comps) are returned too, namespaced (e.g. `a__bg`) with `nestingLevel` and `composition`; inactive layers at the queried time come back marked `active:false` with their box omitted. Set `verbose:true` to also get raw 4x4 transform matrices and the per-component transform chain (for transform-editing tools); omit it for layout reasoning. Determinism is deterministic — identical (scene,time,engine) returns an identical report. Limitations: (1) text layers — the query system does not resolve laid-out glyph bounds, so a text layer's POSITION/center is accurate but its box size is a placeholder (Jet 0x0, V3 ~2000x1); a `notes[]` entry flags any layer with a degenerate dimension. (2) multi-group V3 scenes may need a `sceneContext` (e.g. { canvasGroupId }); single-composition scenes do not. (3) GEOMETRY ONLY — this is NOT a render/export gate. The query is GL-free and never resolves effects, assets, codecs, or engine-specific support, so a clean layout here does NOT guarantee the scene renders or exports. A clean report carries this caveat in its `scope` field — confirm renderability with picsart_media_contact_sheet / picsart_media_export.