ULTIMATE VJ

Output mapping

Output mapping warps the final program image onto one or more surfaces — the feature you reach for when projecting onto an angled wall, a column, or anything that is not a flat rectangle facing you.

Open it from Output settings → Surfaces, or Performance → Output settings….

Mapping is applied to the Output monitor, clean window, PNG snapshot and recording — everything that consumes the final image. Independent clip audition is unwarped. A qualifying sole-live Preview can mirror the mapped program output; see Preview behavior.

Enabling

Toggle Enable surface mapping and build one or more surfaces. Maximum 16, shown as n/16; Add surface disables at the limit.

Surface order is bottom → top. Each surface has a name (1–80 characters), an Enabled flag, an Opacity slider (0…1), flip toggles, an input crop and four output corners.

An enabled setup with zero surfaces outputs black. If the screen goes black right after enabling, add a surface.

Input crop

Four normalized fields — Input X, Input Y, width and height, entered as percentages — selecting which part of the canvas this surface takes.

Output corners

Drag the handles in the preview canvas, or type coordinates as percentages (−200 … 300, where 0–100 spans the canvas). Dragging clamps to −2 … 3.

Requirements, each with its own message:

Rule Message
Coordinates finite and within −2 … 3 "Output corner coordinates must be finite values within −2…3."
Non-degenerate "Output corners must form a nondegenerate convex quadrilateral."
No crossed edges "Output corners must form a convex quadrilateral without crossing edges."

Both clockwise and counter-clockwise windings are accepted. No clamping of saved geometry happens beyond these validation rules.

Applying and resetting

Edits go into a local draft. Only Apply surface — or releasing a dragged corner — writes to the engine. The UI note spells it out: "Apply to update output. Dragging a corner applies on release. Presets and application output setup are independent of composition changes. The clip preview stays unmapped."

That help text describes independent audition. Sole-live Preview mirroring can instead show the final program, including output mapping: see Preview behavior.

Runtime failures do not crash anything: the mapper returns a black canvas plus an issue string, which surfaces in the view. Messages include "Output dimensions must be within 1–8192 pixels.", "Output mapping requires a finite, nonempty input image." and "Surface could not produce a finite perspective transform."

Per-surface controls

Reorder with Back / Front; use Duplicate and Remove surface. Flip with Flip X and Flip Y. Fade a surface with Opacity.

Presets

Load preset… / Save preset…

There are three places this geometry can live, which is what trips people up:

Storage File Lifetime
Portable preset <name>.uvjoutput, wherever you save it Explicit
Application-wide setup ~/Library/Application Support/ULTIMATEVJ/OutputMapping.json Saved on every change; explicit New/Open preserves it

Output geometry is also embedded in each saved .uvj set, so a set carries its own mapping with it.

What mapping actually is

Each surface is a Core Image perspective transform with its opacity applied as the alpha row of a colour matrix, composited source-over. Dimensions are clamped to 1–8192.

This means the current implementation is rectangular crop plus four-corner perspective per surface. There is no mesh warping, no masks, no soft-edge blending and no per-surface colour grading. See Limitations.

Not verified

Opacity reset

The surface-opacity slider offers a right-click zero action. It changes the local surface draft; press Apply surface to commit it, just as with other surface edits.