neuron_morphology.snap_polygons.geometries

A collection of utilities used by snap polygons to manipulate shapely objects.

Module Contents

Classes

Geometries A collection of polygons and lines

Functions

select_largest_subpolygon(polygons: Union[Polygon, Iterable[Polygon]], error_threshold: float) → Polygon Given a collection of polygons, find the largest by area.
safe_linemerge(linestrings: Union[LineString, Sequence[LineString]]) → LineString Wrapper around shapely.ops.linemerge that no-ops in case a single
rasterize(geometry: shapely.geometry.base.BaseGeometry, box: BoundingBox) → np.array Rasterize a shapely object to a grid defined by a provided bounding box.
make_translation(horizontal: float, vertical: float) → TransformType Utility for building a 2D translation transform
make_scale(scale: float = 1.0) → TransformType A utility for making a 2D scale transform, suitable for transforming
clear_overlaps(stack: Dict[str, np.ndarray]) Given a stack of masks, remove all inter-mask overlaps inplace
closest_from_stack(stack: Dict[str, np.ndarray]) Given a stack of images describing distance from several objects, find
get_snapped_polys(closest: np.ndarray, name_lut: Dict[int, str], multipolygon_resolver: MultiPolygonResolverType) → Dict[str, Polygon] Obtains named shapes from a label image.
find_vertical_surfaces(polygons: Dict[str, Polygon], order: Sequence[str], pia: Optional[LineString] = None, white_matter: Optional[LineString] = None) Given a set of polygons describing cortical layer boundaries, find the
shared_faces(poly: Polygon, others: Iterable[Polygon], snap_tolerance=10) → LineString Given a polygon and a set of other polygons that could be adjacent on
neuron_morphology.snap_polygons.geometries.select_largest_subpolygon(polygons: Union[Polygon, Iterable[Polygon]], error_threshold: float) → Polygon

Given a collection of polygons, find the largest by area.

Parameters:
polygons : To be filtered
error_threshold : If the ratio of the largest polygon to the second

largest does not meet or exceed this value, reject the largest polygon.

Returns:
the largest polygon
neuron_morphology.snap_polygons.geometries.safe_linemerge(linestrings: Union[LineString, Sequence[LineString]]) → LineString

Wrapper around shapely.ops.linemerge that no-ops in case a single LineString or length-1 collection is argued.

class neuron_morphology.snap_polygons.geometries.Geometries

A collection of polygons and lines

default_multipolygon_resolver

By default, multiple polygons resulting from operations on these geometries are resolved by discarding all but the largest

default_multisurface_resolver

By default, multiple surfaces arising from operations on these geometries are merged back together (failing if this is not possible).

close_bounds

The smallest bounding box enclosing these geometries.

register_polygon(self, name: str, path: PolyType)

Adds a named polygon path to this object. Updates the close bounding box.

Parameters:
name : identifier for this polygon
path : defines the exterior of this (simple) polygon
_register_many(self, objects: Union[Dict[str, Union[LineType, PolyType]], Sequence[Dict[str, Union[LineType, PolyType]]]], method: Callable[[str, Union[LineType, PolyType]], None])

Utility for registering many polygons or surfaces. See register_polygons and register_surfaces for use.

register_polygons(self, polygons: Union[Dict[str, PolyType], Sequence[Dict[str, PolyType]]])

utility for registering multiple polygons. See register_polygon

register_surface(self, name: str, path: LineType)

Adds a line (e.g. the pia/wm surfaces) to this object. Updates the bounding box.

Parameters:
name : identifier for this surface
path : defines the surface
register_surfaces(self, surfaces: Dict[str, LineType])

utility for registering multiple surfaces. See register_surface

rasterize(self, box: Optional[BoundingBox] = None, polygons: Union[Sequence[str], bool] = True, surfaces: Union[Sequence[str], bool] = False)

Rasterize one or more owned geometries. Produce a mapping from object names to masks.

Parameters:
shape : if provided, the output image shape. Otherwise, use the

rounded close bounding box shape

polygons : a list of names. Alternatively all (True) or none (False)
lines : a list of names. Alternatively all (True) or none (False)

Notes

uses rasterio.features.rasterize

transform(self, transform: TransformType)

Apply a transform to each owned geometry. Return a new collection.

Parameters:
transform : A callable which maps (vertical, horizontal) coordinates to

new (vertical, horizontal) coordinates.

fill_gaps(self, working_scale: float = 1.0, multipolygon_resolver: Optional[MultiPolygonResolverType] = None)

Expand this geometries’ polygons to fill its bounding box, using distance to assign empty space.

Parameters:
working_scale : The filling is carried out in a raster space, with 1

pixel corresponding to 1 unit in the coordinate system of your polygons. You can optionally rescale the polygons before rasterizing.

multipolygon_resolver : This method might obtain multiple output

polygons for a given input polygon. This callable collapses them into a single geometry. The default selects the largest.

Returns:
A copy of this geometries object with the entire bounding box having
been filled.
cut(self, template: shapely.geometry.Polygon, multipolygon_resolver: Optional[MultiPolygonResolverType] = None, multisurface_resolver: Optional[MultiSurfaceResolvertype] = None)

Crop this Geometries’ polygons and surfaces onto a provided template.

Parameters:
template : portions of surfaces and polygons outside this shape will be

removed

multipolygon_resolver : This callable is applied to the outputs of

the intersection operation in order to resolve cases where a polygon has been cut into multiple components. The default method selects the largest by area.

multisurface_resolver : As multipolygon resolver, for surfaces. The

default method attempts to merge the surfaces.

Returns:
A copy of this Geometries object, with polygons and surfaces cropped
convex_hull(self, surfaces: bool = True, polygons: bool = True)

Find the convex hull of these geometries.

Parameters:
surfaces : if True, include surfaces in the hull
polygons : if True, include polygons in the hull
Returns:
The convex hull of the included geometries
to_json(self)

Write contained polygons to a json-serializable format

neuron_morphology.snap_polygons.geometries.rasterize(geometry: shapely.geometry.base.BaseGeometry, box: BoundingBox) → np.array

Rasterize a shapely object to a grid defined by a provided bounding box.

Parameters:
geometry : to be rasterized
box : defines the window (in the same coordinate space as the geometry)

into which the geometry will be rasterized

Returns:
A mask, where 1 indicates presence and 0 absence
neuron_morphology.snap_polygons.geometries.make_translation(horizontal: float, vertical: float) → TransformType

Utility for building a 2D translation transform

Parameters:
horizontal : translate by this much along the first axis
vertical : translate by this much along the second axis
Returns:
Function which applies the argued translation
neuron_morphology.snap_polygons.geometries.make_scale(scale: float = 1.0) → TransformType

A utility for making a 2D scale transform, suitable for transforming bounding boxes and Geometries

Parameters:
scale : isometric scale factor
Returns:
A transform function
neuron_morphology.snap_polygons.geometries.clear_overlaps(stack: Dict[str, np.ndarray])

Given a stack of masks, remove all inter-mask overlaps inplace

Parameters:
stack : Keys are names, values are masks (of the same shape). 0 indicates

absence

neuron_morphology.snap_polygons.geometries.closest_from_stack(stack: Dict[str, np.ndarray])

Given a stack of images describing distance from several objects, find the closest object to each pixel.

Parameters:
stack : Keys are names, values are ndarrays (of the same shape). Each pixel

in the values describes the distance from that pixel to the named object

Returns:
closest : An integer array whose values are the closest object to each

pixel

names : A mapping from the integer codes in the “closest” array to names
neuron_morphology.snap_polygons.geometries.get_snapped_polys(closest: np.ndarray, name_lut: Dict[int, str], multipolygon_resolver: MultiPolygonResolverType) → Dict[str, Polygon]

Obtains named shapes from a label image.

Parameters:
closest : label integer with integer codes
name_lut : look up table from integer codes to string names
Returns:
mapping from names to polygons describing each labelled region
neuron_morphology.snap_polygons.geometries.find_vertical_surfaces(polygons: Dict[str, Polygon], order: Sequence[str], pia: Optional[LineString] = None, white_matter: Optional[LineString] = None)

Given a set of polygons describing cortical layer boundaries, find the boundaries between each layer.

Parameters:
polygons : named layer polygons
order : A sequence of names defining the order of the layer polygons from

pia to white matter

pia : The upper (from the perspective of cortex) pia surface.
white_matter : The lower (from the perspective of cortex) white matter

surface.

Returns:
dictionary whose keys are as “{name}_{side}” and whose values are

linestrings describing these boundaries.

neuron_morphology.snap_polygons.geometries.shared_faces(poly: Polygon, others: Iterable[Polygon], snap_tolerance=10) → LineString

Given a polygon and a set of other polygons that could be adjacent on the same side, find and connect that shared face.

Parameters:
poly : Polygon

Polygon whose boundary with others we want to identify

others : list

List of other Polygons

Returns:
LineString representing the shared face