segment: Segmentations of density maps

Routines for calculating properties of index map segmentations.

Index map segmentations are 3D numpy arrays of uint32 values where the value indicates which region the grid point belongs to. Region index values start at 1, the value 0 indicates the grid point does not belong to any region. Corresponding image data 3d arrays can have any scalar type supported by numpy (int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, float64).

crosssection_midpoints(points, axis, bin_start, bin_size, bin_count)

Experimental API . This routine is intended to compute the midpoints along the axis of a filament defined as a set of region points. The midpoints are compute over bcount intervals where a point p belongs to interval i = ((p,axis) - b0) / bsize (rounded down). Points outside the bcount intervals are not included. Returned values are a bcount x 3 numpy float array giving the sum of point positions (x,y,z) in each interval, and a length bcount numpy int array giving the number of points in each interval. These can be used to compute the mean point position in each interval. The points array is required to be contiguous. Implemented in C++.

Parameters:

  • points (n x 3 array of float) –

  • axis (3 floats) –

  • bin_start (float) –

  • bin_size (float) –

  • bin_count (int) –

Returns:

  • point_sums (bcount x 3 array of float)

  • point_counts (array of int, size bcount)

find_local_maxima(data, start_positions)

Experimental API . Find the local maxima in a 3d data array starting from specified grid points by travelling a steepest ascent path. The starting points array (numpy nx3 int) is modified to have the grid point position of the maxima for each starting point. The starting_positions array is required to be contiguous. Implemented in C++.

Parameters:

  • data (3d array, any scalar type) –

  • start_positions (n x 3 array of int") –

Return type:

None

interface_values(region_map, data)

Experimental API . Report minimum and maximum data values at boundaries between regions. Returns a pair of arrays, an N x 3 array giving (r1, r2, ncontact) and a parallel N x 2 float array giving (data_min, data_max). Here r1 and r2 are the two contacting region ids, ncontact is the number of contact points and data_min, data_max are the minimum and maximum data values on the contact interface. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • data (3d array, any scalar type) –

Returns:

  • contacts (nc x 3 array of int)

  • data_min_max (nc x 2 array of float)

region_bounds(region_map)

Experimental API . Compute grid index bounds for each region. Returns an Nx7 array where N = max region index + 1. The first array index is the region number. The 7 values for a region are (imin, jmin, kmin, imax, jmax, kmax, npoints) where region points exist at the min and max values, and npoints is the total number of points in the region. Implemented in C++.

Parameters:

region_map (3d array, uint32) –

Returns:

bounds

Return type:

n x 7 array of int

region_contacts(region_map)

Experimental API . Compute region contacts returning an Nx3 array where N is the total number of contacting region pairs and the 3 values are (r1, r2, ncontact) with r1 = region1 index, r2 = region2 index, ncontact = number of contact between region1 and region2. Implemented in C++.

Parameters:

region_map (3d array, uint32) –

Returns:

contacts

Return type:

n x 3 array of int

region_index_lists(region_map)

Experimental API . Compute the integer grid indices for each region. Implemented in C++.

Parameters:

region_map (3d array, uint32) –

Returns:

grid_points

Return type:

tuple of n x 3 array of int

region_maxima(region_map, data)

Experimental API . Report the grid index for each region where the maximum data values is attained and the data value at the maximum. Two arrays are returned indexed by the region number (size equals maximum region index plus 1). The first array is n x 3 numpy int containing (i,j,k) grid index of maximum, and the second array is length n 1-D numpy float array containing the maximum data value. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • data (3d array, any scalar type) –

Returns:

  • max_points (n x 3 array of int)

  • max_values (length n array of float)

region_point_count(region_map, region_index)

Experimental API . Count the number of grid points belonging to a specified region. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • region_index (int) –

Returns:

count

Return type:

uint32

region_points(region_map, region_index)

Experimental API . Return an N x 3 array of grid indices for a specified region. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • region_index (int) –

Returns:

points

Return type:

n x 3 array of int

segmentation_surface(region_map, index[, groups])

Experimental API . Calculate surface vertices and triangles surrounding 3d region map voxels having a specified region or group index. The optional group array maps region map values to group index values. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • index (int) – Region or group index of voxels to compute surface for.

  • groups (1d array of int) – This array maps the region index to a group index allowing multiple regions to form one surface.

Returns:

  • vertices (n x 3 array of float)

  • triangles (m x 3 array of int)

segmentation_surfaces(region_map[, groups])

Experimental API . Calculate surface vertices and triangles for several regions of region_map. The region map must have integer values. A surfce is made for each region integer value. If the groups array is given it maps region index values to group index values and a surface is made for each group index. Implemented in C++.

Parameters:

  • region_map (3d array, uint32) –

  • groups (1d array of int) – This array maps the region index to a surface id allowing multiple regions to form one surface.

Returns:

surfaces

Return type:

list of 3-tuples (int index, vertices n x 3 array of float, triangles m x 3 array of int)

watershed_regions(data, threshold, region_map)

Experimental API . Compute watershed regions putting numeric indices for each region in region map array and returning the number of regions. Implemented in C++.

Parameters:

  • data (3D array, any scalar type) –

  • threshold (float) –

  • region_map (3d array, uint32) – This array will be filled in with region index values for each watershed region.

Returns:

region_count

Return type:

uint32