ausboss-ComfyUI-AusBoss/js/docs/AUSBOSS_NODES_LayoutBoxes.md

# Layout Boxes

Draw boxes on a canvas and say what goes in each one: a thing, or words to
write in the picture. The picture you make then has each thing where you put
it. Use it for layout prompts, such as MOSS-Image's.

It does what ComfyUI's own Create Bounding Boxes does and gives the same
outputs. Its canvas also works in the classic node look, where Create Bounding
Boxes only shows "Node 2.0 only".

## How to use it

1. Set the canvas size in **Canvas** (W × H), or wire `width` and `height` from
   Latent Size, so the boxes and your picture have the same size.
2. Drag on the canvas to draw a box. Its tag shows its number and its type,
   such as **1 object**.
3. Under the canvas, the row **Box 1 is** sets what the chosen box holds,
   **object** or **text**. Then type its words:
   - **object**: the **Description** says what is in the box, for example "a
     red bicycle leaning on a brick wall".
   - **text**: the **Text** is the words to write in the picture, for example
     "OPEN 24 HOURS". The **Description** says how they look, for example
     "pink neon letters".
4. Wire `elements` to the `element` input of MOSS-Image Layout Prompt, and give
   that node the same width and height.

Wire `preview` to a Preview Image to see the boxes with their numbers and words.

## Change the words in a picture

The `mask` output is white inside every box. Use it to change only one part
of a picture, such as the words on a sign or a shirt.

1. Wire a Load Image into `background` and pick your picture. It shows on the
   canvas right away.
2. Draw a box over the old words, a little wider than the old words on every
   side (about 12 pixels), or bits of the old letters can show at its edge.
   Keep faces and hands out of it: whatever is in the box is drawn again.
   The arrow keys move the chosen box one pixel at a time.
3. If the words run at a slant, turn the box to match them: drag the round
   handle over the box (see **Turning a box** below).
4. Make it a **text** box. Type the new words in **Text**, and how they look in
   **Description**, for example "white letters on a red sign".
5. Soften the edge of `mask`, for example with Mask Refine 🆎 at a blur of
   about 6, or a line can show around the box. Then wire it into the inpaint
   part of your workflow: Set Latent Noise Mask, so only the box is drawn
   again, and Image Composite Masked, so everything else stays as it was.
6. With MOSS-Image, wire `elements` to MOSS-Image Layout Prompt. The model
   gets the new words from the box, and your prompt only describes the picture.

## Turning a box

Words on a sign or a shirt often run at a slant. Turn the box to lie along
them, and only the slanted words are drawn again.

1. Click the box to choose it. A round handle shows over the middle of its
   top edge.
2. Drag the handle around the box. Hold Shift to turn it in steps of 5
   degrees.
3. Or type the angle in **Turn**, under the canvas: plus turns the box
   clockwise. **0°**, or a double-click on the round handle, makes the box
   level again.

The box's tag shows how far it is turned, for example **1 text 25°**. A turned
box still moves, sizes and takes the arrow keys. Its corners may reach past
the edge of the picture, so it can cover words that run to the edge.

A turned **text** box tells the model the slant for you: its description in
`elements` gets "tilted about 25 degrees, running downhill to the right" (or
"uphill") added, so you do not have to type it.

If the picture is resized on its way to the model, resize the mask with it:
Image Resize 🆎 takes a mask and gives it the same size and crop.

## Drawing and moving boxes

| Do this | To get this |
|---|---|
| Drag on an empty spot | Draw a new box |
| Shift + drag over a box | Draw a new box on top of it |
| Drag a box | Move it |
| Drag a corner or an edge of the chosen box | Make it bigger or smaller |
| Drag the round handle over the chosen box | Turn it (Shift: steps of 5 degrees) |
| Double-click the round handle | Make the box level again |
| Double-click a box | Type its words |
| Click a box's chip under the canvas (**1 text**, **2 object**) | Choose that box, also one hidden under another. When there are more boxes than chips, **‹ ›** step through them |
| Delete | Remove the chosen box |
| Arrow keys | Move the chosen box one pixel (Shift + arrow: ten pixels) |
| Ctrl + D | Copy the chosen box |
| Esc | Let go of the box, or put back a box you are dragging |
| Hold Ctrl (or Alt) while dragging | Place the box freely, off the grid |

The keys work while the canvas has the focus: click the canvas, or a box's
chip, first.

The handles and the tags keep their size on your screen when you zoom the
graph in or out, and a box too small for eight handles keeps its corners.
Over a picture the boxes are see-through and show no words, so you can read
what is under them; the chosen box's words are under the canvas.

An **object** box does not write words. If you typed words while it was a
**text** box, a line under the canvas says they are kept: click **text** and
they come back.

## The order of the boxes

Box 1 is at the back, and the last box is in front, so draw the things at the
back first. The two square buttons under the canvas move the chosen box back or
forward. MOSS-Image Layout Prompt's `character_boxes` takes these numbers.

## Colors

A box can have up to five colors for the model to use on that thing. **+** adds
a color, a click on a color changes it, and a right-click (or its cross)
removes it. The first color also colors the box on the canvas.

## The bar above the canvas

- **Grid**: boxes snap to a grid while you draw, move and size them with the
  mouse. It is on for an empty canvas and off over a picture on `background`,
  so a box can go anywhere on the picture. Click it to turn it on or off; the
  node keeps your choice. Hold Ctrl (or Alt) while dragging to leave the grid
  for one drag. The cells are 32 pixels, bigger on a very big canvas. A
  turned box does not snap: it moves and sizes one pixel at a time.
- **Layouts**: start from a ready arrangement: one in the middle, two side by
  side, three across, top and bottom, a title over a picture, four corners.
  The boxes you already have move into the new places, level, and keep their
  words.
- The canvas size, and where it comes from: **picture** when a picture is on
  `background`, **wired** when width and height are wired.
- **Clear** removes every box.
- **⚙** (the gear): **Grid size**, the pixels from one grid line to the next:
  Auto (32 pixels, more on a very big canvas), 8, 16, 32 or 64. The node keeps
  it.

## Inputs

| Input | What it does |
|---|---|
| `background` | A picture to draw on. It shows under the boxes, and the canvas takes its size and shape, also when `width` and `height` are wired: the boxes are drawn on the picture, where the `mask` is made. The Canvas row dims while a picture is wired. |
| `bboxes` | Boxes to start from: bounding boxes, prompt elements (such as the `elements` of another Layout Boxes), or either as JSON text. New boxes on this wire fill the canvas when the workflow runs. Your changes on the canvas then stay until the boxes on the wire change. After **Clear**, the next run fills the canvas from the wire again. |
| `width`, `height` | The canvas size in pixels. Wired from Latent Size, the canvas takes that size and shape at once. |

## Outputs

| Output | Use |
|---|---|
| `preview` | A picture of the boxes with their numbers, words and colors, to check the layout. Turned boxes are drawn turned. |
| `bboxes` | The boxes in pixels of the canvas (x, y, width, height), for nodes that take bounding boxes. A turned box gives the straight box around it. |
| `elements` | The boxes as prompt elements. Wire it to MOSS-Image Layout Prompt. A turned box gives the straight box around it, and a turned text box says its slant in its description. |
| `mask` | White inside every box, black elsewhere, to change only those places of a picture. A turned box is white inside its turned shape only. |

## In place of Create Bounding Boxes

Layout Boxes has the same inputs and the same outputs in the same order (and
`mask` after them), so the wires move straight over. For the same boxes it
gives the same `bboxes` and `elements`, and MOSS-Image Layout Prompt makes the
same prompt from them.

The boxes drawn on a Create Bounding Boxes do not move over by themselves. To
take them along, wire that node's `elements` into `bboxes` of Layout Boxes and
run once: they fill the canvas. Then remove the old node.

## Technical details

- The boxes are kept on the node as text, in the hidden `layout` input. Each
  box's place is kept as parts of the canvas from 0 to 1, so a new canvas size
  keeps every box at the same place. An API prompt can set it:
  `{"v": 1, "boxes": [{"x": 0.25, "y": 0.1, "w": 0.5, "h": 0.8, "type": "obj", "text": "", "desc": "a cat", "palette": ["#ff3399"]}]}`.
  A list of pixel boxes in Create Bounding Boxes' own form is read as well.
- A turned box also has `"angle"`: degrees, clockwise on the screen, from -90
  to 90, about the box's centre. `x`, `y`, `w` and `h` stay the box as it was
  drawn, before the turn. Only turned boxes carry the key, and a box without
  it is level, so layouts saved before boxes could turn give exactly what
  they gave. The turn is made in pixels of the canvas the box was drawn on
  (the picture on `background`, when there is one), so a turned box is a true
  rectangle there whatever the canvas's shape.
- For a turned box, `mask` is white at every pixel whose centre is inside the
  turned rectangle. `bboxes` and `elements` hold the straight box around it,
  cut to the canvas: those types only know straight boxes. A text box turned
  2 degrees or more gets "tilted about N degrees, running downhill to the
  right" (clockwise) or "running uphill to the right" added to its
  description in `elements`, after a comma, or as its own sentence when the
  description ends with a full stop; not when the description already says
  it. Object boxes get no such words.
- `elements` holds one element per box, in order:
  `{"type": "obj" or "text", "bbox": [ymin, xmin, ymax, xmax], "text", "desc", "color_palette"}`.
  The place is on a 0 to 1000 grid over the canvas, `text` is there for text
  boxes only, and `color_palette` holds up to five colors when the box has any.
- `bboxes` is a list holding one list of boxes, the form ComfyUI's
  bounding-box nodes pass on. With no boxes it is empty.
- `mask` is one mask (1 x height x width): 1 inside every box, 0 elsewhere,
  with hard edges. With a picture on `background` it has the picture's own
  size, and each box covers the same part of the picture that it covers on
  the canvas. Without a picture it has the canvas size and covers the same
  pixels as `bboxes`. With no boxes it is all 0.
- With a picture on `background`, the canvas on the node is the picture at
  its own size, so the arrow keys move a box one pixel of the picture.
  `width` and `height` still set the pixels `bboxes` counts in and the size of
  `preview`.
- The picture shows before a run when `background` comes from a Load Image,
  straight or through Reroutes. Through a node that changes the picture
  first, such as a resize, it shows after a run.
- Before a run, the canvas can only know a wired size it can read from the
  node it comes from: Latent Size, Integer or a Primitive. From any other
  node, the canvas keeps its own size until a run, and then shows the size
  the run used. Either way the boxes keep their place on the size that
  arrives.
- Like Create Bounding Boxes, it is an output node: it runs with the workflow
  even when nothing is wired to its outputs, so new boxes on the `bboxes` wire
  reach the canvas.
- The background is saved, shrunk, in ComfyUI's temp folder for the node's
  face. Nothing else is written.