# MOSS Box Layout (ComfyUI custom node)
Draw labelled boxes, give each one a prompt, and get a **MOSS-Image layout JSON**
plus the canvas **width / height** - with width/height typed *or* linked from any
other node.
## Install
Copy this folder to `ComfyUI/custom_nodes/comfyui-moss-box-layout/`, restart
ComfyUI, hard-refresh the browser. Add the node via
**Add Node > MOSS-Image > MOSS Box Layout (boxes + resolution)**.
## Wiring
| Output | Connect to |
|-------------------|--------------------------------------------------------|
| `prompt` | positive `CLIP Text Encode` (`text` input) |
| `negative_prompt` | negative `CLIP Text Encode` (MOSS-Image: empty is fine) |
| `width`, `height` | your empty-latent node (scaled values if the scaler is on) |
To drive the size from another node (e.g. a resolution selector), link its
width/height into this node's `width` / `height`. Boxes are stored as fractions
of the canvas, so they follow the new size and are converted to pixels at run
time using the values that actually arrive.
## Megapixel scaler
Turn on `scale_to_megapixels` and set `megapixels`: the node keeps the aspect
ratio of `width` / `height` (typed, from a preset, or linked) and rescales it to
the target size, both sides snapped to a multiple of 16. **1.0 MP = 1024 x 1024
pixels** (same convention as ComfyUI's scale-to-total-pixels), so a square at
1.0 gives 1024 x 1024 and 1344 x 768 gives 1360 x 768. The `width` / `height`
outputs are the *scaled* values, and the canvas preview and boxes follow them.
## Reference image
Connect any IMAGE to the optional `reference_image` input and it appears behind
the grid as a placement guide (it is **not** sent to the model). Controls under
the canvas: **Fit** (letterbox) / **Cover** (crop) / **Stretch**, and an opacity
slider. From a Load Image node it shows immediately; from any other node it
shows after the first run (a small preview is kept in ComfyUI's temp folder).
## Using the canvas
- **Drag on empty canvas** to draw a box (type chosen in "Draw as"); **+ Add box** drops one in the middle.
- **Click** a box to select it; drag to move, drag the white handles to resize.
- The **dropdown** also selects boxes (handy when they overlap). Delete / Duplicate / Clear all next to it.
- **Delete** key removes the selected box; **arrow keys** nudge it (Shift = 1 px).
- Per box: type (`object` / `character` / `text`), prompt, exact text (text boxes), and X / Y / W / H in pixels.
- Snapping to the 16 px grid is on by default (MOSS-Image works on a 16 px stride).
- The dashed cross marks the canvas centre, the origin of MOSS-Image's coordinates.
## Output format
Matches the released MOSS-Image weights (OpenMOSS USERGUIDE, "Layout Prompts"):
```json
{"summary":{"caption":"<scene prompt>"},
"items":[{"label":"text","caption":"...","text":"EXPLORE","bbox":[-416,-384,-288,384]},
{"label":"object","caption":"...","bbox":[-192,-288,384,288]}],
"bbox_coord_space":"abs_centralized","bbox_format":"yxyx"}
```
`bbox` = `[y_min, x_min, y_max, x_max]` in pixels from the canvas **centre**.
With no boxes the node outputs the plain scene prompt.
## Tips
- Keep position words ("at the top") out of box prompts - the box already says where.
- Keep width and height divisible by 16 (the node warns otherwise).
- If a link's value can't be read live, the preview uses the size from the last run.