Convert an .nrrd image volume to Neuroglancer "precomputed" format

Reads a 3D image volume from an .nrrd file (or accepts one already loaded into R) and writes it as a Neuroglancer precomputed image layer — an info JSON plus chunked, optionally-gzipped raw bricks under <resolution>/<x_min-x_max>_<y_min-y_max>_<z_min-z_max>. The output can be opened directly by spelunker or any other Neuroglancer viewer when served over HTTP/S3/GCS, and is the format the BANC connectome and most CAVE-served layers use.

This is a thin R wrapper around cloud-volume: each nrrd_to_precomputed() call boots a single Python process via reticulate, builds an info dict, and writes the volume as a single bounding-box write. For very large volumes you'll usually want to chain cloudvolume.transfer.TransferTask or generate downsampled mip levels with cloudvolume.tasks.create_downsampling_tasks; both are available from the same Python session via reticulate::import("cloudvolume").

Users with an existing Python pipeline may prefer the npimage.save one-liner, which wraps the same cloud-volume call: npimage.save(arr, 'foo.ng', pixel_size = res_nm) for single-channel .nrrd-style inputs. Multi-channel light-sheet .lsm stacks need a per-channel loop or RGB packing in either approach.

nrrd_to_precomputed(
  input,
  output,
  resolution = NULL,
  data_type = c("uint8", "uint16", "uint32", "float32"),
  encoding = c("raw", "compresso", "jpeg", "compressed_segmentation"),
  chunk_size = c(64L, 64L, 32L),
  voxel_offset = c(0L, 0L, 0L),
  layer_type = c("image", "segmentation"),
  compress = TRUE,
  overwrite = FALSE,
  python = NULL
)

Arguments

input

either a path to an .nrrd file or a 3D numeric/integer array already loaded into R. If a path, voxel size is read from the NRRD header (space directions); for an in-memory array, supply resolution explicitly.

output

where to write the precomputed layer. A local directory path is accepted (file:// prefix is added if missing); pass a gs://, s3:// or https:// URL to write directly to a bucket (requires the relevant cloud-volume credentials).

resolution

numeric vector of length 3, voxel size in nanometres. If NULL (default) and input is a path, voxel size is taken from the NRRD header (assumed to be in microns and multiplied by 1000). If the array has been down-sampled before calling, multiply the source resolution by the down-sampling factor.

data_type

one of "uint8" (default), "uint16", "uint32", "float32". Choose to match the dynamic range of your data: 16-bit microscopy data with most signal in the bottom 12 bits typically fits cleanly into "uint8" after a right-shift of 4 bits.

encoding

one of "raw" (default; gzip'd at the chunk boundary), "compresso", "jpeg" (lossy; image layers only), or "compressed_segmentation" (segmentation layers only).

chunk_size

length-3 integer vector of voxel chunk dimensions. Default c(64, 64, 32).

voxel_offset

length-3 integer vector applied as the global voxel origin in the Neuroglancer view. Default c(0, 0, 0).

layer_type

one of "image" (default) or "segmentation".

compress

logical; gzip compression for raw chunks (default TRUE). Ignored for encoding != "raw".

overwrite

logical; if FALSE (default) and output is a local directory that already exists, abort.

python

optional path or virtualenv identifier passed to reticulate::use_python() before importing cloudvolume.

Value

Invisibly, the resolved output URL (with file:// prefix added if needed).

See also

bancr::banc_lm_scene for assembling a BANC-overlay Neuroglancer state pointing at a precomputed layer; nrrd_to_mip.

Examples

if (FALSE) { # \dontrun{
# Convert a Kondo-2020 receptor expression NRRD (IS2-space, 16-bit) into a
# Neuroglancer precomputed layer down-sampled 4x in xy and 2x in z, mapped
# to 8-bit:
library(nat); library(reticulate); py_require("cloud-volume")

v <- read.nrrd("IS2_CapaR_no1_01_warp_m0g40c4e1e-1x16r3.nrrd")
hdr <- attr(v, "header")
src_res_um <- diag(hdr[["space directions"]])

v8 <- v[seq(1, dim(v)[1], by = 4),
        seq(1, dim(v)[2], by = 4),
        seq(1, dim(v)[3], by = 2)]
v8 <- as.integer(pmin(pmax(v8, 0), 4095) / 16)  # 12-bit -> 8-bit
dim(v8) <- c(192, 192, 87)

nrrd_to_precomputed(
  v8,
  output     = "file:///tmp/capar_pc",
  resolution = round(src_res_um * c(4, 4, 2) * 1000),
  data_type  = "uint8"
)
# Then upload:
#   gsutil cp -r /tmp/capar_pc gs://your-bucket/lm_layers/CapaR_IS2/
} # }