mvos-hsi 0.1.0__tar.gz

mvos_hsi-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: mvos_hsi
+Version: 0.1.0
+Summary: Hyperspectral imagery (HSI) preprocessing utilities for Machine Learning applications
+Author: Moon Kim, Thomas Burks, Jianwei Qin
+Author-email: Rishik Aggarwal <rishik.aggarwal@sdstate.edu>, Pappu Kumar Yadav <pappu.yadav@sdstate.edu>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: spectral
+Requires-Dist: scikit-image
+Requires-Dist: opencv-python
+Requires-Dist: imgaug
+Requires-Dist: matplotlib
+
+# mvos_hsi
+
+**MVOS Hyperspectral Imaging Utilities**  
+Python package for calibration, clipping, and augmentation of hyperspectral leaf images, ported from MATLAB scripts.
+
+---
+
+## Features
+- **Calibration**
+  - Single image or batch folder calibration
+  - Dark and white reference correction
+  - Spectral binning & spatial binning options
+  - Outputs calibrated reflectance and fluorescence cubes
+  - Saves calibrated cubes as `.mat` files (`*_R.mat`, `*_F.mat`)
+
+- **Clipping**
+  - Detect leaves using vegetation indices:
+    - NDVI (Normalized Difference Vegetation Index)
+    - CI-RedEdge (Chlorophyll Index Red-Edge)
+    - GCI (Green Chlorophyll Index)
+  - Thresholding via Otsu (auto) or manual (e.g., NDVI > 0.45)
+  - Flexible cropping:
+    - Square windows (fixed size, e.g., 30×30 pixels)
+    - Tight bounding boxes fit to each leaf
+  - Saves clipped cubes as ENVI files (`.hdr` + `.img`) in `clipped_hypercubes/`
+
+- **Augmentation**
+  - Apply data augmentation to calibrated or clipped cubes
+  - Options:
+    - Per image (single `.mat` or `.hdr`)
+    - Per folder
+    - Per class (each subfolder = class label)
+  - User-defined number of augmentations
+  - Saves augmented cubes in `augmented_hypercubes/`
+
+---
+
+## Installation
+Clone this repository and install in **editable mode**:
+
+```bash
+conda activate hyperspectral
+pip install -e .

mvos_hsi-0.1.0/README.md

@@ -0,0 +1,43 @@
+# mvos_hsi
+
+**MVOS Hyperspectral Imaging Utilities**  
+Python package for calibration, clipping, and augmentation of hyperspectral leaf images, ported from MATLAB scripts.
+
+---
+
+## Features
+- **Calibration**
+  - Single image or batch folder calibration
+  - Dark and white reference correction
+  - Spectral binning & spatial binning options
+  - Outputs calibrated reflectance and fluorescence cubes
+  - Saves calibrated cubes as `.mat` files (`*_R.mat`, `*_F.mat`)
+
+- **Clipping**
+  - Detect leaves using vegetation indices:
+    - NDVI (Normalized Difference Vegetation Index)
+    - CI-RedEdge (Chlorophyll Index Red-Edge)
+    - GCI (Green Chlorophyll Index)
+  - Thresholding via Otsu (auto) or manual (e.g., NDVI > 0.45)
+  - Flexible cropping:
+    - Square windows (fixed size, e.g., 30×30 pixels)
+    - Tight bounding boxes fit to each leaf
+  - Saves clipped cubes as ENVI files (`.hdr` + `.img`) in `clipped_hypercubes/`
+
+- **Augmentation**
+  - Apply data augmentation to calibrated or clipped cubes
+  - Options:
+    - Per image (single `.mat` or `.hdr`)
+    - Per folder
+    - Per class (each subfolder = class label)
+  - User-defined number of augmentations
+  - Saves augmented cubes in `augmented_hypercubes/`
+
+---
+
+## Installation
+Clone this repository and install in **editable mode**:
+
+```bash
+conda activate hyperspectral
+pip install -e .

mvos_hsi-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mvos_hsi"
+version = "0.1.0"
+description = "Hyperspectral imagery (HSI) preprocessing utilities for Machine Learning applications"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Rishik Aggarwal", email = "rishik.aggarwal@sdstate.edu" },
+  { name = "Pappu Kumar Yadav", email = "pappu.yadav@sdstate.edu" },{name = "Moon Kim"}, {name = "Thomas Burks"}, {name = "Jianwei Qin"}]
+license = { text = "MIT" }
+dependencies = [
+  "numpy",
+  "scipy",
+  "spectral",
+  "scikit-image",
+  "opencv-python",
+  "imgaug",
+  "matplotlib"
+]
+
+[project.scripts]
+mvos-hsi = "mvos_hsi.calibration:main"
+mvos-hsi-clip = "mvos_hsi.clipping:main"
+mvos-hsi-augment = "mvos_hsi.augmentation:main"
+mvos-hsi-plot = "mvos_hsi.plotting:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mvos_hsi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mvos_hsi-0.1.0/src/mvos_hsi/__init__.py

@@ -0,0 +1,13 @@
+from .calibration import calibrate, calibrate_folder
+from .clipping import clip_sample, clip_folder
+from .augmentation import augment_image, augment_folder, augment_classes
+from .plotting import (
+    plot_pixel, plot_roi, plot_leaf_center, plot_leaf_centers_multi, load_wavelengths
+)
+
+__all__ = [
+    "calibrate", "calibrate_folder",
+    "clip_sample", "clip_folder",
+    "augment_image", "augment_folder", "augment_classes",
+    "plot_pixel", "plot_roi", "plot_leaf_center", "plot_leaf_centers_multi", "load_wavelengths",
+]

mvos_hsi-0.1.0/src/mvos_hsi/augmentation.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+import os, glob
+from typing import Optional, List
+import numpy as np
+import scipy.io as sio
+from spectral import envi, open_image
+from imgaug import augmenters as iaa
+
+# -------- helpers --------
+def _ensure_outdir(path: str):
+    os.makedirs(path, exist_ok=True)
+
+def _build_aug_seq(
+    flip: bool = False,
+    rotate: Optional[tuple] = None,
+    shear: Optional[tuple] = None,
+    scale: Optional[tuple] = None,
+) -> iaa.Sequential:
+    """
+    Build augmentation pipeline based on user choices.
+    - flip: horizontal flip with p=0.5
+    - rotate: (min_deg, max_deg)
+    - shear: (min_deg, max_deg)
+    - scale: (min_factor, max_factor)
+    """
+    augs = []
+    if flip:
+        augs.append(iaa.Fliplr(0.5))
+    if rotate is not None:
+        augs.append(iaa.Affine(rotate=rotate))
+    if shear is not None:
+        augs.append(iaa.Affine(shear=shear))
+    if scale is not None:
+        augs.append(iaa.Affine(scale=scale))
+    if not augs:
+        raise ValueError("No augmentation selected. Please specify at least one.")
+    return iaa.Sequential(augs)
+
+def _augment_cube(cube: np.ndarray, aug_seq) -> np.ndarray:
+    # imgaug expects (H,W,C)
+    return aug_seq.augment_image(cube)
+
+def _save_augmented_mat(cube: np.ndarray, out_path: str):
+    sio.savemat(out_path, {"R_Leaf": cube})
+
+def _save_augmented_envi(cube: np.ndarray, out_stem: str):
+    meta = {
+        "description": "Augmented hyperspectral cube",
+        "samples": cube.shape[1],
+        "lines": cube.shape[0],
+        "bands": cube.shape[2],
+        "data type": 4,  # float32
+        "interleave": "bil",
+    }
+    envi.save_image(out_stem + ".hdr", cube.astype(np.float32), metadata=meta)
+
+# -------- core functions --------
+def augment_image(
+    path: str,
+    num_aug: int,
+    outdir: Optional[str] = None,
+    *,
+    flip: bool = False,
+    rotate: Optional[tuple] = None,
+    shear: Optional[tuple] = None,
+    scale: Optional[tuple] = None,
+) -> List[str]:
+    """
+    Augment one hyperspectral cube (.mat or ENVI .hdr).
+    User chooses which augmentations to apply.
+    """
+    aug_seq = _build_aug_seq(flip=flip, rotate=rotate, shear=shear, scale=scale)
+
+    if not os.path.exists(path):
+        raise FileNotFoundError(path)
+
+    if outdir is None:
+        outdir = os.path.join(os.path.dirname(path), "augmented_hypercubes")
+    _ensure_outdir(outdir)
+
+    base = os.path.splitext(os.path.basename(path))[0]
+
+    # load cube
+    if path.lower().endswith(".mat"):
+        m = sio.loadmat(path)
+        if "R_plant" in m: cube = m["R_plant"]
+        elif "R_Leaf" in m: cube = m["R_Leaf"]
+        else: raise KeyError("MAT must contain R_plant or R_Leaf.")
+        save_fn = lambda arr, stem: _save_augmented_mat(arr, os.path.join(outdir, stem + ".mat"))
+    elif path.lower().endswith(".hdr"):
+        cube = open_image(path).load().astype(np.float32)
+        save_fn = lambda arr, stem: _save_augmented_envi(arr, os.path.join(outdir, stem))
+    else:
+        raise ValueError("Unsupported file type: must be .mat or .hdr")
+
+    saved = []
+    for i in range(num_aug):
+        aug = _augment_cube(cube.copy(), aug_seq)
+        stem = f"{base}_aug{i+1}"
+        save_fn(aug, stem)
+        saved.append(stem)
+    return saved
+
+def augment_folder(
+    folder: str,
+    num_aug: int,
+    outdir: Optional[str] = None,
+    **kwargs
+) -> dict:
+    """
+    Augment all .mat/.hdr cubes in a folder with chosen augmentations.
+    kwargs = flip, rotate, shear, scale
+    """
+    files = glob.glob(os.path.join(folder, "*.mat")) + glob.glob(os.path.join(folder, "*.hdr"))
+    results = {}
+    for f in files:
+        results[f] = augment_image(f, num_aug, outdir=outdir, **kwargs)
+    return results
+
+def augment_classes(
+    root: str,
+    num_aug: int,
+    outdir: Optional[str] = None,
+    **kwargs
+) -> dict:
+    """
+    Augment each class subfolder separately (root/classX/*.mat or *.hdr).
+    kwargs = flip, rotate, shear, scale
+    """
+    results = {}
+    for sub in sorted(os.listdir(root)):
+        subpath = os.path.join(root, sub)
+        if os.path.isdir(subpath):
+            results[sub] = augment_folder(
+                subpath, num_aug, outdir=(outdir or os.path.join(subpath, "augmented_hypercubes")), **kwargs
+            )
+    return results
+
+# -------- CLI --------
+def main(argv: Optional[List[str]] = None):
+    import argparse, json
+    p = argparse.ArgumentParser(prog="mvos-hsi-augment", description="Augment hyperspectral cubes")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add_aug_flags(sp):
+        sp.add_argument("--flip", action="store_true", help="Enable horizontal flip (p=0.5)")
+        sp.add_argument("--rotate", nargs=2, type=int, help="Rotation range, e.g. --rotate -10 10")
+        sp.add_argument("--shear", nargs=2, type=int, help="Shear range, e.g. --shear -16 16")
+        sp.add_argument("--scale", nargs=2, type=float, help="Scale range, e.g. --scale 0.9 1.1")
+
+    s1 = sub.add_parser("image", help="Augment one image")
+    s1.add_argument("--path", required=True)
+    s1.add_argument("--num", type=int, required=True)
+    s1.add_argument("--outdir")
+    add_aug_flags(s1)
+
+    s2 = sub.add_parser("folder", help="Augment all cubes in a folder")
+    s2.add_argument("--folder", required=True)
+    s2.add_argument("--num", type=int, required=True)
+    s2.add_argument("--outdir")
+    add_aug_flags(s2)
+
+    s3 = sub.add_parser("classes", help="Augment each class subfolder")
+    s3.add_argument("--root", required=True)
+    s3.add_argument("--num", type=int, required=True)
+    s3.add_argument("--outdir")
+    add_aug_flags(s3)
+
+    args = p.parse_args(argv)
+
+    kwargs = {
+        "flip": args.flip,
+        "rotate": tuple(args.rotate) if args.rotate else None,
+        "shear": tuple(args.shear) if args.shear else None,
+        "scale": tuple(args.scale) if args.scale else None,
+    }
+
+    if args.cmd == "image":
+        res = augment_image(args.path, args.num, outdir=args.outdir, **kwargs)
+        print(json.dumps({"saved": res}, indent=2))
+    elif args.cmd == "folder":
+        res = augment_folder(args.folder, args.num, outdir=args.outdir, **kwargs)
+        print(json.dumps(res, indent=2))
+    elif args.cmd == "classes":
+        res = augment_classes(args.root, args.num, outdir=args.outdir, **kwargs)
+        print(json.dumps(res, indent=2))

mvos_hsi-0.1.0/src/mvos_hsi/calibration.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+import os, glob, re
+from typing import Dict, Optional, List
+import numpy as np
+
+from spectral import envi, io
+from skimage.filters import threshold_multiotsu
+from skimage.morphology import remove_small_objects
+from scipy.ndimage import binary_fill_holes
+from scipy.io import savemat
+
+# ----- camera / pipeline defaults (mirrors your MATLAB) -----
+N_LINE_SAMPLE = 250
+N_LINE_DARK   = 20
+N_SAMPLE      = 810
+N_BAND        = 348
+
+DEFAULT_SPECTRAL_BIN = 3
+DEFAULT_SPATIAL_BIN  = 3
+
+# Index windows (MATLAB -> Python slices)
+INDEX_WHITE   = slice(20, 40)      # 21:40
+INDEX_IFOV    = slice(10, 260)     # 11:260 (columns)
+INDEX_PLANT_R = slice(46, 246)     # 47:246 (rows)
+INDEX_PLANT_F_SHIFT = -2
+
+# Bands used for mask/visuals after calibration
+B815 = 80    # reflectance mask band
+B685 = 56    # example F band (not required in outputs)
+
+# -------- helpers --------
+def _check_factor(k: int, name: str):
+    if not isinstance(k, int) or k <= 0:
+        raise ValueError(f"{name} must be a positive integer (got {k}).")
+
+def _bin_spectral(arr: np.ndarray, k: int) -> np.ndarray:
+    b = arr.shape[-1]
+    if b % k != 0:
+        arr = arr[..., : (b // k) * k]
+        b = arr.shape[-1]
+    return arr.reshape(*arr.shape[:-1], b // k, k).mean(axis=-1)
+
+def _bin_spatial_along_samples(arr: np.ndarray, k: int) -> np.ndarray:
+    s = arr.shape[1]
+    if s % k != 0:
+        arr = arr[:, : (s // k) * k, :]
+        s = arr.shape[1]
+    return arr.reshape(arr.shape[0], s // k, k, arr.shape[2]).mean(axis=2)
+
+def _rotate(arr: np.ndarray, k: int) -> np.ndarray:
+    # numpy.rot90 CCW; MATLAB used +90 for R and -90 for F
+    if k == 1:
+        return np.rot90(arr, k=1, axes=(0, 1))
+    elif k == -1:
+        return np.rot90(arr, k=3, axes=(0, 1))
+    raise ValueError("k must be 1 or -1.")
+
+def _imquantize_mask(img: np.ndarray) -> np.ndarray:
+    ths = threshold_multiotsu(img, classes=2)
+    mask = (img >= ths[0])
+    mask = remove_small_objects(mask, 100, connectivity=2)
+    mask = binary_fill_holes(mask)
+    return mask
+
+def _extract_masked_spectra(cube: np.ndarray, mask: np.ndarray) -> np.ndarray:
+    h, w, b = cube.shape
+    flat = cube.reshape(h * w, b)
+    flat_mask = mask.reshape(h * w)
+    return flat[flat_mask]
+
+# case-insensitive _R/_F + .hdr/.HDR + .img/.IMG
+def _read_envi_cube(base: str, suffix: str) -> np.ndarray:
+    hdr_candidates = [f"{base}_{suffix}.hdr", f"{base}_{suffix}.HDR"]
+    for hdr in hdr_candidates:
+        if os.path.exists(hdr):
+            ds = envi.open(hdr)
+            return np.asarray(ds.load())
+
+    img_candidates = [f"{base}_{suffix}.img", f"{base}_{suffix}.IMG"]
+    for img in img_candidates:
+        if os.path.exists(img):
+            shape = (N_LINE_SAMPLE if suffix.upper() == 'R' else N_LINE_DARK, N_SAMPLE, N_BAND)
+            arr = io.bilopen(img, shape=shape, dtype=np.int16, byteorder='<').load()
+            return np.asarray(arr)
+
+    raise FileNotFoundError(f"Could not find any of {hdr_candidates + img_candidates}")
+
+_BASE_RE = re.compile(r'_(R|F)\.(hdr|img)$', flags=re.IGNORECASE)
+def _strip_base(path: str) -> str:
+    return _BASE_RE.sub('', path)
+
+# -------- core calibration --------
+def _calibrate_pair(
+    sample_base: str,
+    dark_base: str,
+    spectral_bin: int = DEFAULT_SPECTRAL_BIN,
+    spatial_bin: int  = DEFAULT_SPATIAL_BIN,
+) -> Dict[str, np.ndarray]:
+    _check_factor(spectral_bin, "spectral_bin")
+    _check_factor(spatial_bin,  "spatial_bin")
+
+    # Read cubes
+    IR_sample = _read_envi_cube(sample_base, "R")
+    IF_sample = _read_envi_cube(sample_base, "F")
+    IR_dark   = _read_envi_cube(dark_base,   "R")
+    IF_dark   = _read_envi_cube(dark_base,   "F")
+
+    # Binning
+    IR_sample = _bin_spectral(IR_sample, spectral_bin)
+    IF_sample = _bin_spectral(IF_sample, spectral_bin)
+    IR_dark   = _bin_spectral(IR_dark,   spectral_bin)
+    IF_dark   = _bin_spectral(IF_dark,   spectral_bin)
+
+    IR_sample = _bin_spatial_along_samples(IR_sample, spatial_bin)
+    IF_sample = _bin_spatial_along_samples(IF_sample, spatial_bin)
+    IR_dark   = _bin_spatial_along_samples(IR_dark,   spatial_bin)
+    IF_dark   = _bin_spatial_along_samples(IF_dark,   spatial_bin)
+
+    # IFOV crop (cols)
+    IR_sample = IR_sample[:, INDEX_IFOV, :]
+    IF_sample = IF_sample[:, INDEX_IFOV, :]
+    IR_dark   = IR_dark[:,   INDEX_IFOV, :]
+    IF_dark   = IF_dark[:,   INDEX_IFOV, :]
+
+    # dark averages over lines
+    IR_dark_mean = IR_dark.mean(axis=0, keepdims=True).repeat(IR_sample.shape[0], axis=0)
+    IF_dark_mean = IF_dark.mean(axis=0, keepdims=True).repeat(IF_sample.shape[0], axis=0)
+
+    # white (lines 21–40) from sample R
+    I_white = IR_sample[INDEX_WHITE, :, :].mean(axis=0, keepdims=True).repeat(IR_sample.shape[0], axis=0)
+
+    # flat-field reflectance + fluorescence
+    with np.errstate(divide='ignore', invalid='ignore'):
+        R_sample = (IR_sample - IR_dark_mean) / (I_white - IR_dark_mean)
+        R_sample = np.nan_to_num(R_sample, nan=0.0, posinf=0.0, neginf=0.0)
+    F_sample = (IF_sample - IF_dark_mean)
+
+    # rotations
+    R_sample_rot = _rotate(R_sample, k=1)
+    F_sample_rot = _rotate(F_sample, k=-1)
+
+    # plant crops
+    R_plant = R_sample_rot[:, INDEX_PLANT_R, :]
+    idx_f_start = INDEX_PLANT_R.start + INDEX_PLANT_F_SHIFT
+    idx_f_stop  = INDEX_PLANT_R.stop  + INDEX_PLANT_F_SHIFT
+    F_plant = F_sample_rot[:, slice(idx_f_start, idx_f_stop), :]
+
+    # mask from R@815
+    R815 = R_plant[:, :, B815]
+    M_plant = _imquantize_mask(R815)
+
+    # abnormal reflectance removal
+    bad = (R_plant.min(axis=2) <= 0) | (R815 < 0.2)
+    R_mask = M_plant & (~bad)
+    F_mask = M_plant  # keep same as MATLAB-style (F abnormal was commented)
+
+    # spectra
+    RS_plant = _extract_masked_spectra(R_plant, R_mask)
+    FS_plant = _extract_masked_spectra(F_plant, F_mask)
+
+    return {
+        "R_plant": R_plant.astype(np.float32),
+        "F_plant": F_plant.astype(np.float32),
+        "M_plant": M_plant.astype(bool),
+        "RS_plant": RS_plant.astype(np.float32),
+        "FS_plant": FS_plant.astype(np.float32),
+    }
+
+# -------- public api --------
+def calibrate(
+    sample_base: str,
+    dark_base: str,
+    spectral_bin: int = DEFAULT_SPECTRAL_BIN,
+    spatial_bin: int  = DEFAULT_SPATIAL_BIN,
+) -> Dict[str, np.ndarray]:
+    return _calibrate_pair(sample_base, dark_base, spectral_bin, spatial_bin)
+
+def calibrate_folder(
+    folder: str,
+    dark_base: str,
+    spectral_bin: int = DEFAULT_SPECTRAL_BIN,
+    spatial_bin: int  = DEFAULT_SPATIAL_BIN,
+    pattern: str = "*_R.*",
+) -> List[Dict[str, np.ndarray]]:
+    _check_factor(spectral_bin, "spectral_bin")
+    _check_factor(spatial_bin,  "spatial_bin")
+
+    # gather R candidates, case-insensitive
+    candidates = set()
+    for p in glob.glob(os.path.join(folder, "*_R.*")): candidates.add(p)
+    for p in glob.glob(os.path.join(folder, "*_r.*")): candidates.add(p)
+
+    norm_dark = os.path.normcase(_strip_base(dark_base))
+    results = []
+
+    for rfile in sorted(candidates):
+        base = _strip_base(rfile)
+        if os.path.normcase(base) == norm_dark:
+            continue  # skip dark
+
+        out = _calibrate_pair(base, dark_base, spectral_bin, spatial_bin)
+
+        # save calibrated cubes
+        savemat(base + "_R.mat", {"R_plant": out["R_plant"]})
+        savemat(base + "_F.mat", {"F_plant": out["F_plant"]})
+
+        results.append(out)
+    return results
+
+# -------- cli --------
+def main(argv: Optional[List[str]] = None):
+    import argparse
+    p = argparse.ArgumentParser(prog="mvos-hsi", description="MVOS HSI calibration")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s1 = sub.add_parser("calibrate", help="Calibrate one sample")
+    s1.add_argument("--sample", required=True, help="base path without _R/_F")
+    s1.add_argument("--dark",   required=True, help="dark base without _R/_F")
+    s1.add_argument("--k", type=int, default=DEFAULT_SPECTRAL_BIN, help="spectral bin factor (>=1)")
+    s1.add_argument("--spatial", type=int, default=DEFAULT_SPATIAL_BIN, help="spatial bin factor (>=1)")
+
+    s2 = sub.add_parser("calibrate-folder", help="Calibrate all samples in a folder")
+    s2.add_argument("--folder", required=True)
+    s2.add_argument("--dark",   required=True)
+    s2.add_argument("--k", type=int, default=DEFAULT_SPECTRAL_BIN)
+    s2.add_argument("--spatial", type=int, default=DEFAULT_SPATIAL_BIN)
+    s2.add_argument("--pattern", default="*_R.*", help="glob to find R files (case-insensitive handled)")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "calibrate":
+        if args.k == 0:
+            raise ValueError("spectral bin 0 is not allowed.")
+        out = calibrate(args.sample, args.dark, spectral_bin=args.k, spatial_bin=args.spatial)
+        # save outputs like folder mode
+        savemat(args.sample + "_R.mat", {"R_plant": out["R_plant"]})
+        savemat(args.sample + "_F.mat", {"F_plant": out["F_plant"]})
+        print(f"Calibrated and saved: {args.sample}_R.mat, {args.sample}_F.mat")
+
+    elif args.cmd == "calibrate-folder":
+        if args.k == 0:
+            raise ValueError("spectral bin 0 is not allowed.")
+        outs = calibrate_folder(args.folder, args.dark, spectral_bin=args.k, spatial_bin=args.spatial, pattern=args.pattern)
+        print(f"Calibrated {len(outs)} sample(s) and saved *_R.mat / *_F.mat")