Mask

class surfalize.mask.Mask(surface, array=None)

Bases: object

Represents a boolean mask associated with a Surface by composition. A masked point is excluded from analysis (leveling fits, height statistics, the Abbott-Firestone curve, …) while its height value is preserved in the underlying data. This makes masking a reversible operation, in contrast to non-measured points which are stored as NaN and irreversibly discard the height value.

The mask is lazily allocated: as long as no region is masked, no array is stored and the mask reports as empty. The convention follows numpy.ma.MaskedArray, i.e. True marks a point that is masked (ignored).

Two coordinate systems are supported:

• The region methods (add_rectangle, add_circle, …) operate in physical units (µm) by default, following the same convention as Surface.crop, where the y-axis is measured from the bottom of the surface.

• Numpy-style indexing (surface.mask[10:20, 5:15] = True) operates in raw array indices (row, column) measured from the top-left, identical to indexing the underlying height array.

Consistent with the rest of the surfalize API, the region methods return a Surface and do not modify the original by default (inplace=False), returning a copy with the updated mask instead. With inplace=True the surface is modified in place and returned, which allows chaining, e.g. surface.mask.add_rectangle((0, 10, 0, 10), inplace=True).mask.add_circle((50, 50), 5, inplace=True).

The only exception is numpy-style item assignment (surface.mask[2:5, 1:3] = True), which is always in-place since Python item assignment cannot return a value.

Parameters:

surfacesurfalize.Surface

The surface this mask is associated with.

arrayndarray[bool] | None, default None

Optional initial boolean mask. Must match the shape of the surface height data.

Attributes:

is_empty

Returns True if no point is masked.

Methods

add_circle(center, radius[, in_units, inplace])	Masks all points inside a circle.
add_rectangle([box, border, in_units, inplace])	Masks all points inside a rectangle.
any()	Returns True if at least one point is masked.
clear([inplace])	Clears the mask so that no point is masked.
invert([inplace])	Inverts the mask: masked points become unmasked and vice versa.
set(array[, inplace])	Replaces the mask with the supplied boolean array.
subtract_circle(center, radius[, in_units, ...])	Unmasks all points inside a circle.
subtract_rectangle([box, border, in_units, ...])	Unmasks all points inside a rectangle.
threshold([below, above, inplace])	Masks all points whose height value falls below and/or above the specified thresholds.
to_array()	Returns a concrete boolean mask array, even if the mask is currently empty (in which case an all-False array of the surface shape is returned).

add_circle(center, radius, in_units=True, inplace=False)

Masks all points inside a circle.

Parameters:

centertuple[float, float]

Center of the circle as a (x, y) tuple. If in_units is True, the values are in µm and y is measured from the bottom of the surface. Otherwise they are pixel indices (column, row).

radiusfloat

Radius of the circle in µm (in_units=True) or pixels (in_units=False).

in_unitsbool, default True

If True, interpret center and radius in physical units (µm). If False, in pixels.

inplacebool, default False

If False, return a copy of the surface with the updated mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

add_rectangle(box=None, border=None, in_units=True, inplace=False)

Masks all points inside a rectangle.

Exactly one of box or border must be given.

Parameters:

boxtuple[float, float, float, float], optional

Rectangle as a (x0, x1, y0, y1) tuple. If in_units is True, the values are in µm and the y-axis is measured from the bottom, matching the convention of Surface.crop. Otherwise the values are pixel indices.

borderfloat | tuple[float, float, float, float], optional

Alternative to box: the distance from each edge inwards to the rectangle, in the same units and axis order as box. A scalar keeps the same distance to all four edges, so mask.add_rectangle(border=100) masks everything except a 100 µm strip along each edge. A (x0, x1, y0, y1) tuple sets the distance to each edge individually.

in_unitsbool, default True

If True, interpret box/border in physical units (µm). If False, in pixel indices.

inplacebool, default False

If False, return a copy of the surface with the updated mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

any()

Returns True if at least one point is masked.

clear(inplace=False)

Clears the mask so that no point is masked.

Parameters:

inplacebool, default False

If False, return a copy of the surface with the cleared mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

invert(inplace=False)

Inverts the mask: masked points become unmasked and vice versa.

Parameters:

inplacebool, default False

If False, return a copy of the surface with the updated mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

property is_empty

Returns True if no point is masked.

set(array, inplace=False)

Replaces the mask with the supplied boolean array.

Parameters:

arrayndarray[bool] | None

Boolean array matching the surface shape, or None to clear the mask.

inplacebool, default False

If False, return a copy of the surface with the updated mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

subtract_circle(center, radius, in_units=True, inplace=False)

Unmasks all points inside a circle. See add_circle for the parameter description.

Returns:

surfacesurfalize.Surface

subtract_rectangle(box=None, border=None, in_units=True, inplace=False)

Unmasks all points inside a rectangle. See add_rectangle for the parameter description.

Returns:

surfacesurfalize.Surface

threshold(below=None, above=None, inplace=False)

Masks all points whose height value falls below and/or above the specified thresholds.

Parameters:

belowfloat | None, default None

If given, all points with a height value smaller than this value are masked.

abovefloat | None, default None

If given, all points with a height value larger than this value are masked.

inplacebool, default False

If False, return a copy of the surface with the updated mask. If True, modify the surface in place and return it.

Returns:

surfacesurfalize.Surface

to_array()

Returns a concrete boolean mask array, even if the mask is currently empty (in which case an all-False array of the surface shape is returned).

Returns:

ndarray[bool]