Scripts¶

scripts/image-filer.py¶

Reads images from a camera’s memory card or other flat directory structure, finds runs of images and files them into subdirectories. A run is found by the EXIF timestamp in the image files.

The script also builds a full light position map sample.lp from a light position skeleton file and files it alongside the images files.

Some cameras put a maximum of 1000 pictures into a folder. After that they automatically open a new folder. If this happened during a shooting, include both directories on the commandline. The script will sort it out for you.

usage: scripts/image-filer.py [-h] [-v] [-l LP] FILES [FILES ...]

files¶: the image files to file (wildcards supported)

-h, --help¶: show this help message and exit

-v, --verbose¶: increase output verbosity

-l <lp>, --lights <lp>¶: the skeleton light positions file (default: skeleton.lp)

scripts/image-converter.py¶

This script is a wrapper that can pass image files through a converter before calling the ptm-encoder.

With the help of this script you may crop / resize / rotate your images before processing them with the ptm-encoder. Temporary files are created for the encoder, the original files are kept intact.

Write a shell script and chmod +x it. The shell script must process the source image, apply all wanted transformations and save the destination image. The source image path and filename will be $1 and the destination path and filename will be $2. The destination will point to a temp directory.

An example of a shell script follows:

#!/bin/bash
convert "$1" -crop 2800x2800+2236+1064 -resize 2000x2000 "$2"

An example of a command to build one PTM is then:

scripts/image-converter.py -f runs/a/convert.sh \
   bin/ptm-encoder -f PTM_FORMAT_JPEG_LRGB -o a.ptm runs/a/sample.lp

Alternatively you can do without the shell script and put the contents of the script in the command line. The placeholders “{source}” and “{dest}” will be replaced by the source and destination filenames.

The command to build one PTM is then:

scripts/image-converter.py -e 'convert "{source}" -crop 2800x2800+2236+1064 -resize 2000x2000 "{dest}"' \
   bin/ptm-encoder -f PTM_FORMAT_JPEG_LRGB -o a.ptm runs/a/sample.lp

usage: scripts/image-converter.py [-h] [-v]
                                  (-e "COMMANDLINE" | -f SCRIPT-FILE)
                                  ENCODER ...

encoder¶: the PTM encoder executable

...: arguments to the PTM encoder

-h, --help¶: show this help message and exit

-v, --verbose¶: increase output verbosity

-e <"commandline">, --exec <"commandline">¶: execute COMMANDLINE with every image

-f <script-file>, --file <script-file>¶: execute SCRIPT-FILE with every image

scripts/lp-builder.py¶

Build the light position file for Dome 1.

Outputs to stdout a skeleton sample.lp file with light positions according to the Ø 50cm prototype dome at CCeH.

This script is hard-coded to one specific dome but it may serve as example for writing a more general script for other domes.

usage: scripts/lp-builder.py [-h] [-a ANGLE] [-v]

-h, --help¶: show this help message and exit

-a <angle>, --angle <angle>¶: the rotation angle of the camera on the Dome (default 0°)

-v, --verbose¶: increase output verbosity

bin/ptm-encoder¶

Encode a series of JPEG files into one PTM file.

Reads a sample.lp file with a list of the JPEG files to encode. You can build a sample.lp file using the image filer script.

usage: ptm-encoder [OPTION...] sample.lp

-f, --format¶: Which PTM format to output (default: PTM_FORMAT_RGB).

-l, --list¶

Output a list of supported PTM formats, eg:

PTM_FORMAT_RGB,
PTM_FORMAT_LRGB,
PTM_FORMAT_JPEG_RGB,
PTM_FORMAT_JPEG_LRGB.

-o, --output=<FILE>¶: Output to FILE instead of STDOUT.

-v, --verbose¶: Produce verbose output.

-?, --help¶: Give this help list.

--usage¶: Give a short usage message.

-V, --version¶: Print program version.

bin/ptm-decoder¶

Extract one JPEG out of a PTM file.

The output goes to stdout, so the program is easy to use in a web server.

usage: ptm-decoder filename.ptm [u v] > filename.jpg

u v¶: Set the light position for the JPEG. Defaults to 0.5 and 0.5, that is, lighted from top right. See: sample.lp.

bin/ptm-exploder¶

Explode one PTM into multiple JPEGs lighted from different angles.

usage: ptm-exploder filename.ptm sample.lp filename.jpeg

The sample.lp file should be of the same format used by the PTM encoder script, although the filename part is not used by the exploder. Instead the filename to use is provided in the 3rd argument and is changed into into filename-NNN.jpeg for each image.

sample.lp file format¶

The sample.lp file contains a light position map that relates picture files to lighting positions. It is needed by the PTM encoder program.

The format of this file is:

filename01 u01 v01 w01
filename02 u02 v02 w02
filename03 u03 v03 w03
...
filenameNN uNN vNN wNN

The filenames are relative to the sample.lp file. $u$, $v$ and $w$ are the cartesian coordinates of the light source from the center of the dome and lie on the unity sphere, ie. the radius of the dome is defined as 1. Every pair of $u$ and $v$ values must obey $u^2 + v^2 \le 1$. $w$ may be specified, but is not used since it is redundant.