unravel.image_io.points_to_img module

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

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 io_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 utils_points_compressor to unpack the points before running this script.

Usage:

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

unravel.image_io.points_to_img.parse_args()

unravel.image_io.points_to_img.threshold_points_by_region_id(points_df, thresh=None, upper_thresh=None)

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.

Returns:

points_dfpandas.DataFrame

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

unravel.image_io.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.image_io.points_to_img.points_to_img(points_ndarray, ref_img=None)

Create a 3D image from a set of point coordinates, using a reference image for shape if provided. If multiple points fall within the same voxel, the voxel’s value is incremented accordingly.

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.

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)
>>> 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.image_io.points_to_img.main()