ptmlib¶

This is the developer documentation for the PTM function library.

ptmlib.h¶

Defines

PTM_COEFFICIENTS¶: The no. of coefficients used by PTM to describe one pixel.

RGB_COEFFICIENTS¶: The no. of extra channels used by PTM to describe one pixel in RGB color mode.

CBCR_COEFFICIENTS¶: The no. of extra channels used by PTM to describe one pixel in CBCR color mode.

MAX_PTM_BLOCKS¶: The maximal no. of PTM coefficient blocks used in PTM.

MAX_COLOR_COMPONENTS¶: The maximal no. of color components used by libjpeg in any mode.

MAX_JPEG_STREAMS¶: The maximal no. of JPEG streams that a PTM file can contain.

LUM(r, g, b)¶

Typedefs

typedef JSAMPLE *ptm_block_t¶: An array holding one block of either scaled PTM coefficients or RGB values.

Enums

enum ptm_formats_enum_t¶

An enumeration of the supported formats.

Values:

PTM_FORMAT_RGB = 1¶

PTM_FORMAT_LUM¶

PTM_FORMAT_LRGB¶

PTM_FORMAT_JPEG_RGB¶

PTM_FORMAT_JPEG_LRGB¶

Functions

JSAMPLE CLIP(float f)¶: Clip against inter-sample overflow: While all samples may be in the range [0..255] the reconstructed curve may well go beyond that range. Made an inline function instead of a macro to avoid multiple evaluation of POLY.

const ptm_format_t *ptm_get_format(const char *format_name)¶

Get a format by name.

Return

A pointer to a ptm_format_t struct.

Parameters

format_name: The name of the format.

ptm_header_t *ptm_alloc_header()¶

Allocate a PTM header structure. Free this structure with free().

Return: A pointer to the allocated header struct.

ptm_block_t *ptm_alloc_blocks(ptm_header_t *ptm_header)¶

Allocate a struct that will contain 1 or 3 pointers to PTM blocks followed by zero or one pointer to a RGB block. Free this struct with ptm_free_blocks().

Return

A pointer to the allocated block struct.

Parameters

ptm_header: A pointer to an initialized ptm_header_t struct.

void ptm_free_blocks(ptm_header_t *ptm_header, ptm_block_t *blocks)¶

Free the structure allocated by ptm_free_blocks().

Parameters

ptm_header: A pointer to an initialized ptm_header_t struct.
blocks: The structure to free.

ptm_header_t *ptm_read_header(FILE *fp)¶

Read the header section of a PTM file.

Return

A ptm_header_t struct filled with information.

Parameters

fp: A file pointer to a file openfor reading.

void ptm_write_header(FILE *fp, ptm_header_t *ptm_header)¶

Write the header section of a PTM file.

Parameters

fp: A file pointer to a file open for writing.
ptm_header: A pointer to an initialized ptm_header_t struct.

void ptm_read_ptm(FILE *fp, ptm_header_t *ptm_header, ptm_block_t *blocks)¶

Read the blocks from a PTM file.

Does automatic JPEG decoding if the PTM format requires it.

Parameters

fp: File pointer.
ptm_header: A pointer to an initialized ptm_header_t struct.
blocks: A pointer to an allocated ptm_block_t struct.

void ptm_write_ptm(FILE *fp, ptm_header_t *ptm_header, ptm_block_t *blocks)¶

Write the blocks to a PTM file.

Does automatic JPEG encoding if the PTM format requires it.

Parameters

fp: File pointer.
ptm_header: A pointer to an initialized ptm_header_t struct.
blocks: A pointer to an initialized ptm_block_t struct.

void ptm_write_jpeg(FILE *fp, ptm_header_t *ptm_header, ptm_block_t *blocks, float u, float v)¶

Write a JPEG file from a PTM and lighting position.

Parameters

fp: A file pointer open for writing.
ptm_header:
blocks:
u: The u coordinate of the light.
v: The v coordinate of the light.

float *ptm_svd(decoder_t **decoders, int n_decoders)¶

Does the singular value decomposition.

Return

An n_coeffs by n_lights matrix of floats.

Parameters

decoders: An array of decoders.
n_decoders: The number of decoders.

void ptm_fit_poly_jsample(const ptm_image_info_t *info, const JSAMPLE *buffer, size_t pixel_stride, const float *M, ptm_unscaled_coefficients_t *output)¶

Do the polynomial fit for all pixels in the image.

With pixel_stride set to 3 you can process one color component out of an RGB buffer like the buffer returned by libjpeg. The output PTM coefficients buffer can contain one color component only (R, G, B, or Y).

Parameters

info:
buffer: The input buffer (filled by libjpeg).
pixel_stride: The spacing of the pixels in buffer.
M: The SVD matrix.
output: The output PTM coefficients.

void ptm_fit_poly_uint(const ptm_image_info_t *info, const unsigned int *buffer, size_t pixel_stride, const float *M, ptm_unscaled_coefficients_t *output)¶

void ptm_cbcr_avg(const ptm_image_info_t *info, const ycbcr_coefficients_t *buffer, ycbcr_coefficients_t *block)¶

Find the average YCbCr values of a pixel in all images.

Use this to find the best chroma for each pixel when generating an LRGB image. Here we assume that the chroma of a pixel does not change too much between exposures. This is true for diffuse objects. If this is not the case you’d better use RGB formats.

Parameters

info: An info struct containing the buffer size.
buffer: Source buffer of YCbCr values.
block: The destination buffer for the average YCbCr values.

void ptm_scale_coefficients(ptm_header_t *ptm_header, const ptm_unscaled_coefficients_t *unscaled, ptm_block_t *scaled)¶

Scale the float coefficients into unsigned chars.

Scales the coefficients and also sets the parameters in the PTM header.

See: [Malzbender2001]_ §3.3 Scale and Bias

Parameters

ptm_header: The PTM header.
unscaled: The unscaled (float) coefficients.
scaled: The scaled (unsigned char) coefficients.

void ptm_normal(const ptm_unscaled_coefficients_t *coeffs, float *nu, float *nv, float *nw)¶

Find the surface normal from the PTM coefficients.

See: [Malzbender2001] equations 16 and 17.

Parameters

[in] coeffs: The PTM coefficients at the point of interest.
[out] nu: normal
[out] nv: normal
[out] nw: normal

void ptm_print_matrix(const char *name, float *M, int m, int n)¶

Prints a matrix for debugging.

Parameters

name:
M:
m:
n:

Variables

const ptm_format_t ptm_formats[6]¶: An array containing the PTM file formats we support.

struct ptm_coefficients_t¶

#include <ptmlib.h>

Scaled PTM coefficients as expected by libjpeg for de/compression.

Public Members

JSAMPLE cu2¶

JSAMPLE cv2¶

JSAMPLE cuv¶

JSAMPLE cu¶

JSAMPLE cv¶

JSAMPLE c1¶

struct ptm_unscaled_coefficients_t¶

#include <ptmlib.h>

Unscaled PTM coefficients as expected by BLAS.

Public Members

float cu2¶

float cv2¶

float cuv¶

float cu¶

float cv¶

float c1¶

struct rgb_coefficients_t¶

#include <ptmlib.h>

RGB coefficients as found in PTMs.

Public Members

JSAMPLE r¶

JSAMPLE g¶

JSAMPLE b¶

struct ycbcr_coefficients_t¶

#include <ptmlib.h>

YCbCr coefficients as expected by jpeglib.

Public Members

JSAMPLE y¶

JSAMPLE cb¶

JSAMPLE cr¶

struct crcb_coefficients_t¶

#include <ptmlib.h>

CrCb coefficients as found in PTMs. Note the inversion from above!

Public Members

JSAMPLE cr¶

JSAMPLE cb¶

struct ptm_format_t¶

#include <ptmlib.h>

A struct that describes a supported format.

Public Members

ptm_formats_enum_t id¶: The internally used format id

int blocks¶: The no. of blocks to allocate. This is the no. of PTM coefficient blocks plus zero or one block for color components.

int ptm_blocks¶: The no. of PTM coefficient blocks, either 1 = LRGB or 3 = RGB

int color_components¶: The no. of color channels that are not encoded with PTM. Either 0 = RGB, 2 = LUM, or 3 = LRGB

int jpeg_streams¶: The no. of JPEG streams if the file is compressed else 0

const char *name¶: The format name. eg. “PTM_FORMAT_RGB”

struct ptm_image_info_t¶

#include <ptmlib.h>

Holds information about the input images and other.

Public Members

size_t width¶: The width of the input images.

size_t height¶: The height of the input images.

size_t pixels¶: The no. of pixels in each of the input images.

size_t row_stride¶: The row stride in the image buffer, eg. how much to jump to get from one row to the next.

size_t decoder_stride¶: The decoder stride in the image buffer, eg. how much to jump to get from one image to the next.

size_t n_decoders¶: The no. of decoders == no. of images.

struct ptm_header_t¶

#include <ptmlib.h>

This struct contains all information that goes into the PTM header.

For a full description of the PTM file format see: http://www.hpl.hp.com/research/ptm/downloads/PtmFormat12.pdf

Public Members

const ptm_format_t *format¶: The file format.

size_t dimen[2]¶: The PTM image dimensions (w, h).

float scale[PTM_COEFFICIENTS]¶

int bias[PTM_COEFFICIENTS]¶

int compression_param[1]¶: The JPEG compression quality.

int transforms[MAX_JPEG_STREAMS]¶

int motion_vector_x[MAX_JPEG_STREAMS]¶

int motion_vector_y[MAX_JPEG_STREAMS]¶

int order[MAX_JPEG_STREAMS]¶

int reference_planes[MAX_JPEG_STREAMS]¶

size_t compressed_size[MAX_JPEG_STREAMS]¶

size_t side_info_sizes[MAX_JPEG_STREAMS]¶

struct decoder_t¶

#include <ptmlib.h>

Information pertaining to one input image file.

Public Members

FILE *fp¶: The handle of the open file.

char *filename¶: The filename of the input image.

float u¶

float v¶

float w¶: The cartesian coordinates of the light that illuminated this image.

struct jpeg_decompress_struct dinfo¶: Used by libjpeg.