:mod:`neuron_morphology.snap_polygons.geometries` ================================================= .. py:module:: neuron_morphology.snap_polygons.geometries .. autoapi-nested-parse:: A collection of utilities used by snap polygons to manipulate shapely objects. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: neuron_morphology.snap_polygons.geometries.Geometries Functions ~~~~~~~~~ .. autoapisummary:: neuron_morphology.snap_polygons.geometries.select_largest_subpolygon neuron_morphology.snap_polygons.geometries.safe_linemerge neuron_morphology.snap_polygons.geometries.rasterize neuron_morphology.snap_polygons.geometries.make_translation neuron_morphology.snap_polygons.geometries.make_scale neuron_morphology.snap_polygons.geometries.clear_overlaps neuron_morphology.snap_polygons.geometries.closest_from_stack neuron_morphology.snap_polygons.geometries.get_snapped_polys neuron_morphology.snap_polygons.geometries.find_vertical_surfaces neuron_morphology.snap_polygons.geometries.shared_faces .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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. .. !! processed by numpydoc !! .. py:class:: Geometries A collection of polygons and lines .. !! processed by numpydoc !! .. attribute:: default_multipolygon_resolver By default, multiple polygons resulting from operations on these geometries are resolved by discarding all but the largest .. !! processed by numpydoc !! .. attribute:: default_multisurface_resolver By default, multiple surfaces arising from operations on these geometries are merged back together (failing if this is not possible). .. !! processed by numpydoc !! .. attribute:: close_bounds The smallest bounding box enclosing these geometries. .. !! processed by numpydoc !! .. method:: 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 .. .. !! processed by numpydoc !! .. method:: _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. .. !! processed by numpydoc !! .. method:: register_polygons(self, polygons: Union[Dict[str, PolyType], Sequence[Dict[str, PolyType]]]) utility for registering multiple polygons. See register_polygon .. !! processed by numpydoc !! .. method:: 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 .. .. !! processed by numpydoc !! .. method:: register_surfaces(self, surfaces: Dict[str, LineType]) utility for registering multiple surfaces. See register_surface .. !! processed by numpydoc !! .. method:: 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) .. .. rubric:: Notes uses rasterio.features.rasterize .. !! processed by numpydoc !! .. method:: 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. .. !! processed by numpydoc !! .. method:: 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. .. .. !! processed by numpydoc !! .. method:: 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 .. .. !! processed by numpydoc !! .. method:: 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 .. .. !! processed by numpydoc !! .. method:: to_json(self) Write contained polygons to a json-serializable format .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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 .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !! .. function:: 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. .. !! processed by numpydoc !! .. function:: 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 .. .. !! processed by numpydoc !!