{"id":29605802,"url":"https://github.com/fangq/redbird","last_synced_at":"2025-07-20T16:38:19.974Z","repository":{"id":78325016,"uuid":"258383292","full_name":"fangq/redbird","owner":"fangq","description":"Redbird - A Model-Based Diffuse Optical Imaging Toolbox","archived":false,"fork":false,"pushed_at":"2025-07-09T13:37:09.000Z","size":936,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-15T02:47:53.985Z","etag":null,"topics":["algorithms","diffuse-optical-tomography","finite-element-methods","fnirs","forward-simulation","gauss-newton-method","inverse-problems","medical-imaging","near-infrared-spectroscopy","physics-simulation","reconstruction-algorithm","regularization"],"latest_commit_sha":null,"homepage":"https://mcx.space/redbird","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fangq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-24T02:23:49.000Z","updated_at":"2025-07-10T21:56:49.000Z","dependencies_parsed_at":"2024-06-16T04:25:11.501Z","dependency_job_id":"1b50a7e4-8b4c-4ca7-a13e-fb60accaef2a","html_url":"https://github.com/fangq/redbird","commit_stats":null,"previous_names":["fangq/redbird"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fangq/redbird","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fredbird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fredbird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fredbird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fredbird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fangq","download_url":"https://codeload.github.com/fangq/redbird/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fredbird/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266161011,"owners_count":23885886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","diffuse-optical-tomography","finite-element-methods","fnirs","forward-simulation","gauss-newton-method","inverse-problems","medical-imaging","near-infrared-spectroscopy","physics-simulation","reconstruction-algorithm","regularization"],"created_at":"2025-07-20T16:38:16.971Z","updated_at":"2025-07-20T16:38:19.967Z","avatar_url":"https://github.com/fangq.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./doc/images/redbird_banner.png)\n\n# Redbird - A Model-Based Diffuse Optical Imaging Toolbox\n\n* **Copyright**: (C) Qianqian Fang (2005–2025) \\\u003cq.fang at neu.edu\u003e, Edward Xu (2024) \\\u003cxu.ed at northeastern.edu\u003e\n* **License**: GNU Public License V3 or later\n* **Version**: 0.5.0 (Northern Cardinal)\n* **GitHub**: [https://github.com/fangq/redbird](https://github.com/fangq/redbird)\n* **Acknowledgement**: This project is supported by the US National Institute of Health (NIH)\n  grant [R01-CA204443](https://reporter.nih.gov/project-details/10982160)\n\n---\n\n\n## Table of Contents\n- [Introduction](#introduction)\n- [How to Install](#how-to-install)\n- [Workflow Overview](#workflow-overview)\n- [How to Use](#how-to-use)\n  - [Input Data Structure](#input-data-structure)\n  - [Streamlined Forward and Inverse Solvers](#streamlined-forward-and-inverse-solvers)\n    - [rbrun](#rbrun)\n    - [rbrunforward](#rbrunforward)\n    - [rbrunrecon](#rbrunrecon)\n- [How to Cite](#how-to-cite)\n\n---------\n\n## Introduction\n\n**Redbird** is a compact, portable, and feature-rich diffuse optical imaging (DOI) and diffuse optical tomography (DOT) toolbox for MATLAB and GNU Octave. It provides a fast, experimentally-validated forward solver for the diffusion equation using the finite-element (FE) method, along with advanced non-linear image reconstruction algorithms.\n\nRedbird is the result of over two decades of active research in DOT and image reconstruction in Dr. Fang's lab. It has been the core data analysis tool in over a dozen journal publications related to optical breast imaging, prior-guided reconstruction techniques, multi-modal imaging, and wide-field DOT systems.\n\nThe forward solver is carefully validated against our widely used Monte Carlo (MC) solvers—**MCX** and **MMC**. The inverse solvers incorporate advanced reconstruction techniques and are designed for users across a wide spectrum of experience levels.\n\nTechniques such as dual-mesh modeling, multi-spectral chromophore estimation, the adjoint method, structural-prior-guided reconstructions, block iterative solvers, and log-amplitude-phase reconstruction have their roots in the author's PhD dissertation and have been continuously improved over the years.\n\n---\n\n## How to Install\n\nInstalling Redbird is straightforward. After downloading and unzipping the toolbox, simply run `addpath()` in MATLAB or Octave:\n\n```matlab\naddpath('/path/to/redbird/matlab')\n```\n\nReplace `/path/to/redbird/matlab` with the actual unzipped folder path.\n\nAlthough Redbird implements all core functionalities in native MATLAB code for portability, it includes a C-based MEX file, `rbfemmatrix.cpp`, to accelerate FE matrix and Jacobian computations. Precompiled `.mex` files are included for Linux, Windows, and macOS.\n\nTo rebuild the MEX file manually:\n\n```matlab\nmex rbfemmatrix.cpp\n```\n\nOr run `make mex` in the `redbird/matlab` folder using a terminal.\n\nRedbird accepts tetrahedral mesh data from any mesh generator, but it integrates particularly well with our **iso2mesh toolbox**: [https://iso2mesh.sf.net](https://iso2mesh.sf.net). All scripts in the `example/` folder require iso2mesh.\n\n---\n\n## Workflow Overview\n\nRedbird performs two main tasks:\n\n* **Forward simulation**: Computes light distribution (fluence, in 1/mm²) across source-detector arrays within a mesh-based medium with known optical properties.\n* **Image reconstruction** (inverse solution): Iteratively recovers 3D distributions of unknown optical properties by fitting forward simulations to measured data.\n\nThe Redbird forward solver is equivalent to our MC-based solvers like MCX and MMC, but it solves the **diffusion equation (DE)** instead of the more general **radiative transfer equation (RTE)**. As a result, Redbird is typically over 100× faster (without needing GPUs), and its outputs are free of stochastic noise.\n\n**Note**: The diffusion approximation is only valid in high-scattering media, where the reduced scattering coefficient (μs') is much greater than the absorption coefficient (μa). Using Redbird in low-scattering media such as water or cerebrospinal fluid (CSF) may produce biased results.\n\n### Reconstruction Modes\n\nRedbird supports four types of image reconstructions:\n\n1. **Bulk property fitting**: Estimates a single set of optical properties (bulk values) for the entire domain.\n2. **Segmented reconstruction**: Estimates one set of properties per labeled tissue segment. Often called **\"hard-prior\"** reconstruction.\n3. **Soft-prior reconstruction**: Incorporates spatial priors as soft constraints (e.g., from MRI or CT), enabling **compositional-prior** approaches.\n4. **Unconstrained reconstruction**: Assumes each node/element has independent properties; solves via minimum-norm using **Tikhonov regularization**.\n\n---\n\n## How to Use\n\n### Input Data Structure\n\nThe main driver function, `rbrunforward()`, takes a configuration structure `cfg` with the following fields:\n\n* `node`, `face`, `elem`: mesh node coordinates, surface triangles, and tetrahedra\n* `seg`: tissue labels per element (or per node if same length as `node`)\n* `prop`: single-wavelength optical properties (label-wise), same format as MCX/MMC\n    * or `param`: multi-spectral properties (e.g., chromophore concentrations), used to compute `prop` if defined\n* `srcpos`, `srcdir`: source positions and direction vectors\n* `detpos`, `detdir`: detector positions and direction vectors\n* `omega`: modulation angular frequency in the unit of rad for frequency-domain DOI/DOT\n\nBesides the forward `cfg`, the inverse solver `rbrunrecon()` requires a `recon` struct:\n\n* `node`, `elem`: optional reconstruction mesh (typically coarser); enables **dual-mesh**\n* `lambda`: Tikhonov regularization parameter\n* `bulk`: initial guesses (single-wavelength: `mua`, `musp`, etc. or multi-spectral: `hbo`, `hbr`, etc.)\n    * or `prop`: initial distribution of single-wavelength optical properties, with length matching that of `cfg.node` or `cfg.elem`\n    * or `param`: initial distribution of multi-spectral optical properties, with length matching that of `cfg.node` or `cfg.elem`\n\n### Streamlined forward and inverse solvers\n\n#### `rbrun` \n\n`rbrun()` is the **all-in-one** interface to use redbird for forward and inverse modeling. It supports\nseveral forms.\n\nFor example, the following one-liner\n```\ndetphi0 = rbrun(cfg);\n```\nsolves for the forward solution at all source/detector pairs (detphi0) using the `cfg` input, this\nis the same as calling `detphi0 = rbrunforward(cfg)`, see below.\n\nIf 3 inputs are given, such as\n```\nnewrecon = rbrun(cfg, recon, detphi0);\n```\n`rbrun` performs a reconstruction by fitting the measurement data stored `detphi0` using the\nreconstruction data structures `cfg` and `recon`. This is the same as `newrecon = rbrunrecon(10, cfg, recon, detphi0)`\n\nIf the 3rd input is a struct that resembles a forward cfg data structure,\n```\nnewrecon = rbrun(cfg, recon, cfg0);\n```\nthis performs a streamlined forward-simulation using `cfg0`, immediately followed by\na reconstruction using `cfg` and `recon`. This is equivallent to \n```\ndetphi0 = rbrunforward(cfg0);\nnewrecon = rbrunrecon(10, cfg, recon, detphi0);\n```\n\n\n#### `rbrunforward`\n\n`rbrunforward` is the streamlined forward solver of redbird.\n\n```\n[detval, phi]=rbrunforward(cfg)\n   or\n[detval, phi, Amat, rhs]=rbrunforward(cfg,'param1',value1,...)\n\nPerform forward simulations at all sources and all wavelengths based on the input structure\n\ninput:\n    cfg: the redbird cfg input defining the forward simulation settings\n\noutput:\n    detval: the values at every source-detector combination (i.e. channels)\n    phi: the full volumetric forward solution computed at all wavelengths at every source and detector\n    Amat: the left-hand-side matrices (a containers.Map object) at specified wavelengths\n    rhs: the right-hand-side vectors for all sources (independent of wavelengths)\n    param/value pairs: (optional) additional parameters\n         'solverflag': a cell array to be used as the optional parameters\n              for rbfemsolve (starting from parameter 'method'), for\n              example  rbrunforward(...,'solverflag',{'pcg',1e-10,200})\n              calls rbfemsolve(A,rhs,'pcg',1e-10,200) to solve forward\n              solutions\n```\n\n#### `rbrunrecon`\n\n`rbrunrecon` is the streamlined inverse solver of redbird.\n\n```\n[newrecon, resid, newcfg]=rbrunrecon(maxiter,cfg,recon,detphi0,sd)\n  or\n[newrecon, resid, newcfg, updates, Jmua, detphi, phi]=rbrunrecon(maxiter,cfg,recon,detphi0,sd,'param1',value1,'param2',value2,...)\n\nPerform a single iteration of a Gauss-Newton reconstruction\n\ninput:\n    maxiter: number of iterations\n    cfg: simulation settings stored as a redbird data structure\n    recon: reconstruction data structure, recon may have\n        node: reconstruction mesh node list\n        elem: reconstruction mesh elem list\n        bulk: a struct storing the initial guesses of the param\n        param: wavelength-independent parameter on the recon mesh\n        prop: wavelength-dependent optical properties on the recon mesh\n        lambda: Tikhonov regularization parameter\n        mapid: the list of element indices of the reconstruction mesh where each forward mesh\n          node is enclosed\n        mapweight: the barycentric coordinates of the forward mesh nodes inside the\n          reconstruction mesh elements\n    detphi0: measurement data vector or matrix\n    sd (optional): source detector mapping table, if not provided, call\n        rbsdmap(cfg) to compute\n    param/value: acceptable optional parameters include\n        'lambda': Tikhonov regularization parameter (0.05), overwrite recon.lambda\n        'report': 1 (default) to print residual and runtimes; 0: silent\n        'tol': convergence tolerance, if relative residual is less than\n               this value, stop, default is 0, which runs maxiter\n               iterations\n        'reform': 'real', 'complex' or 'logphase'\n        'mex':  whether to use mex file for Jacobian calculations\n        'prior': apply structure-prior-guided reconstruction,\n               supported methods include 'laplace' and 'comp' for use compositional-priors\n\noutput:\n    recon: the updated recon structure, containing recon mesh and\n         reconstructed values in recon.prop or recon.param\n    resid: the residual betweet the model and the measurement data for\n         each iteration\n    cfg: the updated cfg structure, containing forward mesh and\n         reconstructed values in cfg.prop or cfg.param\n    updates: a struct array, where the i-th element stores the update\n         vectors for each unknown block\n    Jmua: Jacobian in a struct form, each element is the Jacobian of an\n         unknown block\n    detphi: the final model prediction that best fits the data detphi0\n    phi: the final forward solutions resulting from the estimation\n```\n---\n\n## How to cite\n\nMany of the key algorithms in redbird have been initially developed by the author, Dr. Fang, \nbetween 2001 and 2005 and are described in details in his PhD dissertation\n\n- Qianqian Fang, \"Computational methods for microwave medical imaging,\" Ph.D. dissertation, Dartmouth College, Hanover, NH, 2004\n\nWhile the initial software, code-named **white-dragon** written in FORTRAN90, was developed \nfor the purpose of microwave tomography, a large portion of its workflow are directly\napplicable to DOT, especially the inverse solvers. The only main difference is that white-dragon\nsolves the Helmholtz equation for microwave forward problem, while redbird solves for the\ndiffusion equation.\n\nBetween 2005 and 2007, Dr. Fang had extended white-dragon to DOT, and developed redbird in\nFORTRAN90. During the following period, over a dozen DOT based papers were published based\nupon computations using redbird-FORTRAN90. Specifically, the redbird software workflow\nwas specifically described in the following OSA/Optica conference proceeding in 2008\n\n- Fang Q, et al., \"A multi-modality image reconstruction platform for diffuse optical tomography,\" \n  in Biomed. Opt., BMD24 (2008). https://doi.org/10.1364/BIOMED.2008.BMD24\n\nfollowed by a journal paper in 2009\n\n- Fang Q, Carp SA, Selb J, Boverman G, Zhang Q, Kopans DB, Moore RH, Brooks DH, Miller EL, \n  Boas DA, \"Combined optical Imaging and mammography of the healthy breast: optical contrast \n  derives from breast structure and compression,\" IEEE Trans. Medical Imaging, \n  vol. 28, issue 1, pp. 30 – 42, Jan. 2009.\n\nThe compositional-prior guided reconstructions have been published in the following series of papers\n- Fang Q, Moore RH, Kopans DB, Boas DA, \"Compositional-prior-guided image reconstruction algorithm \n  for multi-modality imaging,\" Biomedical Optics Express, vol. 1, issue 1, pp. 223-235, 2010.\n- Deng B, Brooks DH, Boas DA, Lundqvist M, and Fang Q, \"Characterization of structural-prior \n  guided optical tomography using realistic breast models derived from dual-energy x-ray mammography,\" Biomed. Opt. Express 6(7), 2366-2379, 2015\n\nwith an extension to this algorithm described in the following US patent\n- Fang Q, \"Method to localize small and high contrast inclusions in ill-posed model-based imaging modalities\", US Patent US-11246529-B2, approved on 2022/02/15\n\nThe multi-spectral reconstruction was initially published in \n- Fang Q, Meaney PM, Paulsen KD, \"Microwave image reconstruction of tissue property dispersion \n  characteristics utilizing multiple frequency information\", IEEE Transactions on Microwave \n  Theory and Techniques, vol. 52, No. 8, pp. 1866-1875, Aug. 2004.\n\nwhich had inspired and subsequently applied to DOT imaging by Shuba Srinivasan, a PhD student working in the same research team\n- S. Srinivasan, B. W. Pogue, S. Jiang, H. Dehghani, and K. D. Paulsen, \"Spectrally constrained \n  chromophore and scattering NIR tomography provides quantitative and robust reconstruction,\" Appl. Opt. 44, 1858–69 (2005).\n\nOver the last two decades, redbird has been the underlying data analysis \ntool behind a list of DOT related publications from the author's lab, including\n\n- Fang Q, Selb J, Carp SA, Kopans DB, Moore RH, Brooks DH, Miller EL, Boas DA, \"Combined optical \n  and tomosynthesis breast imaging,\" Radiology, (cover article) vol. 258, No. 1, pp. 89-97, 2011.\n- Deng B, Fradkin M, Rouet JM, Moore RH, Kopans DB, Boas DA, Lundqvist M, and Fang Q, \"Characterizing \n  breast lesions through robust multi-modal data fusion using independent diffuse optical and x-ray \n  breast imaging,\" Journal of Biomed. Optics Letters, 20(8), 080502, 2015\n- Aiden Vincent Lewis, Qianqian Fang*, \"Revisiting equivalent optical properties for cerebrospinal fluid to improve diffusion-based modeling accuracy in the brain,\" Neurophoton. 12(1) 015009 2025 https://doi.org/10.1117/1.NPh.12.1.015009\n- Miguel Mireles, Edward Xu, Morris Vanegas, Ailis Muldoon, Rahul Ragunathan, Shijie Yan, Bin Deng, Jayne Cormier, Mansi Saksena, Stefan A. Carp, and Qianqian Fang*, \"Widefield ultra-high-density optical breast tomography system supplementing x-ray mammography,\" Scientific Reports 15, 8732 (2025). https://doi.org/10.1038/s41598-025-92261-9\n- Miguel Mireles, Edward Xu, Rahul Ragunathan, and Qianqian Fang, \"Medium-adaptive compressive diffuse optical tomography,\" Biomed. Opt. Express 15, 5128-5142 (2024) https://doi.org/10.1364/BOE.529195\n- Bin Deng, Mats Lundqvist, Qianqian Fang, Stefan Carp, \"Impact of errors in experimental parameters on reconstructed breast images using diffuse optical tomography,\" Biomed Optics Express, 9(3):1130-1150 2018\n- Ailis Muldoon, Aiza Kabeer, Jayne Cormier, Mansi A. Saksena, Qianqian Fang, Stefan A. Carp, and Bin Deng, \"Method to improve the localization accuracy and contrast recovery of lesions in separately acquired X-ray and diffuse optical tomographic breast imaging,\" Biomed. Opt. Express 13, 5295-5310 (2022)\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fredbird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffangq%2Fredbird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fredbird/lists"}