justPFM

Read and write Portable Float Map (PFM) images as NumPy arrays—from files or bytes.

Benchmark badges: 1.2.0, 2026-09-18, 2048² RGB float32 (48 MiB), scale 1, native byte order, contiguous write input; Linux / Ryzen 9 7940HS, warm cache, no fsync. Measurements and methodology. Coverage badge shows the enforced gate, not a live measurement.

At a glance

• Grayscale and RGB float32 images, with both byte orders and strided arrays.
• File I/O plus in-memory encoding and decoding; NumPy is the only runtime dependency.
• Atomic file replacement and validated input, with an optional read-size limit.
• Python 3.7–3.14, type annotations, and MIT license.

Install

python -m pip install justpfm

Quick start

import numpy as np
from justpfm import decode_pfm, encode_pfm, read_pfm, write_pfm

pixels = np.arange(15, dtype=np.float32).reshape(3, 5)

# Files: string paths and pathlib.Path are supported.
write_pfm("image.pfm", pixels)
loaded = read_pfm("image.pfm", max_pixels=4_000_000)
print(loaded.shape)  # (3, 5, 1)

# Bytes: useful with your own HTTP, archive, or cloud-storage code.
payload = encode_pfm(pixels)
restored = decode_pfm(payload, max_pixels=4_000_000)

Inputs must be float32 arrays shaped (H, W), (H, W, 1), or (H, W, 3). Reads return top-first (H, W, C) arrays; use loaded[..., 0] for 2D grayscale. For native byte order and contiguous storage, use np.ascontiguousarray(loaded, dtype=np.float32).

Use the default scale=1 to preserve values. Other positive finite scales are recorded on write and multiplied into pixels on read. max_pixels limits H * W before pixel allocation; its default is unlimited. In-memory APIs hold the full PFM payload, and decoding returns writable pixels independent of it.

Learn more

• API reference: validation, scaling, array layout, memory, and file permissions.
• Benchmarks: raw results, reproduction, and performance tradeoffs.
• Compatibility and changelog.
• Contributing: setup, commit hooks, tests, coverage, and releases.