RadVeil documentation

import radveil

report = radveil.deface_auto("t1.nii.gz", "t1_defaced.nii.gz", mode="adaptive")
print(report["voxels_changed"], "voxels changed;", report["residual_detections"], "faces left")

use radveil_core::{deface_auto, AutoParams, DefaceMode, DefaceParams, MediaPipeDetector, Volume};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut vol = Volume::load("t1.nii.gz")?;
    let params = AutoParams {
        deface: DefaceParams {
            mode: DefaceMode::Adaptive,
            ..Default::default()
        },
        ..Default::default()
    };
    let report = deface_auto(&mut vol, &mut MediaPipeDetector::default(), &params)?;
    println!(
        "{} voxels changed, faces left: {:?}",
        report.deface.voxels_changed, report.residual_detections
    );
    vol.save("t1_defaced.nii.gz")?;
    Ok(())
}

#include <stdio.h>
#include "radveil.h"

int main(void) {
    RadveilVolume *vol = radveil_volume_load("t1.nii.gz");
    if (!vol) { fprintf(stderr, "load: %s\n", radveil_last_error()); return 1; }

    RadveilAutoReport rep;
    if (radveil_deface_auto(vol, "adaptive", "face", NULL, NULL,
                            /*verify=*/1, /*brain=*/RADVEIL_BRAIN_CHECK, NULL, &rep) != 0) {
        fprintf(stderr, "refused: %s\n", radveil_last_error());  /* volume untouched */
        radveil_volume_free(vol);
        return 2;
    }
    printf("%llu voxels changed, %d faces left, %lld brain voxels touched\n",
           (unsigned long long)rep.base.voxels_changed, rep.residual_detections,
           (long long)rep.brain_voxels_modified);
    if (radveil_volume_save(vol, "t1_defaced.nii.gz", 1) != 0)
        fprintf(stderr, "save: %s\n", radveil_last_error());
    radveil_volume_free(vol);
    return 0;
}

radveil auto t1.nii.gz t1_defaced.nii.gz --mode adaptive --report report.json

import json
import radveil

report = radveil.deface_auto(
    "t1.nii.gz", "t1_defaced.nii.gz",
    mode="adaptive",
    region="face+ears",           # the pinna is biometric too
    ear_mode="cut",               # its own mode: blur leaves part of the pinna
    mask_path="t1_mask.nii.gz",   # exactly which voxels changed (uint8 NIfTI)
    qa_dir="qa",                  # before/after renders for review
)
for roi in report["rois"]:
    print(roi["label"], roi["voxels"], roi.get("detected"))
json.dump(report, open("report.json", "w"), indent=2)  # JSON-ready

radveil auto t1.nii.gz t1_defaced.nii.gz --mode adaptive --region face+ears --ear-mode cut \
  --mask-out t1_mask.nii.gz --report report.json

import nibabel as nib
import numpy as np
import radveil

img = nib.load("t1.nii.gz")  # or a DICOM series read with pydicom / SimpleITK
vol = radveil.Volume.from_array(np.asarray(img.dataobj, dtype=np.float32), img.affine)
report = radveil.deface_volume(vol, mode="adaptive")  # modifies vol in place
nib.save(nib.Nifti1Image(vol.data(), img.affine), "t1_defaced.nii.gz")
print(report["views_detected"], "views,", report["verify_rounds"], "verification rounds")

import radveil

report = radveil.anonymization_mask("t1.nii.gz", mask_path="t1_region.nii.gz")
mask = report["mask"]  # uint8 (nx, ny, nz), 1 = voxel deface_auto would rewrite
print(mask.shape, int(mask.sum()), report["voxels_changed"])

use radveil_core::{anonymization_mask, AutoParams, MediaPipeDetector, Volume};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let vol = Volume::load("t1.nii.gz")?;
    let report = anonymization_mask(
        &vol,
        &mut MediaPipeDetector::default(),
        &AutoParams::default(),
    )?;
    let mask = report
        .mask
        .expect("anonymization_mask always returns the mask");
    let n = mask.iter().filter(|&&m| m == 1).count();
    println!(
        "{n} voxels would be rewritten (report: {})",
        report.deface.voxels_changed
    );
    // Save it on the same grid, e.g. for review in a viewer.
    Volume::from_array(mask.mapv(f32::from), vol.affine).save("t1_region.nii.gz")?;
    Ok(())
}

#include <cstdio>
#include <memory>
#include <stdexcept>
#include <vector>
#include "radveil.h"

// RAII ownership for the opaque volume handle.
struct VolumeFree { void operator()(RadveilVolume *v) const { radveil_volume_free(v); } };
using Volume = std::unique_ptr<RadveilVolume, VolumeFree>;

static void check(int32_t rc) {
    if (rc != 0) throw std::runtime_error(radveil_last_error());
}

int main() {
    Volume vol{radveil_volume_load("t1.nii.gz")};
    if (!vol) throw std::runtime_error(radveil_last_error());

    uint64_t dims[3];
    radveil_volume_shape(vol.get(), dims);
    std::vector<uint8_t> mask(dims[0] * dims[1] * dims[2]);  // C order, k fastest

    RadveilDefaceParams params;
    radveil_deface_params_init(&params);  // every field "auto" ...
    params.skin_depth_mm = 4.0;           // ... then override what you need

    RadveilAutoReport rep;
    check(radveil_anonymization_mask(vol.get(), "adaptive", "face", &params, nullptr,
                                     /*brain=*/0, mask.data(), &rep));
    std::printf("%llu voxels would be rewritten; the volume is untouched\n",
                (unsigned long long)rep.base.voxels_changed);
}

# The CLI always anonymizes. The region-only escape hatch is API-only;
# --mask-out writes the region alongside the anonymized output.
radveil auto t1.nii.gz t1_defaced.nii.gz --mode adaptive --mask-out t1_region.nii.gz

import radveil

rep = radveil.deskull("t1.nii.gz", "t1_brain.nii.gz", mask_path="t1_brain_mask.nii.gz")
print(f"brain {rep['brain_volume_ml']:.0f} ml")

# brain_guard: never modify the brain or anything within 3 mm of it (opt-in,
# ~3 s per volume); brain_check: report what happened, from the same extraction.
report = radveil.deface_auto("t1.nii.gz", "t1_defaced.nii.gz", brain_guard=True, brain_check=True)
assert report["brain"]["voxels_modified"] == 0, report["brain"]
print("brain untouched, margin", report["brain"]["margin_mm"], "mm")

use radveil_core::{brain_mask, deface_auto, AutoParams, DeskullParams, MediaPipeDetector, Volume};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Brain extraction on its own (SynthStrip, pure Rust).
    let vol = Volume::load("t1.nii.gz")?;
    let (brain, rep) = brain_mask(&vol, &DeskullParams::default())?;
    println!(
        "brain {:.0} ml, {} voxels",
        rep.brain_volume_ml,
        brain.iter().filter(|&&b| b == 1).count()
    );

    // Or around anonymization: the guard never modifies the brain (opt-in,
    // ~3 s per volume); the check reports on it from the same extraction.
    let mut vol = Volume::load("t1.nii.gz")?;
    let params = AutoParams {
        brain_guard: true,
        brain_check: true,
        ..Default::default()
    };
    let report = deface_auto(&mut vol, &mut MediaPipeDetector::default(), &params)?;
    let check = report.brain.expect("brain_check was requested");
    assert_eq!(check.voxels_modified, 0, "anonymization touched the brain");
    Ok(())
}

radveil deskull t1.nii.gz -o t1_brain.nii.gz --mask-out t1_brain_mask.nii.gz

# --brain-guard: never modify the brain or anything within 3 mm of it (~3 s).
# --brain-check: exit status 3 if a brain voxel was modified (output still written).
radveil auto t1.nii.gz t1_defaced.nii.gz --brain-guard --brain-check

import numpy as np
import radveil

def my_detector(rgb: np.ndarray, try_rotations: bool):
    """Return None, a (68, 2) array in the 68-point (iBUG) order, or (array, score)."""
    return radveil.detect_landmarks(rgb, try_rotations=try_rotations)

report = radveil.deface_auto("t1.nii.gz", "t1_defaced.nii.gz", detector=my_detector)
print(report["detector"], report["views_detected"])

use radveil_core::{deface_auto, AutoParams, Detection, FaceDetector, Volume};

/// Any 2D landmark model can drive the pipeline: return 68 points in
/// the standard 68-point (iBUG) order (pixel coordinates of the rendered view), or None.
struct MyDetector;

impl FaceDetector for MyDetector {
    fn detect(
        &mut self,
        rgb: &[u8],
        w: usize,
        h: usize,
        _try_rotations: bool,
    ) -> Result<Option<Detection>, String> {
        let _ = (rgb, w, h); // run your model here
        Ok(None)
    }
}

fn main() {
    let mut vol = Volume::load("t1.nii.gz").expect("load");
    match deface_auto(&mut vol, &mut MyDetector, &AutoParams::default()) {
        Ok(r) => println!("{} voxels changed", r.deface.voxels_changed),
        Err(refusal) => eprintln!("refused, volume untouched: {refusal}"),
    }
}

#include <math.h>
#include <stdio.h>
#include "radveil.h"

/* Your own detector: 68 landmarks (standard 68-point order), world RAS+ mm.
 * Here they are read from "points.txt" (one "x y z" per line, "nan nan nan"
 * for a missing point). To lift 2D detections yourself, render with
 * radveil_render: its pos output maps every pixel to a world position. */
int main(void) {
    double pts[68 * 3];
    FILE *f = fopen("points.txt", "r");
    if (!f) { perror("points.txt"); return 1; }
    for (int i = 0; i < 68 * 3; i++)
        if (fscanf(f, "%lf", &pts[i]) != 1) pts[i] = NAN;
    fclose(f);

    RadveilVolume *vol = radveil_volume_load("t1.nii.gz");
    if (!vol) { fprintf(stderr, "%s\n", radveil_last_error()); return 1; }
    RadveilReport rep;
    if (radveil_deface(vol, pts, "adaptive", NULL, NULL, &rep) != 0) {
        fprintf(stderr, "%s\n", radveil_last_error());
        radveil_volume_free(vol);
        return 1;
    }
    printf("%llu voxels changed (no verification: check the result)\n",
           (unsigned long long)rep.voxels_changed);
    radveil_volume_save(vol, "t1_defaced.nii.gz", 1);
    radveil_volume_free(vol);
    return 0;
}

import radveil

# Threads in this process by default (the Rust core releases the GIL);
# executor="processes" isolates each volume in a worker process instead.
reports = radveil.deface_batch("cohort/*.nii.gz", output_dir="defaced", mode="adaptive", workers=2)
for r in reports:
    print(r["input"], r.get("error") or f"{r['voxels_changed']} voxels")

mkdir -p defaced
for f in cohort/*.nii.gz; do
  radveil auto "$f" "defaced/$(basename "$f" .nii.gz)_defaced.nii.gz" --mode adaptive \
    || echo "$f: refused or failed (exit $?)" >&2
done

import radveil

try:
    radveil.deface_auto("t1_defaced.nii.gz", "twice.nii.gz")
except RuntimeError as refusal:  # nothing was written
    print("refused:", str(refusal)[:60])

use radveil_core::{deface_auto, AutoParams, Detection, FaceDetector, Volume};

/// Any 2D landmark model can drive the pipeline: return 68 points in
/// the standard 68-point (iBUG) order (pixel coordinates of the rendered view), or None.
struct MyDetector;

impl FaceDetector for MyDetector {
    fn detect(
        &mut self,
        rgb: &[u8],
        w: usize,
        h: usize,
        _try_rotations: bool,
    ) -> Result<Option<Detection>, String> {
        let _ = (rgb, w, h); // run your model here
        Ok(None)
    }
}

fn main() {
    let mut vol = Volume::load("t1.nii.gz").expect("load");
    match deface_auto(&mut vol, &mut MyDetector, &AutoParams::default()) {
        Ok(r) => println!("{} voxels changed", r.deface.voxels_changed),
        Err(refusal) => eprintln!("refused, volume untouched: {refusal}"),
    }
}

#include <stdio.h>
#include "radveil.h"

int main(void) {
    RadveilVolume *vol = radveil_volume_load("t1.nii.gz");
    if (!vol) { fprintf(stderr, "load: %s\n", radveil_last_error()); return 1; }

    RadveilAutoReport rep;
    if (radveil_deface_auto(vol, "adaptive", "face", NULL, NULL,
                            /*verify=*/1, /*brain=*/RADVEIL_BRAIN_CHECK, NULL, &rep) != 0) {
        fprintf(stderr, "refused: %s\n", radveil_last_error());  /* volume untouched */
        radveil_volume_free(vol);
        return 2;
    }
    printf("%llu voxels changed, %d faces left, %lld brain voxels touched\n",
           (unsigned long long)rep.base.voxels_changed, rep.residual_detections,
           (long long)rep.brain_voxels_modified);
    if (radveil_volume_save(vol, "t1_defaced.nii.gz", 1) != 0)
        fprintf(stderr, "save: %s\n", radveil_last_error());
    radveil_volume_free(vol);
    return 0;
}

if ! radveil auto t1_defaced.nii.gz twice.nii.gz; then
  echo "refused: nothing was written"   # exit status 1
fi

import radveil

vol = radveil.Volume("t1.nii.gz")
views = [vol.render(yaw_deg=yaw) for yaw in (-20, 0, 20)]
landmarks = [radveil.detect_landmarks(v["rgb"]) for v in views]  # (68, 2) or None
points = radveil.lift_landmarks(views, landmarks)                # 68 x (x, y, z) | None
report = vol.deface(points, mode="adaptive")
vol.save("t1_defaced.nii.gz")
print(report["voxels_changed"], "voxels changed")

#include <math.h>
#include <stdio.h>
#include "radveil.h"

/* Your own detector: 68 landmarks (standard 68-point order), world RAS+ mm.
 * Here they are read from "points.txt" (one "x y z" per line, "nan nan nan"
 * for a missing point). To lift 2D detections yourself, render with
 * radveil_render: its pos output maps every pixel to a world position. */
int main(void) {
    double pts[68 * 3];
    FILE *f = fopen("points.txt", "r");
    if (!f) { perror("points.txt"); return 1; }
    for (int i = 0; i < 68 * 3; i++)
        if (fscanf(f, "%lf", &pts[i]) != 1) pts[i] = NAN;
    fclose(f);

    RadveilVolume *vol = radveil_volume_load("t1.nii.gz");
    if (!vol) { fprintf(stderr, "%s\n", radveil_last_error()); return 1; }
    RadveilReport rep;
    if (radveil_deface(vol, pts, "adaptive", NULL, NULL, &rep) != 0) {
        fprintf(stderr, "%s\n", radveil_last_error());
        radveil_volume_free(vol);
        return 1;
    }
    printf("%llu voxels changed (no verification: check the result)\n",
           (unsigned long long)rep.voxels_changed);
    radveil_volume_save(vol, "t1_defaced.nii.gz", 1);
    radveil_volume_free(vol);
    return 0;
}

radveil info t1.nii.gz                               # shape, spacing, orientation, affine
radveil render t1.nii.gz -o renders --yaw=-20,0,20   # PNG views + camera JSON
# 68 world-space (RAS+ mm) points from any source: {"points": [[x, y, z] | null, ...]}
radveil deface t1.nii.gz t1_defaced.nii.gz --landmarks3d points.json --mode adaptive