Pure-R port of Janelia's ColorMIP_Mask_Search

Source: R/colormip.R

Score a query colour-depth MIP against a library of candidate colour-depth MIPs and rank them by pixel overlap, mirroring the algorithm in Janelia's ColorMIP_Mask_Search FIJI plugin. Both query and library MIPs must already be on the same template grid (e.g. JRC2018VNCU_HR 1209 x 573 with the 90-px header that nrrd_to_mip(target_space = "VNC") writes). For a worked example see vignette("banc_colormip_search").

colormip_search(
  query,
  library,
  threshold = 100L,
  z_tolerance = 2L,
  xy_shift = 2L,
  mirror = FALSE,
  top_n = NULL,
  mc.cores = 1L,
  verbose = TRUE
)

Arguments

query

path to a colour-MIP image, or an H x W x 3 numeric array in [0, 1] (the format nrrd_to_mip returns when save = FALSE).

library

either (i) a directory containing candidate colour-MIP PNG/TIFF files, or (ii) a character vector of file paths. All candidates must share the query's pixel grid.

threshold

integer brightness cutoff applied to the channel sum (R + G + B) when classifying a pixel as foreground. Default 100 (Janelia's plugin default).

z_tolerance

integer; allowed difference between query and library depth-LUT indices (0..255) for a pixel to count as a match. Default 2.

xy_shift

integer; the search translates the query by -xy_shift..+xy_shift pixels in each of x and y. Default 2.

mirror

logical; if TRUE also try the left-right mirrored query and keep the better score (with the corresponding shift). Default FALSE.

top_n

integer or NULL; if non-NULL return only the top top_n hits by score.

mc.cores

integer; number of cores for parallel scoring via parallel::mclapply. 1 (default) runs sequentially.

verbose

logical; emit progress ticks (one dot per 100 candidates).

Value

A data.frame sorted by descending score, with columns path, score (matched pixels divided by query foreground count), n_match, dx, dy and mirror.

Details

Each pixel's RGB triple is mapped back to its closest entry in the shared 256-entry depth LUT (the same table used by nrrd_to_mip; near-anterior = blue, near-posterior = red). A pixel is a "match" at shift (dx, dy) when (a) both query and library pixels exceed threshold in summed brightness and (b) their depth-LUT indices differ by at most z_tolerance. For each candidate the score is the best match count over the (2 * xy_shift + 1)^2 translation grid (and its mirror image when mirror = TRUE), normalised by the query foreground count.

Validated against Janelia's plugin (top-50 Spearman > 0.95 on the SREN efferent benchmark in the banc_colormip_search vignette); switch to method = "fiji" on nrrd_to_mip or run the FIJI plugin directly if you need byte-perfect parity with the canonical reference.

See also

nrrd_to_mip