Lenticle

A lenticular print hides several pictures under a sheet of tiny ridged lenses. Each ridge shows you a different strip of the pictures underneath depending on where your eye is, so tilting the print swaps one picture for another. Lenticle does the same thing with the motion sensors in a phone: the file carries several full pictures and a short description of the effect, and the viewer blends between them as you tilt.

The two halves

A Lenticle file has two kinds of content. Layers are the pictures, all the same size. Metadata is a small text block that says what should happen when the phone moves. The metadata only describes the intent; the viewer decides how to render it. That split is what lets the format stay simple while viewers get better.

Layers

Layer 0 is special. It is stored as an ordinary PNG, which means any program that opens PNG files will show it, even if it has never heard of Lenticle. Choose it as the picture that should survive on its own. In the grandmother example, layer 0 is the grandmother alone and layer 1 is the grandmother with the toddler, so a plain viewer sees a complete photograph and the Lenticle viewer adds the toddler as you tilt.

Layers 1 and up are stored inside the same file as complete JPEG or PNG images. The creator crops every picture to the shape of layer 0 and scales them all to the same size, because the viewer draws them exactly on top of each other. For the effect to look right, the pictures should line up: shoot or scan them in the same framing, or make the second from the first.

The axis

Everything the viewer does is driven by one number, t, that runs from −1 to +1. Zero is the rest pose, the angle you were holding the phone at when the file opened. Tilting one way pushes t toward +1, the other way toward −1. Each layer sits at a position on this axis, called at. The viewer finds the two layers on either side of the current t and blends between them.

FIG_001
T = −1T = 0T = +1 REST POSE · RECENTER SETS THIS LAYER 0 · AT 0 LAYER 1 · AT 1 ← BLEND → CLAMPED TO LAYER 0

With two layers the creator places them at 0 and +1, so the rest pose shows layer 0 cleanly and tilting forward fades layer 1 in. Tilting backward stays on layer 0. With three layers the default is −1, 0 and +1: the middle picture at rest, one picture in each direction. You can type any positions you like in the creator; the only rule is they stay between −1 and +1.

Fields in the metadata

axispitch is tilting the top of the phone toward or away from you, the way you would tip a print to catch the light. roll is tilting the phone left or right, like turning a steering wheel. Pitch is the default and matches the way flip prints are usually made.
rangeHow many degrees of tilt it takes to travel the whole axis from −1 to +1. The default of 40 means ±20° around the rest pose. A smaller range makes the effect snappier, a larger one gives finer control. Beyond the range the viewer simply holds the end picture.
transitioncrossfade dissolves one layer into the next, the ghosting you see on a real print half way through a tilt. cut switches hard at the midpoint, like a print with a very sharp lens.
curveShapes the crossfade. linear maps tilt to opacity one to one. smoothstep holds each picture a little longer at the ends and moves faster in the middle, which feels closer to a lens flipping over. Ignored when the transition is cut.
layers[].atWhere each layer sits on the axis, as described above.
layers[].labelA name for your own reference. Viewers may show it; nothing depends on it.

Anything a viewer does not recognise it ignores. Unknown values fall back to the defaults with a warning in the status strip. The version number at the top of the metadata lets a future viewer tell a v1 file from a later one.

What the viewer does

What the creator does

How the file is built

A PNG is a signature followed by a list of chunks. Each chunk is a length, a four letter type, the data, and a checksum. PNG lets anyone add private chunk types as long as the first letter is lowercase, which tells decoders they may skip it. Lenticle adds two.

FIG_002
89 50 4E 47 0D 0A 1A 0A   PNG signature
IHDR   width, height, bit depth, colour type
lnMD   metadata, UTF-8 JSON          ← ours
IDAT   layer 0 pixels                 ← what any viewer shows
lnLY   layer 1: 8-byte header + JPEG  ← ours
lnLY   layer 2 ...                    ← ours
IEND

The metadata goes before the pixels so a reader knows what it has before downloading the big part. The extra layers go after the pixels so layer 0 can appear before the rest arrives. Each extra layer starts with an eight byte header giving its index, its codec, and its width and height, followed by a complete image file. The viewer hands that image to the browser to decode, so it needs no decoder of its own.

Every chunk, including ours, carries a CRC-32 checksum. If a byte is damaged in transit the viewer notices and falls back to layer 0 with a message naming the chunk. The full byte-level description is in the spec.

Tips for good results