neurom.morphmath¶

Mathematical and geometrical functions used to compute morphometrics.

Functions

`angle_3points`(p0, p1, p2)	Compute the angle in radians between three 3D points.
`angle_between_projections`(p1, p2)	Angle between the projections p1 and p2 (2d vectors).
`angle_between_vectors`(p1, p2)	Computes the angle in radians between vectors 'p1' and 'p2'.
`angles_to_pi_interval`(angles[, scale])	Convert any angles into the ]-scale * pi, scale * pi] interval.
`aspect_ratio`(points)	Computes the min/max ratio of the principal direction extents.
`average_points_dist`(p0, p_list)	Computes the average distance between a list of points and a given point p0.
`azimuth_from_vector`(vec)	Return the azimuth of a vector.
`circularity`(points)	Computes circularity as 4 * pi * area / perimeter^2.
`convex_hull`(points)	Get the convex hull from an array of points.
`dist_point_line`(p, l1, l2)	Compute the orthogonal distance between a line and a point.
`elevation_from_vector`(vec)	Return the elevation of a vector.
`interpolate_radius`(r1, r2, fraction)	Interpolate the radius between two values.
`interval_lengths`(points[, prepend_zero])	Returns the list of distances between consecutive points.
`linear_interpolate`(p1, p2, fraction)	Returns the point p satisfying: p1 + fraction * (p2 - p1).
`path_distance`(points)	Compute the path distance from given set of points.
`path_fraction_id_offset`(points, fraction[, ...])	Find segment by fractional offset.
`path_fraction_point`(points, fraction)	Find coordinates by fractional offset.
`pca`(points)	Estimate the principal components of the covariance on the given point cloud.
`point_dist`(p1, p2)	Compute the euclidian distance between two 3D points.
`point_dist2`(p1, p2)	Compute the square of the euclidian distance between two 3D points.
`polygon_diameter`(points)	Compute the maximun euclidian distance between any two points in a list of points.
`principal_direction_extent`(points)	Calculate the extent of a set of 3D points.
`scalar_projection`(v1, v2)	Compute the scalar projection of v1 upon v2.
`section_length`(points)	Compute the path distance from given set of points.
`segment_area`(seg)	Compute the surface area of a segment.
`segment_length`(seg)	Return the length of a segment.
`segment_length2`(seg)	Return the square of the length of a segment.
`segment_radial_dist`(seg, pos)	Return the radial distance of a tree segment to a given point.
`segment_radius`(seg)	Return the mean radius of a segment.
`segment_taper_rate`(seg)	Compute the taper rate of a segment.
`segment_volume`(seg)	Compute the volume of a segment.
`segment_x_coordinate`(seg)	Return the mean x coordinate of a segment.
`segment_y_coordinate`(seg)	Return the mean y coordinate of a segment.
`segment_z_coordinate`(seg)	Return the mean z coordinate of a segment.
`shape_factor`(points)	Computes area over max pairwise distance squared.
`sphere_area`(r)	Compute the area of a sphere with radius r.
`spherical_from_vector`(vec)	Return the spherical coordinates of a vector: elevation and azimuth.
`taper_rate`(p0, p1)	Compute the taper rate between points p0 and p1.
`vector`(p1, p2)	Compute vector between two 3D points.
`vector_from_spherical`(elevation, azimuth[, ...])	Return a vector from the frame center to the point in given direction and given radius.
`vector_projection`(v1, v2)	Compute the vector projection of v1 upon v2.

neurom.morphmath.angle_3points(p0, p1, p2)¶

Compute the angle in radians between three 3D points.

Calculated as the angle between p1-p0 and p2-p0.

Parameters:

p0 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p1 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p2 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.

Returns:

Angle in radians between (p1-p0) and (p2-p0). 0.0 if p0==p1 or p0==p2.

neurom.morphmath.angle_between_projections(p1, p2)¶: Angle between the projections p1 and p2 (2d vectors).

neurom.morphmath.angle_between_vectors(p1, p2)¶

Computes the angle in radians between vectors ‘p1’ and ‘p2’.

Normalizes the input vectors and computes the relative angle between them.

neurom.morphmath.angles_to_pi_interval(angles, scale=1.0)¶: Convert any angles into the ]-scale * pi, scale * pi] interval.

neurom.morphmath.aspect_ratio(points)¶: Computes the min/max ratio of the principal direction extents.

neurom.morphmath.average_points_dist(p0, p_list)¶: Computes the average distance between a list of points and a given point p0.

neurom.morphmath.azimuth_from_vector(vec)¶: Return the azimuth of a vector.

neurom.morphmath.circularity(points)¶

Computes circularity as 4 * pi * area / perimeter^2.

Note: For 2D points, ConvexHull.volume corresponds to its area and ConvexHull.area: to its perimeter.

neurom.morphmath.convex_hull(points)¶

Get the convex hull from an array of points.

Returns:: scipy.spatial.ConvexHull object if successful, otherwise None

neurom.morphmath.dist_point_line(p, l1, l2)¶

Compute the orthogonal distance between a line and a point.

The line is that which passes through the points l1 and l2.

Parameters:

p – iterable indices 0, 1, 2 correspond to cartesian coordinates
l1 – iterable indices 0, 1, 2 correspond to cartesian coordinates
l2 – iterable indices 0, 1, 2 correspond to cartesian coordinates

neurom.morphmath.elevation_from_vector(vec)¶: Return the elevation of a vector.

neurom.morphmath.interpolate_radius(r1, r2, fraction)¶

Interpolate the radius between two values.

Calculate the radius that corresponds to a point P that lies at a fraction of the length of a cut cone P1P2 where P1, P2 are the centers of the circles that bound the shape with radii r1 and r2 respectively.

Parameters:

r1 – float Radius of the first node of the segment.
r2 – float Radius of the second node of the segment
fraction – float The fraction at which the interpolated radius is calculated.

Returns: float: The interpolated radius.

Note: The fraction is assumed from point P1, not from point P2.

neurom.morphmath.interval_lengths(points, prepend_zero=False)¶

Returns the list of distances between consecutive points.

Parameters:

points – a list of np.array of 3D points
prepend_zero (bool) – if True, the returned array will start with a zero

neurom.morphmath.linear_interpolate(p1, p2, fraction)¶: Returns the point p satisfying: p1 + fraction * (p2 - p1).

neurom.morphmath.path_distance(points)¶: Compute the path distance from given set of points.

neurom.morphmath.path_fraction_id_offset(points, fraction, relative_offset=False)¶

Find segment by fractional offset.

Find the segment which corresponds to the fraction of the path length along the piecewise linear curve which is constructed from the set of points.

Parameters:

points – an iterable of indexable objects with indices 0, 1, 2 correspoding to 3D cartesian coordinates
fraction – path length fraction (0.0 <= fraction <= 1.0)
relative_offset – return absolute or relative segment distance

Returns:

(segment ID, segment offset) pair.

neurom.morphmath.path_fraction_point(points, fraction)¶

Find coordinates by fractional offset.

Computes the point which corresponds to the fraction of the path length along the piecewise linear curve which is constructed from the set of points.

Parameters:

points – an iterable of indexable objects with indices 0, 1, 2 correspoding to 3D cartesian coordinates
fraction – path length fraction (0 <= fraction <= 1)

Returns:

The 3D coordinates of the aforementioned point

neurom.morphmath.pca(points)¶

Estimate the principal components of the covariance on the given point cloud.

Parameters:: points – A numpy array of points of the form ((x1,y1,z1), (x2, y2, z2)…)
Returns:: Eigenvalues and respective eigenvectors

neurom.morphmath.point_dist(p1, p2)¶

Compute the euclidian distance between two 3D points.

Parameters:

p1 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p2 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.

Returns:

The euclidian distance between the points.

neurom.morphmath.point_dist2(p1, p2)¶

Compute the square of the euclidian distance between two 3D points.

Parameters:

p1 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p2 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.

Returns:

The square of the euclidian distance between the points.

neurom.morphmath.polygon_diameter(points)¶: Compute the maximun euclidian distance between any two points in a list of points.

neurom.morphmath.principal_direction_extent(points)¶

Calculate the extent of a set of 3D points.

The extent is defined as the maximum distance between the projections on the principal directions of the covariance matrix of the points.

Parameters:: points – a 2D numpy array of points with 2 or 3 columns for (x, y, z)
Returns:: the extents for each of the eigenvectors of the cov matrix

Note

Direction extents are ordered from largest to smallest.

neurom.morphmath.scalar_projection(v1, v2)¶

Compute the scalar projection of v1 upon v2.

Parameters:

v1 – iterable indices 0, 1, 2 corresponding to cartesian coordinates
v2 – iterable indices 0, 1, 2 corresponding to cartesian coordinates

Returns:

3-vector of the projection of point p onto the direction of v

neurom.morphmath.section_length(points)¶: Compute the path distance from given set of points.

neurom.morphmath.segment_area(seg)¶

Compute the surface area of a segment.

Approximated as a conical frustum. Does not include the surface area of the bounding circles.

neurom.morphmath.segment_length(seg)¶

Return the length of a segment.

Returns: Euclidian distance between centres of points in seg

neurom.morphmath.segment_length2(seg)¶

Return the square of the length of a segment.

Returns: Square of Euclidian distance between centres of points in seg

neurom.morphmath.segment_radial_dist(seg, pos)¶

Return the radial distance of a tree segment to a given point.

The radial distance is the euclidian distance between the mid-point of the segment and the point in question.

Parameters:

seg – tree segment
pos – origin to which distances are measured. It must have at lease 3 components. The first 3 components are (x, y, z).

neurom.morphmath.segment_radius(seg)¶

Return the mean radius of a segment.

Returns: arithmetic mean of the radii of the points in seg

neurom.morphmath.segment_taper_rate(seg)¶

Compute the taper rate of a segment.

Returns:: The taper rate, defined as the absolute value of the difference in the diameters of the segment’s two points divided by the euclidian distance between them.

neurom.morphmath.segment_volume(seg)¶

Compute the volume of a segment.

Approximated as a conical frustum.

neurom.morphmath.segment_x_coordinate(seg)¶

Return the mean x coordinate of a segment.

Returns: arithmetic mean of the x coordinates of the points in seg

neurom.morphmath.segment_y_coordinate(seg)¶

Return the mean y coordinate of a segment.

Returns: arithmetic mean of the y coordinates of the points in seg

neurom.morphmath.segment_z_coordinate(seg)¶

Return the mean z coordinate of a segment.

Returns: arithmetic mean of the z coordinates of the points in seg

neurom.morphmath.shape_factor(points)¶

Computes area over max pairwise distance squared.

Defined in doi: 10.1109/ICoAC44903.2018.8939083

Note: For 2D points, ConvexHull.volume corresponds to its area.

neurom.morphmath.sphere_area(r)¶: Compute the area of a sphere with radius r.

neurom.morphmath.spherical_from_vector(vec)¶

Return the spherical coordinates of a vector: elevation and azimuth.

Note

the elevation is the angle between the vector and its projection on the XZ plane.
the azimuth is the angle between the X axis and the projection of the vector on the XZ plane.

Warning

This frame is not the usual spherical frame (see Spherical coordinates).

neurom.morphmath.taper_rate(p0, p1)¶

Compute the taper rate between points p0 and p1.

Parameters:

p0 – iterables with first 4 components containing (x, y, z, r)
p1 – iterables with first 4 components containing (x, y, z, r)

Returns:

The taper rate, defined as the absolute value of the difference in the diameters of p0 and p1 divided by the euclidian distance between them.

neurom.morphmath.vector(p1, p2)¶

Compute vector between two 3D points.

Parameters:

p1 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p2 – indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.

Returns:

3-vector from p1 - p2

neurom.morphmath.vector_from_spherical(elevation, azimuth, radius=1.0)¶: Return a vector from the frame center to the point in given direction and given radius.

Warning

The frame is not the usual spherical frame (see Spherical coordinates).

neurom.morphmath.vector_projection(v1, v2)¶

Compute the vector projection of v1 upon v2.

Parameters:

v1 – iterable indices 0, 1, 2 corresponding to cartesian coordinates
v2 – iterable indices 0, 1, 2 corresponding to cartesian coordinates

Returns:

3-vector of the projection of point p onto the direction of v