ThanhNguyxnOrg product-grid-scene-planner
Purpose
Translate a multi-product grid intent (e-commerce / catalog / comparison) into a structured scene plan. Distinct from product-hero-scene-planner (single product, hero) and interior-architectural-scene-planner (room scene).
Quick start
- pin product list (count + per-product type)
- pin grid layout (rows × cols + spacing)
- pin per-cell consistency (camera angle, lighting, background)
- pin shared material / lighting / background palette
- emit a structured plan + handoff to checkers
When to use
- intent is multi-product display (4+ products in same scene)
- e-commerce catalog grid
- product comparison view
- showroom-style grid
When not to use
- single product hero (use
product-hero-scene-planner) - character portrait (use
character-portrait-scene-planner) - environment / interior scene (use respective planners)
Trigger phrases
- "grid of products"
- "lineup of"
- "catalog showing N items"
- "comparison render"
Prerequisites / readiness
- product list known (count + per-product description)
- consistency expectations known (identical lighting? identical camera? identical scale?)
Input schema
Required inputs
| Input | Why it is required |
|---|---|
| Product list | Determines grid size + asset scope |
| Grid layout (rows × cols) | Drives composition |
| Aspect ratio | Composition rules |
| Consistency level (strict / loose) | Determines per-cell rules |
Optional inputs
| Input | Use |
|---|---|
| Brand palette | Material + background consistency |
| Per-product variants (color / SKU) | Adds variant rows |
| Reference catalog images | Calibrate visual style |
Assumptions to confirm
- All products share the same scale convention.
- Lighting is shared across cells (not per-cell separate lighting setups).
- Camera angle is consistent (same yaw / pitch / lens) across cells unless explicitly varied.
Output schema
Primary output
A structured product-grid plan: Product list, Grid layout, Per-cell consistency rules, Shared lighting plan, Shared background, Per-cell composition rules, Aspect + framing.
Secondary output
- asset list flagged for
blender-asset-discovery-planner - naming + file convention notes for export
- handoff list
Evidence / caveat output
Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>
Required laws
../../laws/evidence-before-done.md../../laws/non-blender-user-language.md../../laws/no-arbitrary-python-interface.md../../laws/official-runtime-only.md
Official runtime boundary
Planning skill — does not run Blender, model, or render. Hand off to discovery / quality checkers.
Operating procedure
- Read product list; pin count + per-product description.
- Pin grid layout (rows × cols + spacing) per
references/grid-layout-rules.md. - Decide consistency level (strict / loose).
- Plan shared lighting (one rig, applied uniformly).
- Plan shared background.
- Plan per-cell camera + framing (typically same).
- Define per-product asset rows.
- Hand off to discovery / checkers.
Decision tree
Products at very different scales (lipstick + sofa) in same grid?
→ Fail; pick separate scenes or normalize scale clearly
Different lighting per cell requested?
→ Warn; usually erodes catalog uniformity
20+ products in single render?
→ Warn; consider multiple grid renders
Brand palette unclear?
→ Hand off to brief writer
Playbooks
Playbook A: 2×2 e-commerce hero grid (16:9)
4 products, identical 35mm lens, identical 3-point lighting, neutral seamless background, products centered in cells, equal spacing.
Playbook B: 3×3 catalog page (1:1)
9 products, square cells, identical lighting, brand-color background, consistent product orientation, lower-third caption space per cell.
Playbook C: 1×4 comparison strip (2.39:1)
4 product variants of same SKU, side-by-side, identical lighting + camera, label space below each.
Mode handling
Text-only mode
Plan only.
Runtime-ready mode
Plan + runtime path attribution.
Blocked runtime mode
Plan only; flag what cannot be confirmed.
Validation checklist
- Product list complete with count
- Grid layout (rows × cols + spacing) explicit
- Consistency level stated
- Shared lighting plan present
- Shared background present
- Per-cell camera consistent (or variation explicit)
- Aspect + framing consistent across cells
- Asset list flagged
- Handoff named
Pass / Warn / Fail rubric
| Verdict | Criteria |
|---|---|
| Pass | All sections + scale-normalized + consistent lighting + asset list. |
| Warn | One inconsistency (per-cell lighting variance) without justification. |
| Fail | Mixed-scale products without normalization, no shared lighting plan, missing per-cell camera consistency. |
Failure handling
- Mixed product scales → user picks normalized scale or splits into separate grids.
- 20+ products → suggest splitting into multiple renders.
- Missing brand palette → hand off to brief writer.
Troubleshooting
| Problem | Response |
|---|---|
| Products read at different sizes despite same scale | Verify camera distance is identical per cell; verify assets at same world scale. |
| One cell stands out | Check for accidental lighting / material variance. |
| Caption space cramped | Re-plan grid spacing or reduce product count. |
| Background distracts | Simplify to solid color or gradient. |
Best practices
- Lock one camera + one lighting rig; apply identically across all cells.
- Normalize product scale before grid planning.
- Reserve consistent caption space per cell for downstream layout.
- Use brand color as accent only, not full background (often clashes with materials).
Good examples
- "Products: 4 sneaker variants. Grid: 2×2, 0.5m spacing. Aspect: 16:9. Shared lighting: 3-point key 250W + fill 50W + rim 100W; HDRI 0.7 studio. Background: neutral seamless gray (#dddddd). Per-cell camera: 50mm equivalent, eye-level, 1.5m distance, identical orientation. Caption space: lower 15% of cell. Mood: clean, modern, e-commerce."
Bad examples
- "Show 4 products in a grid." — no lighting, layout, scale.
User-facing response template
Product list: <count + per-product list>
Grid layout: <rows × cols> | spacing <m> | aspect <ratio>
Consistency: <strict / loose>
Shared lighting: <plan>
Shared background: <type + tone>
Per-cell camera: <focal length> | <distance> | <eye-line>
Caption / label space: <where + size>
Mood + style: <line>
Assets to discover: <list>
Limitations: <gaps>
Next: blender-asset-discovery-planner / composition-quality-checker / lighting-quality-checker / material-quality-checker
Anti-patterns
- Per-cell separate lighting setups (breaks uniformity).
- Mixed-scale products without normalization.
- Background clashing with products.
- Skipping caption space when downstream layout needs it.
Cross-skill handoff
- Brief writer →
../intent-to-3d-brief-writer/SKILL.md - Asset discovery →
../blender-asset-discovery-planner/SKILL.md - Composition validation →
../composition-quality-checker/SKILL.md - Lighting validation →
../lighting-quality-checker/SKILL.md - Material validation →
../material-quality-checker/SKILL.md
Non-goals
- Model the products.
- Source the products.
- Render.
- Run Blender.
References
references/grid-layout-rules.mdreferences/grid-consistency-rules.mdreferences/grid-output-naming-rules.md../../docs/skill-system.md