unravel.coordinates.points_to_img module

Use coords_points_to_img (p2i) from UNRAVEL to convert a set of points (coordinates) to a 3D image, accounting for the number of detections at each voxel.

Important

• Input coordinates must be in voxel/index space (integer indices).

• If your points are in physical space (e.g., µm or mm), convert them to voxel coordinates first (e.g., using coords_physical_points_to_img).

Input:

• A CSV file where each row represents a point corresponding to a detection in the 3D image.

• The columns should include ‘x’, ‘y’, ‘z’, and ‘Region_ID’ (e.g., from rstats or coords_img_to_points).

Output image types:

.nii.gz, .tif series, .h5, .zarr

Note

• Points outside the brain (i.e., ‘Region_ID’ == 0) are excluded.

• If the input CSV has a ‘count’ column, use coords_points_compressor to unpack the points before running this script.

Usage:

coords_points_to_img -i path/points.csv -ri path/ref_image [-o path/image] [-thr 20000 or -uthr 20000] [-v]

unravel.coordinates.points_to_img.parse_args()

unravel.coordinates.points_to_img.threshold_points_by_region_id(points_df, thresh=None, upper_thresh=None, region_id_col='Region_ID')

Filter the points (i.e., coordinates) based on the ‘Region_ID’ column. This function removes points that are outside the brain (i.e., ‘Region_ID’ == 0) and optionally filters points based on a threshold or upper threshold.

Parameters:

points_dfpandas.DataFrame

A DataFrame containing the points with columns ‘x’, ‘y’, ‘z’, and ‘Region_ID’.

threshfloat, optional

Exclude region IDs below this threshold.

upper_threshfloat, optional

Exclude region IDs above this threshold.

region_id_colstr, optional

The name of the column in points_df that contains the region IDs used for filtering. Default is “Region_ID”.

Returns:

points_dfpandas.DataFrame

The filtered DataFrame containing the points with columns ‘x’, ‘y’, ‘z’, and region_id_col.

unravel.coordinates.points_to_img.load_and_prepare_points(points_csv_path, thresh=None, upper_thresh=None)

Load points from a CSV file and prepare them by filtering based on Region_ID and adjusting coordinates.

Parameters:

points_csv_pathstr or Path

Path to the input CSV file containing the points.

threshfloat, optional

Threshold to exclude points with Region_ID below this value.

upper_threshfloat, optional

Threshold to exclude points with Region_ID above this value.

Returns:

points_dfpandas.DataFrame

A DataFrame containing the prepared points with columns ‘x’, ‘y’, ‘z’, and ‘Region_ID’.

unravel.coordinates.points_to_img.points_to_img(points_ndarray, ref_img=None, values=None)

Create a 3D image from point coordinates.

If values is None:

• voxel intensities represent counts per voxel.

If values is provided:

• voxel intensities are assigned from the corresponding values array.

• later points overwrite earlier points if multiple points map to the same voxel

Parameters:

points_ndarraynumpy.ndarray

A 2D array of shape (n, 3) where each row represents the (x, y, z) coordinates of a point.

ref_imgnumpy.ndarray

A reference image from which to derive the output shape.

valuesnumpy.ndarray, optional

A 1D array of values corresponding to each point, used to assign voxel intensities instead of counting occurrences. Must be the same length as points_ndarray.

Returns:

imgnumpy.ndarray

A 3D image created from the input points. Each voxel’s value represents the number of points that fall within that voxel.

Note:

• If the point coordinates are in physical or resampled space, ensure that they are appropriately scaled and aligned with the desired image grid before calling this function.

• If the count in a voxel exceeds the maximum value for uint8 (255), the image’s data type is automatically promoted to uint16 to accommodate higher counts.

Example:

>>> points_ndarray = np.array([[10, 20, 30], [10, 20, 30], [15, 25, 35]])
>>> ref_img = np.zeros((50, 50, 50), dtype='uint8')
>>> img = points_to_img(points_ndarray, ref_img, values=None)
>>> print(img[10, 20, 30])  # Output will be 2, since two points are at this coordinate.
>>> print(img[15, 25, 35])  # Output will be 1, since one point is at this coordinate.

unravel.coordinates.points_to_img.main()