transloadit/skills/transform-build-mosaic-collage-with-transloadit

Inputs

• Two or more absolute paths to local input images
• Optional output path; default to an explicit collage.jpg in the current working directory
• Optional canvas size (--width, --height), default 1920×1200
• Optional --seed for deterministic layout

Prepare Instructions

Resolve credentials in this order:

• Shell environment variables
• The current working directory .env only
• ~/.transloadit/credentials

If your .env lives in a parent directory, export the variables into the shell first.

Run

npx -y @transloadit/node image merge \
  --input ./photo-a.jpg \
  --input ./photo-b.jpg \
  --input ./photo-c.jpg \
  --input ./photo-d.jpg \
  --input ./photo-e.jpg \
  --input ./photo-f.jpg \
  --effect mosaic \
  --width 1920 \
  --height 1200 \
  --border 12 \
  --shuffle \
  --format jpg \
  --output ./collage.jpg

After the command finishes, confirm the image exists at the expected output path.

Tuning

• --border 12 sets both the outer canvas padding and the gutter width between tiles. Larger values give more breathing room.
• --background '#eee5d3' fills the gutters and canvas padding (default). Hex codes or named colors both work.
• --background none (with --format png or --format webp) produces a transparent canvas and transparent gutters.
• --shuffle lets the Robot reorder inputs before solving the layout; combine with --seed to pin the shuffle.
• --seed 42 makes the mosaic solver deterministic — rerun with the same inputs to reproduce the same output.

Debug If It Fails

npx -y @transloadit/node assemblies get <assemblyIdOrUrl> -j

Notes:

• Repeated --input values are bundled into a single /image/merge assembly.
• The mosaic effect reads each input's aspect ratio and solves for a justified tile layout — portrait + landscape mixes generally produce more interesting layouts than uniform sizes.
• Tiles are center-cropped to fit their allocated rectangle. Parts of a photo can be cropped off. Resizing inputs beforehand with /image/resize and resize_strategy: fit does not guarantee that the mosaic layout will preserve every pixel.
• Prefer an explicit output filename (e.g. ./collage.jpg or ./collage.png) over a directory output so the extension is deterministic.