Filters & Fitting

Frequency-domain filters and downsampling for 3D volumes, geometric slab fitting from picks or segmentations, and a helper for multi-GPU parallel processing.

Filters

Filter3D

A 3D cosine band-pass / low-pass / high-pass filter.

copick_torch.filters.bandpass.Filter3D

init

__init__(apix, sz, lp=0, lpd=0, hp=0, hpd=0, device=None)

Initialize the Filter3D class.

Parameters:

apix (float) –

Pixel size in angstrom.
sz (tuple) –

Size of the tomogram (D, H, W).
lp (float, default: 0 ) –

Low-pass cutoff resolution in angstroms.
lpd (float, default: 0 ) –

Low-pass decay width in pixels.
hp (float, default: 0 ) –

High-pass cutoff resolution in angstroms.
hpd (float, default: 0 ) –

High-pass decay width in pixels.
device (device, default: None ) –

Device for the filter tensor.

angst_to_pix

angst_to_pix(ang)

Convert angstroms to pixels based on the pixel size.

Parameters:

ang (float) –

Measurement in angstroms.

Returns:

float –

Measurement in pixels.

cosine_filter

cosine_filter()

Creates a combined low-pass and high-pass cosine filter for 3D tomograms.

construct_filter

construct_filter(r, freq, freqdecay, mode='lp')

Constructs a low-pass or high-pass filter based on the mode. Handles pure LP or HP cases properly.

extract_1d_profile

extract_1d_profile(axis='x')

Extracts a 1D profile from the 3D filter along the specified axis.

Returns:

freqs ( ndarray ) –

Frequency values in cycles per angstrom (1/Å).
profile ( ndarray ) –

Filter magnitude values along the specified axis.

apply

apply(data)

Applies the filter to a tomogram.

Parameters:

data (Tensor) –

Input data tensor of shape (D, H, W).

Returns:

–

torch.Tensor: Filtered data tensor.

show_filter

show_filter()

Displays the 3D filter as a 3D plot.

FourierRescale3D

Downsamples 3D volumes via Fourier cropping.

copick_torch.filters.downsample.FourierRescale3D

init

__init__(input_voxel_size, output_voxel_size)

Initialize the FourierRescale operation with voxel sizes.

Parameters:

input_voxel_size (int or tuple) –

Physical spacing of the input voxels (d, h, w) or a single int (which will be applied to all dimensions).
output_voxel_size (int or tuple) –

Desired physical spacing of the output voxels (d, h, w) or a single int (which will be applied to all dimensions). Must be greater than or equal to input_voxel_size.

run

run(volume)

Rescale a 3D volume (or a batch of volumes on GPU) using Fourier cropping.

submit

submit(volume: Tensor) -> torch.Tensor

Submit the volume for rescaling based on its dimensionality.

batched_rescale

batched_rescale(volume: Tensor)

Process a (batched) volume: move to device, perform FFT, crop in Fourier space, and compute the inverse FFT.

calculate_cropping

calculate_cropping(volume: Tensor)

Calculate cropping indices and new dimensions based on the voxel sizes.

Fitting

Fit 3D slabs (parallel planes / spline surfaces) to membrane-like structures.

slab_from_picks

copick_torch.fitting.slab_from_picks.slab_from_picks

slab_from_picks(picks1: CopickPicks, picks2: CopickPicks, run: CopickRun, object_name: str, session_id: str, user_id: str, tomo_type: str = 'wbp', voxel_spacing: float = 10.0, method: str = 'spline', grid_resolution: Tuple[int, int] = (5, 5), fit_resolution: Tuple[int, int] = (50, 50), num_iterations: int = 500, learning_rate: float = 0.1, regularization: float = 0.0, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create a closed slab mesh from two pick sets by fitting surfaces.

Parameters:

picks1 (CopickPicks) –

First set of picks (e.g. top-layer).
picks2 (CopickPicks) –

Second set of picks (e.g. bottom-layer).
run (CopickRun) –

CopickRun object.
object_name (str) –

Name for the output mesh object.
session_id (str) –

Session ID for the output mesh.
user_id (str) –

User ID for the output mesh.
tomo_type (str, default: 'wbp' ) –

Type of tomogram (for determining volume dimensions).
voxel_spacing (float, default: 10.0 ) –

Voxel spacing of the tomogram.
method (str, default: 'spline' ) –

Fitting method - "spline" for two independent B-spline surfaces, "coupled" for one shared curved surface with two offsets (curved but exactly parallel slab), "parallel" for two flat parallel planes (shared normal, two offsets).
grid_resolution (Tuple[int, int], default: (5, 5) ) –

B-spline grid resolution (rows, cols). Used with the "spline" and "coupled" methods (the knot grid).
fit_resolution (Tuple[int, int], default: (50, 50) ) –

Output mesh grid resolution (rows, cols).
num_iterations (int, default: 500 ) –

Number of optimizer iterations per surface.
learning_rate (float, default: 0.1 ) –

Learning rate for Adam optimizer.
regularization (float, default: 0.0 ) –

Bending-energy (curvature) penalty weight for the "spline" and "coupled" methods; higher = flatter. 0.0 (default) leaves the spline fit unregularized. Ignored for "parallel".

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh, stats dict) or None if creation failed.

slab_from_segmentation

copick_torch.fitting.slab_from_segmentation.slab_from_segmentation

slab_from_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, label: int = 1, method: str = 'coupled', grid_resolution: Tuple[int, int] = (5, 5), fit_resolution: Tuple[int, int] = (50, 50), num_iterations: int = 500, learning_rate: float = 0.1, regularization: float = 0.0, surface_stride: int = 1, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create a closed slab mesh by fitting a surface to a segmentation.

Extracts a single label, keeps its largest connected component, then fits a slab using one of several methods and connects the two surfaces into a closed, watertight box mesh.

Parameters:

segmentation (CopickSegmentation) –

CopickSegmentation object.
run (CopickRun) –

CopickRun object.
object_name (str) –

Name for the output mesh object.
session_id (str) –

Session ID for the output mesh.
user_id (str) –

User ID for the output mesh.
label (int, default: 1 ) –

Label index to extract from the segmentation.
method (str, default: 'coupled' ) –

Fitting method. "spline" fits two independent B-spline surfaces to the extracted top/bottom surface points; "coupled" fits one shared curved surface with two offsets (curved but exactly parallel slab); "parallel" fits two flat parallel planes to the surface points; "iou" fits two flat parallel planes directly to the binary volume by maximizing intersection-over-union (legacy).
grid_resolution (Tuple[int, int], default: (5, 5) ) –

B-spline knot grid resolution (rows, cols) for spline/coupled.
fit_resolution (Tuple[int, int], default: (50, 50) ) –

Output mesh grid resolution (rows, cols).
num_iterations (int, default: 500 ) –

Number of optimizer iterations.
learning_rate (float, default: 0.1 ) –

Learning rate for Adam optimizer.
regularization (float, default: 0.0 ) –

Bending-energy (curvature) penalty weight for spline/coupled; higher = flatter. Ignored for parallel/iou.
surface_stride (int, default: 1 ) –

Column subsampling stride for surface-point extraction (>=1); bounds the point count on large volumes. Ignored for iou.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh, stats dict) or None if creation failed.

Parallelization

GPUPool

A thread-safe pool for parallel processing across multiple GPUs.

copick_torch.parallelization.GPUPool

Flexible GPU processing pool for parallel model inference.

execute

execute(func: Callable, tasks: List[Any], task_ids: Optional[List] = None, progress_desc: str = 'Processing') -> List[Dict]

Execute function on all tasks across GPUs.

Your function will receive

All your original arguments
gpu_id: int (keyword argument)
models: Any (keyword argument, if init_fn was provided)

shutdown

shutdown()

Shutdown workers and cleanup resources