Platform independent tools for working with Lytro LFP files
===========================================================

Lytro has not announced much about their file formats other than that they
have software for OS X and will have Windows supported in 2012.  To enable 
support for other platforms, it will be useful to develop open source software
to process their files.

This tool supports both the large raw files that come from the Lytro camera
and the compressed files that the desktop software produces for web display.

Note: The description below refers to .lfp file format for files generated
using Lytro's Version 1 processing software. See README_V2 for a description
of .lfp format changes as of Lytro's December 2012 update (Version 2).

.lfp file format
----------------

The file itself is formatted as follows.  First, a header:

    # magic 12 byte header (LFP)
    89 4C 46 50 0D 0A 1A 0A 00 00 00 01
    # 4 byte length (0, since there is nothing in this section)
    00 00 00 00
    
After this are a number of sections.  The data in the first is plain text
JSON table of contents describing what the rest of the sections in the file
contain.  The remaining sections can be additional metadata, a depth lookup
table, compressed jpg images, or raw sensor data depending on the file.
The sections are formatted as follows:
    
    # magic 12 byte header (containing a type like LFM or LFC)
    89 4C 46 4D 0D 0A 1A 0A 00 00 00 00
    # 4 byte length, not including header, sha1, or null padding
    00 00 07 A7
    # 45 bytes of sha1 hash as hex in ascii
    73 68 61 31 ...
    # 35 bytes of null padding
    00 00 00 00 ...
    # the data of length previously specified
    7B 22 70 69 ...
    # 0 or more bytes of null padding
    00 00 00 00 ...

.lfp web files
--------------

The Lytro desktop app exports compressed representations of the light field
captured by the Lytro camera to reduce file times and rendering requirements
for web display.  The .lfp files are simply a set of JPEG files representing
the unique visually interesting sections of the light field.  That is, a set in
which each image shows a different area in focus.  It appears to do so
dynamically, picking the minimum number of images necessary to show all
*focusable* objects in narrow depths of field.

These images are stored along with their estimated depths and a depth lookup
table for the image.  This allows for HTML5 and Flash applications in which the
user clicks on a region of the image, the value of that region is looked up,
and the depth image closest to that value is displayed.

.lfp raw files
--------------
The files that come directly from the camera are roughly 16MB, made primarily
of one section which is a raw Bayer array of the 3280 x 3280 pixel sensor.
There are also two metadata files, one containing detailed information about
the format of the captured image, and the other containing serial numbers.

lfpsplitter
-----------

lfpsplitter is a commandline tool that reads in a .lfp file and splits it into
a plaintext metadata file, a plaintext listing of the depth lookup table, and
the component jpgs.

    make
        gcc -O3 -Wall    -c -o lfpsplitter.o lfpsplitter.c
        gcc -o lfpsplitter lfpsplitter.o  -O3 -Wall 

    ./lfpsplitter IMG_0001.lfp
        Saved IMG_0001_table.json
        Saved IMG_0001_imageRef0.raw
        Saved IMG_0001_metadataRef.json
        Saved IMG_0001_privateMetadataRef.json

    ./lfpsplitter IMG_0001-stk.lfp
        Saved IMG_0001-stk_table.json
        Saved IMG_0001-stk_depth.txt
        Saved IMG_0001-stk_0.jpg
        Saved IMG_0001-stk_1.jpg
        Saved IMG_0001-stk_2.jpg
        Saved IMG_0001-stk_3.jpg