# Lenticle File Format Specification

Version 1.0
Status: Final
Date: 2026-11-16

## Abstract

This document specifies the Lenticle file format, a container for a set of
co-registered raster image layers together with declarative metadata that
describes how a viewer shall select and blend those layers in response to a
one-dimensional tilt input. A Lenticle file is a conforming Portable Network
Graphics (PNG) datastream extended with two private ancillary chunk types.
Decoders that do not implement this specification render the first layer as
an ordinary PNG image.

## Table of contents

1. Scope
2. Conformance
3. Normative references
4. Terms and definitions
5. Identification
6. Datastream structure
7. The lnMD chunk
8. The lnLY chunk
9. Rendering model
10. Decoding procedure
11. Encoding requirements
12. Versioning and extensibility
13. Security considerations
Annex A (informative): Design rationale
Annex B (informative): Example datastream
Annex C (informative): Test vectors

---

## 1. Scope

This specification defines:

- the byte-level structure of a Lenticle datastream;
- the semantics of the metadata that governs layer selection and blending;
- the requirements that encoders and decoders shall satisfy to claim
  conformance;
- the rules under which the format may be extended in later versions.

This specification does not define a sensor interface, a smoothing or
filtering method for sensor input, a user interface, or a transport. Those
are properties of a viewer, not of the file.

## 2. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted as
described in RFC 2119.

Two conformance classes are defined.

**Conforming encoder.** An implementation that produces datastreams. It MUST
satisfy every requirement in clauses 5 through 8 and clause 11.

**Conforming decoder.** An implementation that consumes datastreams. It MUST
satisfy every requirement in clauses 5 through 10, including the fallback
behaviour of clause 10.4.

A datastream is a *conforming Lenticle datastream* when it satisfies every
requirement in clauses 5 through 8.

## 3. Normative references

- ISO/IEC 15948:2004, *Portable Network Graphics (PNG): Functional
  specification*. Equivalent to W3C Recommendation "PNG Specification
  (Second Edition)".
- RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*.
- RFC 8259, *The JavaScript Object Notation (JSON) Data Interchange Format*.
- RFC 3629, *UTF-8, a transformation format of ISO 10646*.
- ISO/IEC 10918-1, *Digital compression and coding of continuous-tone still
  images (JPEG)*, together with the JFIF file interchange format.

## 4. Terms and definitions

**datastream** — the complete sequence of bytes constituting a Lenticle file.

**chunk** — the PNG unit of structure: a length field, a type field, a data
field and a CRC field, as defined in ISO/IEC 15948 clause 5.3.

**base image** — the image encoded by the PNG IHDR, PLTE (if present) and IDAT
chunks of the datastream. The base image is layer 0.

**layer** — one of N raster images of identical pixel dimensions carried by
the datastream, numbered 0 to N−1. Layer 0 is the base image; layers 1 to N−1
are carried in lnLY chunks.

**layer count (N)** — the number of layers in the datastream. N ≥ 2.

**axis** — the closed real interval [−1, +1] on which layers are positioned
and along which a viewer's tilt input is mapped.

**axis position (t)** — a value on the axis derived by a viewer from its
tilt input at a given instant.

**rest pose** — the physical device orientation that a viewer maps to t = 0.

**range** — the total angular extent, in degrees, that a viewer maps onto the
axis.

**nested image** — a complete image file, in a codec listed in clause 8.3,
carried as the payload of an lnLY chunk.

All multi-byte integers in this specification are unsigned and are stored
most significant byte first (network byte order), in accordance with
ISO/IEC 15948 clause 7.1. The notation u8, u16 and u32 denotes unsigned
integers of 1, 2 and 4 bytes respectively.

## 5. Identification

5.1 A Lenticle datastream MUST begin with the PNG signature:

    89 50 4E 47 0D 0A 1A 0A

5.2 The RECOMMENDED file name extension is `.lnt`. A datastream MAY also be
stored with the extension `.png`; its content is identical.

5.3 The media type of a Lenticle datastream for the purposes of content
sniffing is `image/png`. The media type `image/vnd.lenticle` is reserved for
contexts that distinguish Lenticle datastreams from other PNG datastreams.

5.4 A decoder MUST NOT rely on the file name extension to determine whether a
datastream is a Lenticle datastream. The presence of a valid lnMD chunk
(clause 7) is the sole determinant.

## 6. Datastream structure

6.1 A Lenticle datastream MUST be a conforming PNG datastream as defined in
ISO/IEC 15948. All requirements of that specification apply, including chunk
layout, CRC computation and the ordering constraints on standard chunks.

6.2 In addition to the chunks permitted by ISO/IEC 15948, a Lenticle
datastream contains:

- exactly one lnMD chunk (clause 7);
- N−1 lnLY chunks (clause 8), where N is the layer count.

6.3 Chunk layout. Each chunk consists of the following fields in order, as
defined by ISO/IEC 15948 clause 5.3:

| Field  | Size | Description |
|--------|------|-------------|
| Length | u32  | Number of bytes in the Data field. MUST NOT exceed 2³¹−1. |
| Type   | 4 bytes | Chunk type code, ASCII letters. |
| Data   | Length bytes | Chunk content. |
| CRC    | u32  | CRC-32 computed over the Type and Data fields, excluding the Length field. |

6.4 CRC algorithm. The CRC field MUST be computed with the CRC-32 algorithm
specified in ISO/IEC 15948 clause 5.5 and Annex D: generator polynomial
`0xEDB88320` (reflected representation of x³²+x²⁶+x²³+x²²+x¹⁶+x¹²+x¹¹+x¹⁰+x⁸+x⁷+x⁵+x⁴+x²+x+1),
initial register value `0xFFFFFFFF`, final complement `0xFFFFFFFF`. This is
the algorithm commonly known as the zlib or ISO 3309 CRC-32.

6.5 Chunk ordering. The following ordering constraints apply in addition to
those of ISO/IEC 15948:

(a) The lnMD chunk MUST appear after the IHDR chunk and before the first IDAT
chunk.

(b) Every lnLY chunk MUST appear after the last IDAT chunk and before the IEND
chunk.

(c) lnLY chunks MUST appear in strictly ascending order of their Index field
(clause 8.2), beginning at 1 and without gaps.

6.6 Overall layout. The resulting datastream has the following structure.
Standard ancillary chunks permitted by ISO/IEC 15948 MAY appear at any
position allowed by that specification and are not shown.

    Offset    Size     Content
    0         8        PNG signature
    8         25       IHDR chunk (13 data bytes)
    33        var      lnMD chunk
    ...       var      IDAT chunk(s): layer 0
    ...       var      lnLY chunk: layer 1
    ...       var      lnLY chunk: layer 2
    ...       ...      ...
    ...       var      lnLY chunk: layer N−1
    EOF−12    12       IEND chunk

6.7 Chunk type codes. The chunk types defined by this specification are
`lnMD` and `lnLY`. Their property bits, as defined in ISO/IEC 15948 clause
5.4, are:

| Byte | Letter | Case | Property |
|------|--------|------|----------|
| 1 | `l` | lower | Ancillary. Decoders not implementing this specification MUST ignore the chunk. |
| 2 | `n` | lower | Private. The type is not registered with the PNG Registration Authority. |
| 3 | `M` / `L` | upper | Reserved. MUST be upper case in a conforming datastream. |
| 4 | `D` / `Y` | upper | Not safe to copy. An editor that modifies critical chunks MUST NOT copy the chunk to the output datastream. |

## 7. The lnMD chunk

7.1 Purpose. The lnMD chunk carries the declarative metadata that identifies
the datastream as a Lenticle datastream and governs rendering.

7.2 Cardinality. A conforming datastream MUST contain exactly one lnMD chunk.
A decoder encountering more than one MUST use the first in datastream order
and SHOULD report the condition.

7.3 Encoding. The Data field MUST be a JSON text as defined in RFC 8259,
encoded in UTF-8 as defined in RFC 3629, without a byte order mark and without
a terminating NUL byte. The top-level value MUST be a JSON object.

7.4 Members. The following members are defined. Member names are
case-sensitive.

| Member | Type | Presence | Constraint | Semantics |
|--------|------|----------|------------|-----------|
| `lenticle` | number | REQUIRED | Positive integer | Major version of this specification to which the datastream conforms. Datastreams conforming to this document MUST set the value 1. |
| `axis` | string | OPTIONAL | `"pitch"` or `"roll"` | The tilt axis that drives t. Default `"pitch"`. See clause 9.2. |
| `range` | number | OPTIONAL | > 0 | Total angular extent in degrees mapped onto the axis. Default 40. See clause 9.2. |
| `transition` | string | OPTIONAL | `"crossfade"` or `"cut"` | Blending mode between adjacent layers. Default `"crossfade"`. See clause 9.4. |
| `curve` | string | OPTIONAL | `"linear"` or `"smoothstep"` | Response curve applied to the blend fraction. Default `"smoothstep"`. See clause 9.4. |
| `layers` | array | REQUIRED | Length equal to N | One layer descriptor per layer, in layer index order. |

7.5 Layer descriptor. Each element of `layers` MUST be a JSON object with the
following members.

| Member | Type | Presence | Constraint | Semantics |
|--------|------|----------|------------|-----------|
| `at` | number | REQUIRED | −1 ≤ at ≤ +1 | Position of the layer on the axis. |
| `label` | string | OPTIONAL | — | Human-readable name. Carries no rendering semantics. |

7.6 Element i of `layers` describes layer i. Element 0 describes the base
image.

7.7 Two or more layers MAY share the same `at` value. The behaviour in that
case is defined in clause 9.3.

7.8 Members not defined in this specification MAY be present. A decoder MUST
ignore members it does not recognise. See clause 12.

## 8. The lnLY chunk

8.1 Purpose. An lnLY chunk carries one layer other than the base image.

8.2 Data layout. The Data field consists of an 8-byte header followed by a
nested image.

| Offset | Type | Field | Constraint |
|--------|------|-------|------------|
| 0 | u8 | Index | 1 ≤ Index ≤ 255. The layer number. The value 0 is reserved for the base image and MUST NOT appear. |
| 1 | u8 | Codec | A value from clause 8.3. |
| 2 | u16 | Width | MUST equal the Width field of IHDR. |
| 4 | u16 | Height | MUST equal the Height field of IHDR. |
| 6 | u16 | Flags | MUST be 0 in datastreams conforming to this document. |
| 8 | var | Payload | A complete nested image in the codec given by Codec, extending to the end of the Data field. |

8.3 Codec values.

| Value | Codec | Payload format |
|-------|-------|----------------|
| 0 | PNG | A complete PNG datastream per ISO/IEC 15948. |
| 1 | JPEG | A complete JFIF datastream per ISO/IEC 10918-1. |
| 2 | WebP | Reserved. Encoders conforming to this document MUST NOT emit this value. |
| 3–255 | — | Reserved for future versions. |

8.4 The decoded pixel dimensions of the Payload MUST equal Width and Height.
The Width and Height fields therefore duplicate information in the Payload;
the duplication is normative and permits validation without decoding.

8.5 Because the Width and Height fields are u16, every layer in a conforming
datastream, including the base image, has dimensions not exceeding 65535
pixels on either side.

8.6 Colour. The Payload's colour space SHOULD match that of the base image.
A decoder MAY apply the base image's colour-management chunks (sRGB, gAMA,
iCCP) to all layers.

8.7 Flags. Bits of the Flags field are reserved. A decoder MUST ignore bits
it does not recognise and SHOULD report a non-zero value.

## 9. Rendering model

9.1 This clause defines the mapping from an axis position t to a rendered
image. It is normative for the result and informative for the method: a
decoder MAY use any technique that produces the same image.

9.2 Axis position. A viewer derives t from its tilt input as follows. Let θ be
the current angle about the selected axis, in degrees, and θ₀ the angle at
the rest pose. Then

    t = clamp( (θ − θ₀) / (range / 2), −1, +1 ).

For `axis` = `"pitch"`, θ is rotation about the device's horizontal screen
axis, and positive t corresponds to the top edge of the screen rotating
toward the viewer. For `axis` = `"roll"`, θ is rotation about the device's
vertical screen axis, and positive t corresponds to the right edge of the
screen rotating downward. The method by which a viewer determines θ₀, and
any filtering applied to θ, are outside the scope of this specification.
A viewer without tilt input MAY derive t from any other control.

9.3 Layer selection. Let the layers be ordered by ascending `at`, with ties
broken by ascending layer index. Let L be the layer with the smallest `at`
and U the layer with the largest.

(a) If t ≤ at(L), the rendered image is layer L.

(b) If t ≥ at(U), the rendered image is layer U.

(c) Otherwise let A and B be adjacent layers in the ordering such that
at(A) ≤ t ≤ at(B) and at(A) < at(B). The raw blend fraction is

    u = (t − at(A)) / (at(B) − at(A)).

If more than one pair satisfies the condition, the pair with the smallest
at(A) SHALL be chosen.

9.4 Blend fraction. The effective fraction u′ is derived from u:

- `transition` = `"cut"`: u′ = 0 if u < 0.5, otherwise u′ = 1.
- `transition` = `"crossfade"`, `curve` = `"linear"`: u′ = u.
- `transition` = `"crossfade"`, `curve` = `"smoothstep"`: u′ = u²(3 − 2u).

9.5 Composition. The rendered image is layer A composited beneath layer B,
where B has uniform opacity u′ and A is opaque, using normal (source-over)
compositing in the working colour space of the viewer. Layers other than A
and B do not contribute.

## 10. Decoding procedure

10.1 A conforming decoder SHALL perform the following steps in order.

1. Verify the PNG signature (clause 5.1). On failure, the datastream is not a
   PNG datastream; proceed to clause 10.4(b).
2. Read all chunks (clause 6.3). Verify the CRC of every chunk (clause 6.4).
   Verify that the first chunk is IHDR and that an IEND chunk is present.
3. Locate the lnMD chunk. If absent, the datastream is a PNG datastream that
   is not a Lenticle datastream; proceed to clause 10.4(a).
4. Parse the lnMD Data field as JSON (clause 7.3). Verify that `lenticle` is
   present, numeric, and that its integer part is not greater than the major
   version implemented by the decoder.
5. Apply defaults to absent optional members (clause 7.4). Replace an optional
   member holding an unrecognised value with its default and report the
   condition.
6. Decode each lnLY header (clause 8.2). Verify ordering (clause 6.5(c)),
   codec (clause 8.3) and dimensions (clause 8.2, 8.4).
7. Verify that `layers` has exactly N elements and that every `at` lies in
   [−1, +1].
8. Decode the base image and every nested image.

10.2 A datastream that passes every verification in clause 10.1 is accepted
and SHALL be rendered according to clause 9.

10.3 A verification failure in steps 1 through 8 is an error. A decoder MUST
report at least the first error it encounters and SHALL apply clause 10.4.

10.4 Fallback. On error:

(a) If the datastream is a valid PNG datastream (steps 1 and 2 succeeded, or
step 2 failed only because of a CRC mismatch in an lnMD or lnLY chunk), the
decoder MUST render the base image as an ordinary PNG image and MUST NOT
render any lnLY payload.

(b) Otherwise the decoder MUST indicate failure and MUST NOT render partial
content as though it were a valid image.

10.5 Reporting. Conditions that this specification designates as reportable
but not as errors (duplicate lnMD, unrecognised optional values, non-zero
Flags, unrecognised members) are warnings. A decoder SHOULD make warnings
available to the user and MUST NOT treat them as grounds for fallback.

## 11. Encoding requirements

11.1 An encoder MUST produce a datastream satisfying clauses 5 through 8.

11.2 An encoder MUST assign `at` values and lnLY Index values such that
element i of `layers` corresponds to the layer carried at Index i.

11.3 An encoder MUST emit all layers with identical pixel dimensions. Where
source images differ, the encoder SHALL resample or crop them before
encoding; the method is at the encoder's discretion.

11.4 An encoder SHOULD emit the lnMD chunk immediately after IHDR and the
lnLY chunks immediately after the last IDAT chunk.

11.5 An encoder that derives its base image from an existing PNG datastream
MUST remove any lnMD and lnLY chunks present in the source before inserting
its own.

11.6 An encoder MUST recompute the CRC of every chunk it emits.

## 12. Versioning and extensibility

12.1 The `lenticle` member carries the major version. A change that would
cause a conforming decoder of the previous version to render a datastream
incorrectly MUST increment the major version. A decoder MUST reject a
datastream whose major version exceeds the version it implements, applying
clause 10.4(a).

12.2 Additions that a previous-version decoder can safely ignore, such as new
optional members of lnMD or new bits of Flags, do not increment the major
version. Decoders MUST ignore unrecognised members and bits for this reason.

12.3 A change to the layout of the lnLY Data field MUST be made by defining a
new chunk type rather than by altering the meaning of existing fields. This
follows the extension practice of ISO/IEC 15948.

12.4 The following identifiers are reserved for future use and MUST NOT be
assigned other meanings by implementations: the lnMD member name `look`; the
lnMD member `axis` as a JSON object; lnLY Codec value 2; all non-zero lnLY
Flags bits.

## 13. Security considerations

13.1 A Lenticle datastream contains nested image datastreams. A decoder
inherits every vulnerability of the PNG and JPEG decoders it employs and
SHOULD use decoders that are hardened against malformed input.

13.2 The lnMD chunk is parsed as JSON. Decoders MUST bound the size of the
chunk they are willing to parse and MUST NOT evaluate its content as code.

13.3 The Length field of a chunk is attacker-controlled. Decoders MUST verify
that Length does not exceed the remaining datastream before reading the Data
field (clause 6.3).

13.4 Nothing in this specification causes a decoder to perform network
access or to execute content.

---

## Annex A (informative): Design rationale

A.1 Container. Three families of container were evaluated: PNG with private
ancillary chunks; RIFF-based WebP and ISOBMFF-based HEIF with custom boxes;
and a purpose-designed binary container. PNG was selected on four grounds.
First, ISO/IEC 15948 requires decoders to ignore unrecognised ancillary
chunks, so the fallback behaviour of clause 10.4 is guaranteed by the host
format rather than by this specification. Second, the chunk structure is
uniform, self-delimiting and individually checksummed, which simplifies
validation and inspection. Third, PNG encoding is universally available in
browser environments, whereas WebP encoding is absent from WebKit and HEIF
encoding is absent from all browsers, which would have constrained encoders.
Fourth, the APNG extension demonstrates that the ancillary-chunk mechanism
supports exactly this class of extension in practice. The principal cost is
the lossless encoding of the base image; clause 8.3 mitigates it by allowing
JPEG for every other layer.

A.2 Nested images. Layers are carried as complete image files rather than as
raw samples so that decoders can delegate decompression to an existing image
decoder and so that each layer can use a codec suited to its content. The
same technique is used for thumbnails in HEIF and for gain maps in Ultra HDR
JPEG.

A.3 Normalised axis. Layer positions are expressed on the dimensionless axis
[−1, +1] rather than in degrees because the physical angle at which a device
is held varies between users and sessions. The datastream specifies only the
angular extent of the effect; the viewer supplies the rest pose. This also
makes the model independent of the number of layers.

A.4 Structural fallback. No member identifies a fallback layer. The base
image is the fallback by construction, which cannot be contradicted by
metadata.

A.5 Separation of concerns. Sensor filtering is excluded from the datastream
because it characterises the viewer's input device, not the image. Keeping it
out of the file allows viewers to improve without invalidating existing
content.

A.6 Mixed metadata encodings. The lnMD chunk uses JSON and the lnLY header
uses fixed binary fields. JSON offers extensibility by member name at
negligible cost for a chunk of a few hundred bytes. The lnLY header is fixed
binary because it is validated before any decoding occurs and because its
fields have fixed widths. ISO/IEC 15948 itself follows the same pattern, with
binary IHDR and textual tEXt and iTXt chunks.

## Annex B (informative): Example datastream

B.1 The following lnMD content describes a two-layer datastream in which the
rest pose shows the base image and forward tilt reveals layer 1.

```json
{
  "lenticle": 1,
  "axis": "pitch",
  "range": 40,
  "transition": "crossfade",
  "curve": "smoothstep",
  "layers": [
    { "at": 0, "label": "grandmother" },
    { "at": 1, "label": "with toddler" }
  ]
}
```

B.2 Chunk table of the reference sample `samples/demo.lnt`, as produced
by `tools/lntinfo.py`:

        offset     length  type  crc       properties
             8         13  IHDR  cbaa3c05  critical, public, unsafe-to-copy
    *       33        224  lnMD  c7368c1a  ancillary, private, unsafe-to-copy
           269       4005  IDAT  f1798ab7  critical, public, unsafe-to-copy
    *     4286       2654  lnLY  24d914c7  ancillary, private, unsafe-to-copy
          6952          0  IEND  ae426082  critical, public, unsafe-to-copy

B.3 Bytes of the lnLY chunk at offset 0x10BE of the same sample:

    000010be  00 00 0a 5e 6c 6e 4c 59 01 00 01 e0 02 80 00 00
    000010ce  89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52

Interpretation: Length = 0x00000A5E (2654); Type = "lnLY"; Index = 1;
Codec = 0 (PNG); Width = 0x01E0 (480); Height = 0x0280 (640); Flags = 0;
the Payload begins at offset 0x10CE with a PNG signature.

## Annex C (informative): Test vectors

C.1 CRC-32 of the ASCII string `123456789` is `0xCBF43926`.

C.2 CRC-32 of the IEND chunk (Type "IEND", empty Data) is `0xAE426082`.

C.3 An lnLY header for layer 1, codec JPEG, 1600 × 1200 pixels, is

    01 01 06 40 04 B0 00 00
