Reading meshes and masks

The meshes every inference reads: a DcelData from a segmentation mask, raw mesh arrays or a mesh file.

Inputs can be: - a segmentation mask (3D uint array) ; - a multimaterial mesh: points, triangles, labels ; - a file (.rec, or opened by meshio) containing a multimaterial mesh.

Output is always a DcelData mesh. Conventions: label 0 is the exterior medium; a mask's axes are (z, y, x) and the mesh's coordinates follow them, column 0 along axis 0; the mesh is in voxel units unless a spacing gives a physical one, and the inferred pressures are in the tension unit divided by that length unit.

Matthieu Perez 2024.

MaskReconstruction dataclass

MaskReconstruction(points: NDArray[float64], triangles: NDArray[int64], labels: NDArray[int64], crop_faces: NDArray[bool_] | None, spacing: tuple[float, float, float], spacing_unit: str, min_distance: int, rec_bytes: bytes, n_cells: int, n_cut_cells: int)

A mask's mesh as foambryo mesh reconstructs it, held as plain arrays and the bytes of its .rec file.

Returned by reconstruct_mask. It holds no reconstruction algorithm, so it pickles to the size of the mesh (a front end can reconstruct in a child process and send it back), and it writes the .rec file foambryo mesh writes, byte for byte, because it holds the bytes delaunay-watershed-3d's own export wrote.

Attributes:

Name	Type	Description
points	NDArray[float64]	the mesh's points, in the unit of spacing, axis order (z, y, x).
triangles	NDArray[int64]	the triangles, as the reconstruction returned them.
labels	NDArray[int64]	the two materials of each triangle.
crop_faces	NDArray[bool_] | None	True on the crop faces, aligned with triangles, or None when the reconstruction records none.
spacing	tuple[float, float, float]	the voxel size the mask was reconstructed with, (dz, dy, dx).
spacing_unit	str	its unit.
min_distance	int	the reconstruction's min_distance, in cubic voxels of the shortest spacing.
rec_bytes	bytes	the .rec file (crop faces as its last triangle rows, metadata appendix included).
n_cells	int	the labels other than the medium that the mesh holds.
n_cut_cells	int	the cells the image boundary cuts.

mesh

mesh() -> DcelData

The mesh for inference, as dcel_mesh_from_segmentation_mask(mask, spacing=...) builds it.

Built from copies of the arrays, so the reconstruction is unchanged by any use of the mesh.

write_rec

write_rec(filename: str | Path) -> None

Write the .rec file, byte for byte what foambryo mesh writes for the same mask and options.

summary

summary() -> str

The counts foambryo mesh prints: points, triangles, cells, and those cut by the image boundary.

load_rec_appendix

load_rec_appendix(*_args: object, **_kwargs: object) -> None

Raise because the installed dw3d does not provide the .rec metadata appendix reader.

This stands in for dw3d.io.load_rec_appendix, which is only available on dw3d >= 0.4.0.

Raises:

Type	Description
ImportError	always; the installed dw3d lacks load_rec_appendix.

reconstruct_mask

reconstruct_mask(segmentation_mask: NDArray[uint], spacing: tuple[float, float, float], *, spacing_unit: str = 'um', min_distance: int = 3) -> MaskReconstruction

Reconstruct a mask's mesh in physical units, exactly as foambryo mesh does.

The call is delaunay-watershed-3d's entry point for masks with a voxel size, get_default_mesh_reconstruction_algorithm(min_distance, False).construct_mesh_in_physical_units(mask, spacing, spacing_unit=spacing_unit, axis_order="zyx"): a mask whose voxels are longer along one axis is resampled to cubic voxels of the shortest spacing, meshed, and the mesh is scaled to the unit of spacing; cubic voxels are meshed as they are. Every face of the image box is a crop. The mesh's numbers are those of dcel_mesh_from_segmentation_mask(mask, min_distance, spacing=spacing); only the unit recorded in the .rec file depends on spacing_unit.

Parameters:

Name	Type	Description	Default
segmentation_mask	NDArray[uint]	3-D labels, axis 0 = z (see foambryo.segmentation_masks.check_segmentation_mask).	required
spacing	tuple[float, float, float]	(dz, dy, dx), the voxel size along axes 0, 1, 2; one axis may be longer than the other two, which must be equal.	required
spacing_unit	str	the unit of spacing, recorded in the .rec file. Keyword-only. Defaults to "um", the command's.	'um'
min_distance	int	minimum distance between the reconstruction's points, in cubic voxels of the shortest spacing. Keyword-only. Defaults to 3, delaunay-watershed-3d's.	3

Returns:

Name	Type	Description
MaskReconstruction	MaskReconstruction	the mesh's arrays, its .rec bytes and its counts.

Raises:

Type	Description
ValueError	on a spacing the resampling cannot handle, or a mask the reconstruction refuses; or if the installed delaunay-watershed-3d has no construct_mesh_in_physical_units.

dcel_mesh_from_segmentation_mask

dcel_mesh_from_segmentation_mask(segmentation_mask: NDArray[uint], min_distance: int = 3, print_info: bool = False, *, physical_image_faces: Iterable[str] = (), spacing: tuple[float, float, float] | None = None) -> DcelData

Obtain a DcelData mesh from a segmentation mask using Delaunay-Watershed 3D.

The default mesh reconstruction algorithm is used (its dither seed is 42; see foambryo.infer_tensions_over_seeds for other seeds), with its junction relocation (on by default since dw3d 0.5.0). The mesh carries the reconstruction's crop faces: the triangles a cell has on a face of the image box that the cell reaches in the mask, where the image cut the tissue (see foambryo.crop_faces). Every inference method keeps them out of its equations and reports the pressures of the cells they cut as nan.

Parameters:

Name	Type	Description	Default
segmentation_mask	NDArray[uint]	Instance segmentation image: 3-D integer labels, axes (z, y, x), label 0 the medium, one label per cell. The mesh's coordinates follow the mask's axes, column 0 along axis 0.	required
min_distance	int	minimum distance between points of the output mesh, in voxels. Defaults to 3, dw3d's own default (it was 5 up to foambryo 0.4.2). Pass 5 to reproduce the 0.4 spacing; at 5 or more dw3d emits CoarseSpacingRelocationWarning once per reconstruction.	3
print_info	bool	print mesh construction details. Defaults to False.	False
physical_image_faces	Iterable[str]	faces of the image box where the tissue really ends, for example on a coverslip: "axis0_low" (index 0 along the mask's first axis), "axis0_high", ... "axis2_high". Cell surfaces on them are contact with the medium. Keyword-only. Defaults to none: every image face is a crop.	()
spacing	tuple[float, float, float] | None	the voxel size along the mask's axes 0, 1, 2, in any one unit; one axis (a z step) may be longer than the other two, which must be equal. Keyword-only. Defaults to None: the mesh is reconstructed on the voxel grid and returned in voxel units. Given, the call is delaunay-watershed-3d's construct_mesh_in_physical_units: the mask is resampled to cubic voxels of the shortest spacing (shape-based interpolation), meshed with the same settings (min_distance then counts cubic voxels), and the mesh is returned in the unit of spacing, with DcelData.source_spacing set. Measured on 12 simulated tissues of 90 and 165 cells at a real cell size, down-sampled along z, against the same tissues meshed at full resolution: resampling first costs +0.83, +0.71 and +1.17 degrees of contact-angle error at an anisotropy of 5/3, 2 and 3, against +1.38, +1.97 and +4.10 for meshing the native grid and scaling the mesh. Above 3 nothing was measured at that cell size, and delaunay-watershed-3d warns (UnmeasuredAnisotropyWarning); the mesh is built anyway. The cost is that of a mask acquired at the short spacing: the anisotropy times the voxels.	None

Returns:

Name	Type	Description
DcelData	DcelData	The mesh reconstructed from the segmentation and ready for force inference, in voxel units without spacing and in the spacing's unit with it.

Raises:

Type	Description
ValueError	if physical_image_faces names an unknown face, or is given to a dw3d that does not record crop faces; if spacing is not three positive finite numbers with at most one longer axis, or is given to a dw3d without construct_mesh_in_physical_units.

Warns:

Type	Description
UserWarning	the reconstruction's own warnings, from delaunay-watershed-3d (for example CoarseSpacingRelocationWarning at min_distance 5 or more, or UnmeasuredAnisotropyWarning above an anisotropy of 3).

dcel_mesh_from_multimaterial_mesh

dcel_mesh_from_multimaterial_mesh(points: NDArray[float64], triangles: NDArray[int64], labels: NDArray[int64], *, crop_faces: NDArray[bool_] | NDArray[integer] | None = None, source_spacing: tuple[float, float, float] | None = None) -> DcelData

Obtain a DcelData mesh for force inference from raw multimaterial mesh data.

Parameters:

Name	Type	Description	Default
points	NDArray[float64]	Points of the multimaterial mesh, shape (nv, 3), in any length unit (the pressures are then in the tension unit divided by it).	required
triangles	NDArray[int64]	Triangles of the multimaterial mesh, as vertex indices, shape (nf, 3).	required
labels	NDArray[int64]	the two materials on the sides of each triangle, shape (nf, 2), label 0 the exterior medium. A triangle's winding must put its right-hand-rule normal on the side of its second label (see DcelData); the label order is then normalised to label_1 < label_2.	required
crop_faces	NDArray | None	which triangles are crop faces, as a boolean mask or row indices (see DcelData). Keyword-only. Defaults to None, no crop face.	None
source_spacing	tuple | None	the voxel size of the source mask, recorded, not used (see DcelData). Keyword-only. Defaults to None, unknown.	None

Returns:

Name	Type	Description
DcelData	DcelData	The mesh ready for force inference.

Raises:

Type	Description
ValueError	as DcelData: a triangle with the same material on both sides, an invalid crop_faces or source_spacing.

dcel_mesh_from_file

dcel_mesh_from_file(filename: str | Path) -> DcelData

Obtain a DcelData mesh for force inference from a multimaterial mesh file.

It can be either a .rec (or .arec) file created from Delaunay-Watershed 3D, or a mesh that can be opened by meshio and contains a "label1" and "label2" data. The .vtk meshes saved by Delaunay-Watershed 3D are an example of such meshes. The mesh is read in the length unit of the file.

Crop faces are read from the file when it records them: in a .rec file, the metadata appendix's crop_faces = <first row> <count> (the last block of triangle rows); in a file meshio opens, a crop_face cell array. A file that records neither is read without crop faces; if its mesh has triangles that look like crop faces (between the medium and a cell, lying flat on a face of the mesh's bounding box over a large patch), an UnrecordedCropFacesWarning says so, because they are then read as contact with the medium.

The source voxel size is read from a .rec file whose appendix says the mesh is in physical units (coordinate_frame = physical, spacing = ...), as DcelData.source_spacing; it changes no number. Any other file gives None.

Parameters:

Name	Type	Description	Default
filename	str | Path	Path to the file on disk.	required

Returns:

Name	Type	Description
DcelData	DcelData	The mesh ready for force inference.

Raises:

Type	Description
ValueError	if the file's crop record is inconsistent with its triangles, or as DcelData (a triangle with the same material on both sides).

Warns:

Type	Description
UnrecordedCropFacesWarning	when the file records no crop faces but its mesh has triangles that look like them.