@article{munoz2025cpmeasure,
  title={cp\_measure: API-first feature extraction for image-based profiling workflows},
  author={Mu{\~n}oz, Al{\'a}n F and Treis, Tim and Kalinin, Alexandr A and Dasgupta, Shatavisha and Theis, Fabian and Carpenter, Anne E and Singh, Shantanu},
  journal={arXiv preprint arXiv:2507.01163},
  year={2025}
}

The simplest way to extract all features from an image and its masks:

import numpy as np
from cp_measure.featurizer import featurize
image: (C, H, W) float array, masks: (N_masks, H, W) integer labels
image = np.random.default_rng(42).random((2, 240, 240))
masks = np.zeros((1, 240, 240), dtype=np.int32)
masks[0, 50:100, 50:100] = 1
masks[0, 150:200, 150:200] = 2
data, columns, rows = featurize(image, masks) 
data:    np.ndarray of shape (nobjects, nfeatures)
 
columns: feature names (e.g. "Area", "IntensityMeanIntensity_ch0", ...)
 
rows:    [(None, "object", 1), (None, "object", 2)]  — (imageid, objectname, label) per row

To customise which features are extracted, or to name your channels and masks, use makefeaturizerconfig. Channel names are matched positionally to the image's first axis and control how per-channel features are labeled in the output columns (e.g. "IntensityMeanIntensity_DNA"). If omitted, channels are auto-named ch0, ch1, ...

import numpy as np
from cpmeasure.featurizer import featurize, makefeaturizer_config
Recreate variables from previous examples for this block to run in isolation
image = np.random.default_rng(42).random((2, 240, 240))
masks = np.zeros((1, 240, 240), dtype=np.int32)
masks[0, 50:100, 50:100] = 1
masks[0, 150:200, 150:200] = 2
Disable texture features, name channels explicitly
config = makefeaturizerconfig(["DNA", "ER"], texture=False)
data, columns, rows = featurize(image, masks, config)

Multiple mask types (e.g. nuclei and cells) are supported by stacking them along the first axis:

import numpy as np
from cpmeasure.featurizer import featurize, makefeaturizer_config
Recreate variables from previous examples for this block to run in isolation
image = np.random.default_rng(42).random((2, 240, 240))
config = makefeaturizerconfig(["DNA", "ER"], objects=["nuclei", "cells"])
masks = np.zeros((2, 240, 240), dtype=np.int32) masks[0, 50:100, 50:100] = 1    # nucleus 1 masks[1, 40:110, 40:110] = 1    # cell 1 masks[1, 150:200, 150:200] = 2  # cell 2 masks[1, 175:180, 180:210] = 2  # Minor asymmetries on bottom right edge of cells
data, columns, rows = featurize(image, masks, config) 
rows: [(None, "nuclei", 1), (None, "cells", 1), (None, "cells", 2)]

Volumetric (C, Z, H, W) data is supported. The featurizer automatically skips 2D-only features (radialdistribution, radialzernikes, zernike, feret). All other features (intensity, sizeshape, texture, granularity, correlations) work for both 2D and 3D.

The output is plain numpy + lists, so converting to a DataFrame is straightforward:

notest
import pandas as pd
row_names = [f"{img}{obj}{label}" for img, obj, label in rows]
df = pd.DataFrame(data, index=row_names, columns=columns)

Note: DataFrame libraries must be installed independently, to keep the dependency tree low.

For more control over individual measurements, or to call specific functions directly, use the bulk API. It operates on single images and masks following the scikit-image convention.

cp_measure currently provides two types of measurements based on their inputs:

• Type 1: 1 image + 1 set of masks (e.g., intensity)
• Type 2: 2 images + 1 set of masks (e.g., colocalization)

import numpy as np
from cpmeasure.bulk import getcore_measurements
measurements = getcoremeasurements() 
print(measurements.keys())
 
dictkeys(['radialdistribution', 'radial_zernikes', 'intensity', 'sizeshape', 'zernike', 'feret', 'texture', 'granularity'])

Create synthetic data
size = 240
rng = np.random.default_rng(42)
pixels = rng.integers(low=1, high=255, size=(size, size))
Create two similar-sized objects
masks = np.zeros_like(pixels)
masks[50:100, 50:100] = 1
masks[150:200, 150:200] = 2
measurements = getcoremeasurements() results = {} for name, func in measurements.items():     results = {results, func(masks, pixels)}
""" {'RadialDistributionFracAtD1of4': array([0.03673493, 0.05640786]),  'RadialDistributionMeanFrac1of4': array([1.02857809, 1.15072037]),  'RadialDistributionRadialCV1of4': array([0.05539421, 0.04635982]),  ...  'Granularity_16': array([97.65759629, 97.64371833]) } """

Individual measurement functions can be imported directly. Each returns a dictionary of arrays.

import numpy as np
from cpmeasure.core.measureobjectsizeshape import getsizeshape
mask = np.zeros((50, 50), dtype=np.int32) mask[5:-6, 5:-6] = 1 get_sizeshape(mask, None)

measureobjectintensitydistribution.getradialzernikes
measureobjectintensity.get_intensity
measureobjectsizeshape.get_zernike
measureobjectsizeshape.get_feret
measuregranularity.get_granularity
measuretexture.get_texture
measurecolocalization.getcorrelationpearson
measurecolocalization.getcorrelationmanders_fold
measurecolocalization.getcorrelationrwc
measurecolocalization.getcorrelationcostes
measurecolocalization.getcorrelationoverlap

You can follow progress here.

Most features are implemented, but Type 3 measurements (e.g., ObjectNeighbors) does not have a wrapper. We do not plan to implement ObjectSkeleton.