util.py

The util module contains several useful shared classes and methods for the camera spectral calibration suite.

class util.QuietPrint(quiet=False)

Context manager class for suppressing print()

Replaces builtins.print with either print_quiet or print_flush inside the context. Nesting is supported:

with QuietPrint(True):
    print('This will not print')
    with QuietPrint(False):
        print('This will print with flush=True')
    print('This will not print')
print('This will print normally')

Parameters:

quiet (bool) – If True, builtins.print is monkey-patched with print_quiet within the context, otherwise it uses print_flush.

print_original(*, sep=' ', end='\n', file=None, flush=False)

Prints the values to a stream, or to sys.stdout by default.

sep

string inserted between values, default a space.

end

string appended after the last value, default a newline.

file

a file-like object (stream); defaults to the current sys.stdout.

flush

whether to forcibly flush the stream.

static print_quiet(*args, **kw)

Don’t print.

static print_flush(*args, **kw)

Print with flush=True by default.

class util.Settings(path)

Camera Spectral Calibration task settings.

This class loads image stack, file paths, and other data related to the spectral calibration workflow from a yaml file. The yaml file should be formatted as:

camera: Camera model name
lens: Lens model name
settings: Camera & lens settings (e.g. ISO & Aperture)
label: Short name for dataset
ND: 0.0 # ND filter value (or 0.0 if unused)
crop: [x, y, w, h] # raw->tiff crop settings
dcraw: -w # dcraw command-line settings
roi: [x, y, w, h] # region of interest (in cropped image) for collecting stats
non_negative: True # set True to use non-negative regression for spectral response
source_spectra: monochromator data directory
image_dir: image file directory
image_name: DSC_{:04}.NEF #image filename pattern. the {} will be replaced with the image number
images:
    300: [1, 2, 3]
    305: [4, 5, 6]
    ...
    wavelength: [image numbers]

The first line must be camera: ... for check_valid to accept the file, but the other items may appear in any order. Omitted items will be set to None.

Parameters:

path – Path to the settings yaml file.

camera: str

Camera name/description.

lens: str

Lens name/description.

settings: str

Camera & lens settings.

label: str

Short name to identify the dataset.

nd: float

Neutral density filter value.

crop_xywh: list[int]

dcraw crop settings [x,y,w,h]

dcraw_args: str

dcraw extra arguments

roi: tuple[slice, slice]

region of interest slices for image statistics

non_negative: bool

True to use non-negative regression methods

image_dir: str

Path to image files

image_name: str

Image filename pattern

images: dict[float, list[int]]

mapping wavelength to lists of image numbers

samples_file: str

path to image samples file

spectra_dir: str

illuminant spectra data directory

spectra_file: str

illuminant spectra data file

response_file: str

spectral response data file path

plots_file: str

spectral response plots file path

excel_file: str

spectral response excel file path

static check_valid(path: str) → bool

Check for a (possibly) valid settings yaml file, without loading the whole thing.

image_file(i: int, suffix: str | None = None) → str

Get path (as string) to i’th image file.

class util.H5Storage

Base class for data storage backed by H5 files.

This class provides several methods that can be used by derived classes to semi-automatically load and save data from H5 files.

E.g. in the derived class:

class Foo(H5Storage):
    _h5members = [('x'),('y')]

    def __init__(self):
        self.x = numpy.arange(100)

    def save(self):
        with self._open('file.h5','w') as f:
            self._save(f)

The members argument to _load and _save is either None or an iterable where each item is (name, h5_name, attrs, dims, func). If the members argument is None, it defaults to self._h5members.

h5_name, attrs, dims, and func are optional, but must be specified in order. If not specified, they will default to None. if h5_name is None it will default to name. If both name and h5_name are None, h5_name will be set to '/', representing the file’s root (e.g. to set file attributes). If func is None it will default to numpy.array.

Data will be loaded as self.name = func(file[h5_name]) and stored as file.create_dataset(h5_name,data=self.name). If the dataset already exists, then it will be overwritten (requiring that the shape matches!), if the same data was previously written to a different dataset, then a hardlink will be created rather than copy the data.

attrs is either None or an iterable of (attr_name, h5_attr_name) Attributes are loaded as self.attr_name = file[h5_name].attrs[h5_attr_name] and stored as file[h5_name].attrs[h5_attr_name] = self.attr_name.

To access file or group attributes, set name to None and h5_name to either the group name or '/' to access file attributes.

dims is either None or an iterable of h5_scale_name or (dim_label, h5_scale_name). If only h5_scale_name is given, it will also be used as the label. After all datasets have been written to the file, all datasets referred to by h5_scale_name will have make_scale() called on them and then attached as dimension scales to the associated datasets. If the h5_scale_name dataset does not exist a H5Storage.Warning will be issued.

exception Warning

Warning class derived from UserWarning, emitted by _load and _save.

_open(path: str, mode: Literal['r', 'r+', 'w', 'w-', 'x', 'a']) → h5py.File

Open and return an h5py File.

_load(file: h5py.File, members: list[tuple[str, ...]] | None = None, warn_missing: bool = False)

Load the specified members from file.

Parameters:

• file – an open h5py.File.

• members – list of class members to load.

• warn_missing – if True, issue a warning for missing items rather than raise an exception.

_save(file: h5py.File, members: list[tuple[str, ...]] | None = None)

Save the specified members to file.

Parameters:

• file – an open h5py.File file.

• members – list of class members to store.