Core library (`pylorenzmie.lib`)#

LMObject#

Base class and shared type aliases for pylorenzmie objects.

class pylorenzmie.lib.LMObject.LMObject[source]#

Bases: ABC

Base class for pylorenzmie objects.

Provides the properties protocol (used for both serialization and optimization), JSON and pandas I/O, equality comparison, and a class-scoped logger.

properties#

Dictionary of adjustable object properties. Concrete subclasses must override the getter; the base-class setter applies any key that matches an existing attribute and logs a debug message for unknown keys.

Type:: dict

Notes

LMObject instances are mutable and therefore unhashable (__hash__ is explicitly None).

The type aliases below are re-exported at class scope for backward compatibility. Prefer importing them directly from pylorenzmie.lib.

Property = bool | int | float | str#

Properties#: alias of dict[str, bool | int | float | str]

Image = NDArray[float] | NDArray[int]#

Images = NDArray[float] | NDArray[int] | list[NDArray[float] | NDArray[int]]#

Coordinates#: alias of NDArray[float]

Coefficients#: alias of NDArray[complex]

Field#: alias of NDArray[complex]

Result = pandas.Series | pandas.DataFrame#

Results = pandas.Series | pandas.DataFrame | list[pandas.Series | pandas.DataFrame]#

static meshgrid(corner=(0.0, 0.0), flatten=True, dtype=<class 'float'>)#

Pixel coordinate grid for holographic microscopy images.

Parameters:

shape (tuple[int, int]) – (ny, nx) dimensions of the grid.
corner (tuple[float, float]) – (left, top) origin of the coordinate system in pixels. Default: (0., 0.).
flatten (bool) – If True (default), return shape (2, ny*nx). If False, return shape (2, ny, nx).
dtype (type) – Numeric type for the coordinate arrays. Default: float.

Return type:

GenericAlias[float]

Returns:

xy (numpy.ndarray) – Coordinate grid.

property logger: Logger#: Logger named after the concrete class.

abstract property properties: dict[str, bool | int | float | str]#

Adjustable parameters of this object.

Returns a flat dict mapping parameter names to their current values. Only parameters included here are visible to the serialization methods and to Optimizer during fitting.

Subclasses must override the getter using:

@ParentClass.properties.getter
def properties(self) -> Properties:
    props = super().properties
    props.update(...)
    return props

The base-class getter returns an empty dict; the base-class setter iterates over the supplied dict and calls setattr for every key that already exists as an attribute. Unknown keys are silently ignored and logged at DEBUG level.

to_json(**kwargs)[source]#

Serialize properties to a JSON string.

NumPy scalars are automatically converted to native Python types before serialization.

Parameters:: **kwargs – Passed through to json.dumps.
Return type:: str
Returns:: str – JSON-encoded properties.

from_json(s)[source]#

Update properties from a JSON string.

Mutates the object in place by assigning to self.properties.

Parameters:: s (str) – JSON-encoded properties, as produced by to_json.
Return type:: None

to_pandas(**kwargs)[source]#

Serialize properties to a pandas Series.

Parameters:: **kwargs – Passed through to pandas.Series.
Return type:: Series
Returns:: pandas.Series – Index is the property names; values are the property values.

from_pandas(series)[source]#

Update properties from a pandas Series.

Mutates the object in place by assigning to self.properties.

Parameters:: series (pandas.Series) – As produced by to_pandas.
Return type:: None

classmethod example()[source]#

Return type:: None

Azimuthal#

Azimuthal statistics for 2-D images.

pylorenzmie.lib.Azimuthal.azimuthaloperator(func)[source]#

Decorator that adds image-to-radii conversion to a radial function.

A function decorated with @azimuthaloperator gains the public signature f(data, center=None), where data is a 2-D image and center is an (x, y) coordinate pair defaulting to the image centre. Internally the decorator builds or retrieves a cached _Context (integer radii, sort order, bin boundaries) and passes the ravelled data and context to the original function.

The context is keyed by (ny, nx, x_p, y_p) and cached across calls via functools.lru_cache(), so repeated calls on images of the same shape and center pay no recomputation cost.

pylorenzmie.lib.Azimuthal.avg(d, ctx)[source]#

Azimuthal average of a 2-D image.

Parameters:

data (numpy.ndarray) – Two-dimensional data set.
center (tuple of float, optional) – (x, y) center for the azimuthal average. Default: center of data.

Return type:

GenericAlias[float]

Returns:

avg (numpy.ndarray) – Average value of data as a function of distance from center.

pylorenzmie.lib.Azimuthal.std(d, ctx)[source]#

Azimuthal standard deviation of a 2-D image.

Parameters:

data (numpy.ndarray) – Two-dimensional data set.
center (tuple of float, optional) – (x, y) center for the azimuthal average. Default: center of data.

Return type:

tuple[GenericAlias[float], GenericAlias[float]]

Returns:

avg (numpy.ndarray) – Azimuthal average as a function of distance from center.
std (numpy.ndarray) – Azimuthal standard deviation as a function of distance from center.

pylorenzmie.lib.Azimuthal.med(d, ctx)[source]#

Azimuthal median of a 2-D image.

Parameters:

data (numpy.ndarray) – Two-dimensional data set.
center (tuple of float, optional) – (x, y) center for the azimuthal median. Default: center of data.

Return type:

GenericAlias[float]

Returns:

med (numpy.ndarray) – Median value as a function of distance from center. Radii with no contributing pixels are set to NaN.

pylorenzmie.lib.Azimuthal.mad(d, ctx)[source]#

Azimuthal median absolute deviation of a 2-D image.

Parameters:

data (numpy.ndarray) – Two-dimensional data set.
center (tuple of float, optional) – (x, y) center for the azimuthal median. Default: center of data.

Return type:

tuple[GenericAlias[float], GenericAlias[float]]

Returns:

med (numpy.ndarray) – Azimuthal median as a function of distance from center. Radii with no contributing pixels are set to NaN.
mad (numpy.ndarray) – Azimuthal median absolute deviation as a function of distance from center.

CircleTransform#

Orientation alignment transform for detecting ring-like features.

class pylorenzmie.lib.CircleTransform.CircleTransform[source]#

Bases: object

Transform an image to emphasize ring-like holographic features.

Implements the orientation alignment transform described in Krishnatreya & Grier, Opt. Express 22, 12773 (2014).

The kernel is cached so repeated calls on images of the same shape pay no recomputation cost.

kernel(shape)[source]#

Fourier-space orientation alignment kernel.

Parameters:: shape (tuple of int) – (ny, nx) shape of the image to be transformed.
Return type:: GenericAlias[complex]
Returns:: kernel (ndarray, complex) – K(k) = e^{-2i\theta} / k, shifted for FFT pixel ordering.

transform(image)[source]#

Apply the orientation alignment transform.

Parameters:: image (ndarray) – Grayscale image data.
Return type:: GenericAlias[float]
Returns:: transformed (ndarray) – Array with the same shape as image, with ring-like features enhanced. Values are normalized to [0, 1].

pylorenzmie.lib.CircleTransform.circletransform(image)[source]#

Transform an image to emphasize ring-like features.

Convenience wrapper around CircleTransform that reuses a module-level instance so the Fourier kernel is cached across calls.

Parameters:: image (ndarray) – Grayscale image data.
Return type:: GenericAlias[float]
Returns:: transformed (ndarray) – Transformed image with ring-like features enhanced.

Core library (pylorenzmie.lib)#

LMObject#

Azimuthal#

CircleTransform#

Core library (`pylorenzmie.lib`)#