PTW File Functions

Overview

This module provides functionality to read the contents of files in the PTW file format and convert the raw data to source radiance or source temperature (provided that the instrument calibration data is available).

Functions are provided to read the binary Agema/Cedip/FLIR Inc PTW format into data structures for further processing.

The following functions are available to read PTW files:

readPTWHeader(ptwfilename)

showHeader(header)

getPTWFrame(header, frameindex)

readPTWHeader(ptwfilename):

Returns a PTWFrameInfo object with all header information from the ptw file.

showHeader(header):

Returns nothing. Prints the PTW header content to the screen.

getPTWFrame(header, frameindex):

Return the raw DL levels of the frame defined by frameindex.

The authors wish to thank FLIR Advanced Thermal Solutions for the permission to publicly release our Python version of the ptw file reader. Please note that the copyright to the proprietary ptw file format remains the property of FLIR Inc.

This package was partly developed to provide additional material in support of students and readers of the book Electro-Optical System Analysis and Design: A Radiometry Perspective, Cornelius J. Willers, ISBN 9780819495693, SPIE Monograph Volume PM236, SPIE Press, 2013. http://spie.org/x648.html?product_id=2021423&origin_id=x646

Module classes

class PTWFrameInfo

Bases: object

Container for PTW file header and frame information.

Attributes are populated by readPTWHeader() (file-level fields) and GetPTWFrameFromFile() (per-frame fields). Attribute names follow the original DL002U-D Altair Reference Guide conventions.

class JadeCalibrationData(filename, datafileroot)

Bases: object

Container and loader for Jade camera calibration data.

Reads an XML calibration file and associated spectral data files, then builds a pyradi.rylookup.RadLookup table for DL ↔ temperature / radiance conversion.

Parameters:

• filename (str) – Full path to the XML calibration file.

• datafileroot (str) – Root directory for spectral data files referenced inside the XML.

Info()

Return a summary string of the calibration data.

Returns:

Human-readable summary of all loaded calibration parameters.

Return type:

str

Module functions

readPTWHeader(ptwfilename)

Read the PTW file header and return a populated PTWFrameInfo object.

Parameters:

ptwfilename (str) – Full path to the ptw file.

Returns:

Object containing all PTW header information.

Return type:

PTWFrameInfo

Raises:

No exception is raised. –

Reference:

Header field names and byte positions are from DL002U-D Altair Reference Guide.

showHeader(Header)

Print all PTW header fields to stdout.

Parameters:

Header (PTWFrameInfo) – PTW file header object.

Returns:

None

getPTWFrame(header, frameindex)

Retrieve a single PTW frame given the header and frame index.

The frame data array is also stored inside header as header.data. The header is returned explicitly to make it clear that its contents have been updated (frame time, detector temperature).

Parameters:

• header (PTWFrameInfo) – PTW file header object.

• frameindex (int) – 1-based index of the frame to extract.

Returns:

(data, header) where data is np.ndarray of shape (rows, cols) containing raw DL values, and header is the updated PTWFrameInfo object. On error a bare np.ndarray([0]) is returned instead of the tuple.

Return type:

tuple

Raises:

No exception is raised. –

GetPTWFrameFromFile(header)

Load the frame specified by header.h_framepointer from the PTW file.

Parameters:

header (PTWFrameInfo) – Header object with h_framepointer set to the desired 1-based frame index.

Returns:

The same header object, updated with:

data (np.ndarray of shape (cols, rows)), h_frameMinute, h_frameHour, h_frameSecond, h_detectorTemp, h_sensorTemp4, h_minval, h_maxval.

Return type:

PTWFrameInfo

Raises:

No exception is raised. –

getPTWFrames(header, loadFrames=[])

Retrieve multiple PTW frames specified by a list of frame indices.

Parameters:

• header (PTWFrameInfo) – PTW file header object.

• loadFrames (list[int]) – 1-based frame indices to extract.

Returns:

(data, fheaders) where data is np.ndarray of shape (len(loadFrames), rows, cols) and fheaders is a list of PTWFrameInfo objects (one per frame, carrying frame time and FPA temperature). On error returns (np.asarray([0]), None).

Return type:

tuple

Raises:

No exception is raised. –

myint(x)

Decode a 2-byte little-endian signed integer from a bytes slice.

Parameters:

x – bytes of length 2.

Returns:

signed 16-bit integer value.

Return type:

int

mylong(x)

Decode a 4-byte little-endian unsigned integer from a bytes slice.

Parameters:

x – bytes of length 4.

Returns:

unsigned integer value.

Return type:

int

Note

Pre-existing bug: the shift for byte 3 is x[3] << 32 instead of the correct x[3] << 24. When byte 3 is non-zero the result is larger than expected by a factor of 256. In practice all PTW integer fields fit within 24 bits so byte 3 is always 0 and the result is correct.

myfloat(x)

Decode a 4-byte IEEE 754 single-precision float from a bytes slice.

Parameters:

x – bytes of length 4.

Returns:

single-precision floating-point value.

Return type:

float

mydouble(x)

Decode an 8-byte IEEE 754 double-precision float from a bytes slice.

Parameters:

x – bytes of length 8.

Returns:

double-precision floating-point value.

Return type:

float

mybyte(x)

Decode a single unsigned byte from a bytes slice of length 1.

Parameters:

x – bytes of length 1.

Returns:

unsigned byte value (0–255).

Return type:

int

Note

Will raise TypeError if x is longer than one byte.

mypass(x)

Identity function — return x unchanged.

Parameters:

x – any value.

Returns:

The input x unchanged.

myRGB(x)

Decode three bytes as an HTML-style hex colour string.

Parameters:

x – bytes of length 3, ordered R, G, B.

Returns:

colour string of the form '#rrggbb'.

Return type:

str

terminateStrOnZero(str)

Iterate through str and terminate on the first null byte.

Parameters:

str – bytes object to scan.

Returns:

prefix of str up to (but not including) the first null byte.

Return type:

bytes

Note

Pre-existing Python-3 bug: str[idx] on a bytes object returns an int, so the comparison str[idx] != '\00' (int vs str) is always True and the loop never exits early. The function therefore always returns the full input slice unchanged. Callers in readPTWHeader compensate by using .rstrip('\x00') on the decoded string, which achieves the intended trimming for null-padded fields.