R/colormip.R
nrrd_to_mip.RdEncode the most-anterior occupied z-slice at each (x, y)
pixel as a colour drawn from a 256-entry depth lookup table (blue =
anterior, red = posterior; PsychedelicRainBow2-like ramp), and write the
resulting RGB MIP to a .png or .tif. Three back-ends are
offered, all targeting the same Janelia ColorMIP / Color Depth MIP
specification (Otsuna et al. 2018,
bioRxiv):
method = "direct" (default)Pure R; vectorised
which.max along z, LUT lookup, transpose. No external
dependencies beyond nat, png and (for TIFF) tiff.
Pixel-perfect against the BANC Python port.
method = "python"Calls the Python implementation by
Jasper Phelps distributed in
the
BANC connectome package (fanc.render_neurons.make_colormip) via
reticulate. The R helper loads each NRRD, hands the volume to
numpy, and runs the inner colour-MIP algorithm with the BANC
depth_lut. Use this to validate the R port byte-for-byte.
method = "fiji"Launches FIJI/ImageJ and runs Janelia's
Color_Depth_MIP_batch_0308_2021.ijm macro (the canonical
reference implementation). Requires a working FIJI install with the
ColorMIP plugins (search tool,
MIP generator).
The macro asks for input and output folders interactively; the
input/savefolder arguments are not used in this path.
nrrd_to_mip(
input = NULL,
savefolder = NULL,
method = c("direct", "python", "fiji"),
target_space = c("brain", "VNC"),
threshold = "auto",
denoise = "auto",
format = c("png", "tiff"),
save = TRUE,
overwrite = FALSE,
fiji.path = NULL,
macro = NULL,
MinMem = "2500m",
MaxMem = "2500m",
python = NULL
)either a path to a single .nrrd file, a path to a
folder of .nrrd files (each will be processed), or an im3d/3D
numeric array. Ignored when method = "fiji".
folder in which to write the MIP image(s). Defaults to a
color_mips/ folder next to the input. Required when input is
an in-memory array and save = TRUE. Ignored when method = "fiji".
which back-end to use. One of "direct" (default,
pure R), "python" (BANC Python via reticulate), or
"fiji" (Janelia FIJI macro).
which template space the input volume is in.
"brain" (default) corresponds to **JRC2018U_HR** (a.k.a.
JRC2018_UNISEX_20x_HR, dims c(1210, 566, 174), voxdims
c(0.5189, 0.5189, 1.0)) — the NeuronBridge brain space.
"VNC" corresponds to **JRC2018VNCU_HR** (a.k.a.
JRC2018_VNC_UNISEX_461, dims c(573, 1119, 219), voxdims
c(0.461, 0.461, 0.7)) — the NeuronBridge VNC space. Both are
the high-resolution variants Janelia's pre-computed ColorMIPs are
served at. For "VNC" a 90-pixel black header is prepended so
output is dimensionally identical to Janelia VNC colormips.
one of "auto" (default), "triangle",
"otsu", "none", or a numeric value. Controls how
foreground voxels are separated from background:
"auto" keeps the legacy > 0 mask if the input
looks binary (≤ 2 distinct values, e.g. a synthetic neuron
skeleton from root_id_to_nrrd); otherwise applies
Triangle thresholding to suppress background staining in
real-world LM data.
"triangle" (Zack et al. 1977): draws a line
from the histogram peak to the highest-value bin and picks the
bin of maximum perpendicular distance. Robust on histograms with
a dominant background peak and a long signal tail (typical
confocal data).
"otsu" (1979): maximises between-class variance,
ignoring zero voxels by default. Works on bimodal foregrounds.
"none" keeps every voxel > 0 (the original
behaviour; correct for binary inputs).
A numeric in [0, 1] is interpreted as a quantile
threshold against the non-zero voxels (0.99 = top 1%).
A numeric > 1 is a raw intensity cutoff.
one of "auto" (default), "median3d" or
"none". Controls a pre-MIP denoising step that runs before
threshold: "median3d" applies a 3 × 3 × 3 median
filter to suppress salt-and-pepper noise (requires the
mmand package). "auto" enables "median3d" for
grayscale input and skips it for binary input. The 3-D filter is
equivalent to FIJI's Mask Median Subtraction idiom that the
Janelia ColorMIP macro uses for the same purpose.
output image format. One of "png" (default) or "tiff".
logical; if TRUE (default) write the MIP to disk and
return the file path(s) invisibly. If FALSE, return the MIP as a
height x width x 3 numeric array with values in [0, 1].
logical; if FALSE (default) skip inputs whose MIP
file already exists.
(method = "fiji") path to FIJI executable. If
NULL, looks up getOption("jimpipeline.fiji"), then $PATH,
then /Applications/Fiji.app/....
(method = "fiji") path to the FIJI macro. Defaults to
Color_Depth_MIP_batch_0308_2021.ijm (shipped with this package and
expected to be installed under FIJI's plugins/Macros).
(method = "fiji") JVM memory limits.
(method = "python") optional path to a Python
executable or virtualenv. If NULL, reticulate's default
Python is used. If the BANC depth_lut cannot be imported from
fanc.render_neurons, the function falls back to an internal
verbatim copy of the same LUT.
Invisibly, the path(s) to the written MIP file(s); or, when
save = FALSE, the MIP as a height x width x 3 array (or list
of such, when processing a folder). For method = "fiji", returns
the result of the macro call.
if (FALSE) { # \dontrun{
# Render a flywire neuron into a JRC2018U_HR-sized .nrrd, then color-MIP it
# in pure R (no FIJI, no Python):
root_id_to_nrrd("720575940632295751",
reference = "JRC2018U_HR",
savefolder = "~/asta_sez_mips")
nrrd_to_mip("~/asta_sez_mips", target_space = "brain")
# Validate against Jasper Phelps's Python port:
nrrd_to_mip("~/asta_sez_mips", method = "python")
# Or hand off to the FIJI macro (interactive folder picker):
nrrd_to_mip(method = "fiji",
fiji.path = "/Applications/Fiji.app/Contents/MacOS/ImageJ-macosx")
} # }