redbirdpy 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- redbirdpy/__init__.py +112 -0
- redbirdpy/analytical.py +927 -0
- redbirdpy/forward.py +589 -0
- redbirdpy/property.py +602 -0
- redbirdpy/recon.py +893 -0
- redbirdpy/solver.py +814 -0
- redbirdpy/utility.py +1117 -0
- redbirdpy-0.1.0.dist-info/METADATA +596 -0
- redbirdpy-0.1.0.dist-info/RECORD +13 -0
- redbirdpy-0.1.0.dist-info/WHEEL +5 -0
- redbirdpy-0.1.0.dist-info/licenses/LICENSE.txt +674 -0
- redbirdpy-0.1.0.dist-info/top_level.txt +1 -0
- redbirdpy-0.1.0.dist-info/zip-safe +1 -0
|
@@ -0,0 +1,596 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: redbirdpy
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python toolbox for Diffuse Optical Tomography (DOT) and Near-Infrared Spectroscopy (NIRS)
|
|
5
|
+
Home-page: https://github.com/fangq/redbirdpy
|
|
6
|
+
Author: Qianqian Fang
|
|
7
|
+
Author-email: Qianqian Fang <fangqq@gmail.com>
|
|
8
|
+
Maintainer: Qianqian Fang
|
|
9
|
+
Maintainer-email: Qianqian Fang <fangqq@gmail.com>
|
|
10
|
+
License: GPL-3.0
|
|
11
|
+
Project-URL: Homepage, https://github.com/fangq/redbirdpy
|
|
12
|
+
Project-URL: Documentation, https://github.com/fangq/redbirdpy#readme
|
|
13
|
+
Project-URL: Repository, https://github.com/fangq/redbirdpy
|
|
14
|
+
Project-URL: Bug Tracker, https://github.com/fangq/redbirdpy/issues
|
|
15
|
+
Keywords: Diffuse Optical Tomography,DOT,NIRS,Near-Infrared Spectroscopy,FEM,Finite Element Method,Biomedical Optics,Image Reconstruction,Inverse Problem,Photon Migration,Diffusion Equation,Tissue Optics
|
|
16
|
+
Platform: any
|
|
17
|
+
Classifier: Development Status :: 3 - Alpha
|
|
18
|
+
Classifier: Intended Audience :: Science/Research
|
|
19
|
+
Classifier: Intended Audience :: Developers
|
|
20
|
+
Classifier: Intended Audience :: Healthcare Industry
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
24
|
+
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
|
|
25
|
+
Classifier: Programming Language :: Python :: 3
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.6
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
28
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
29
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
30
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
31
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
32
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
33
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
34
|
+
Classifier: Operating System :: OS Independent
|
|
35
|
+
Requires-Python: >=3.6
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
License-File: LICENSE.txt
|
|
38
|
+
Requires-Dist: numpy>=1.15.0
|
|
39
|
+
Requires-Dist: scipy>=1.0.0
|
|
40
|
+
Provides-Extra: mesh
|
|
41
|
+
Requires-Dist: iso2mesh>=0.5.4; extra == "mesh"
|
|
42
|
+
Provides-Extra: dev
|
|
43
|
+
Requires-Dist: pytest>=6.0; extra == "dev"
|
|
44
|
+
Requires-Dist: pytest-cov>=2.0; extra == "dev"
|
|
45
|
+
Requires-Dist: flake8>=3.0; extra == "dev"
|
|
46
|
+
Provides-Extra: all
|
|
47
|
+
Requires-Dist: iso2mesh>=0.5.4; extra == "all"
|
|
48
|
+
Requires-Dist: matplotlib>=3.0; extra == "all"
|
|
49
|
+
Dynamic: author
|
|
50
|
+
Dynamic: home-page
|
|
51
|
+
Dynamic: license-file
|
|
52
|
+
Dynamic: maintainer
|
|
53
|
+
Dynamic: platform
|
|
54
|
+
Dynamic: requires-python
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
58
|
+
# RedbirdPy - A Model-Based Diffuse Optical Imaging Toolbox for Python
|
|
59
|
+
|
|
60
|
+
* **Copyright**: (C) Qianqian Fang (2005–2025) \<q.fang at neu.edu>
|
|
61
|
+
* **License**: GNU Public License V3 or later
|
|
62
|
+
* **Version**: 0.1.0
|
|
63
|
+
* **GitHub**: [https://github.com/fangq/redbirdpy](https://github.com/fangq/redbirdpy)
|
|
64
|
+
* **Acknowledgement**: This project is supported by the US National Institute of Health (NIH)
|
|
65
|
+
grant [R01-CA204443](https://reporter.nih.gov/project-details/10982160)
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Table of Contents
|
|
70
|
+
|
|
71
|
+
- [Introduction](#introduction)
|
|
72
|
+
- [Installation](#installation)
|
|
73
|
+
- [Quick Start](#quick-start)
|
|
74
|
+
- [Workflow Overview](#workflow-overview)
|
|
75
|
+
- [Module Structure](#module-structure)
|
|
76
|
+
- [Data Structures](#data-structures)
|
|
77
|
+
- [Forward Structure `cfg`](#forward-structure-cfg)
|
|
78
|
+
- [Reconstruction Structure `recon`](#reconstruction-structure-recon)
|
|
79
|
+
- [Wide-Field Sources and Detectors](#wide-field-sources-and-detectors)
|
|
80
|
+
- [Multi-Spectral Simulations](#multi-spectral-simulations)
|
|
81
|
+
- [Examples](#examples)
|
|
82
|
+
- [Units](#units)
|
|
83
|
+
- [Running Tests](#running-tests)
|
|
84
|
+
- [How to Cite](#how-to-cite)
|
|
85
|
+
- [References](#references)
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Introduction
|
|
90
|
+
|
|
91
|
+
**Redbird-Python** is a Python translation of the [Redbird MATLAB toolbox](https://github.com/fangq/redbird) for diffuse optical imaging (DOI) and diffuse optical tomography (DOT). It provides a fast, experimentally-validated forward solver for the diffusion equation using the finite-element method (FEM), along with advanced non-linear image reconstruction algorithms.
|
|
92
|
+
|
|
93
|
+
Redbird is the result of over two decades of active research in DOT and image reconstruction. It has been the core data analysis tool in numerous publications related to optical breast imaging, prior-guided reconstruction techniques, multi-modal imaging, and wide-field DOT systems.
|
|
94
|
+
|
|
95
|
+
### Key Features
|
|
96
|
+
|
|
97
|
+
- **Forward Modeling**: Solve the diffusion equation for photon fluence using FEM
|
|
98
|
+
- **Inverse Reconstruction**: Iterative Gauss-Newton with Tikhonov regularization
|
|
99
|
+
- **Wide-Field Sources/Detectors**: Support for planar, pattern, and Fourier-basis illumination
|
|
100
|
+
- **Multi-Spectral Analysis**: Wavelength-dependent simulations for chromophore estimation
|
|
101
|
+
- **Frequency-Domain**: Support for amplitude-modulated light sources
|
|
102
|
+
- **Dual-Mesh Reconstruction**: Use coarse mesh for faster inverse solving
|
|
103
|
+
- **Structure Priors**: Laplacian, Helmholtz, and compositional priors
|
|
104
|
+
|
|
105
|
+
### Validation
|
|
106
|
+
|
|
107
|
+
The forward solver is carefully validated against Monte Carlo solvers—**MCX** and **MMC**. The diffusion approximation is valid in high-scattering media where the reduced scattering coefficient (μs') is much greater than the absorption coefficient (μa).
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Installation
|
|
112
|
+
|
|
113
|
+
### Requirements
|
|
114
|
+
|
|
115
|
+
- Python 3.8+
|
|
116
|
+
- NumPy
|
|
117
|
+
- SciPy
|
|
118
|
+
|
|
119
|
+
### Basic Installation
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
pip install numpy scipy
|
|
123
|
+
# For mesh generation
|
|
124
|
+
pip install iso2mesh # or from https://github.com/NeuroJSON/pyiso2mesh
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Optional Dependencies
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
# For accelerated Jacobian computation
|
|
131
|
+
pip install numba # JIT compilation
|
|
132
|
+
|
|
133
|
+
# For accelerated solvers
|
|
134
|
+
pip install blocksolver # or from https://github.com/fangq/
|
|
135
|
+
|
|
136
|
+
# For other linear solvers
|
|
137
|
+
pip install pypardiso # Intel MKL PARDISO (fastest direct solver)
|
|
138
|
+
pip install scikit-umfpack # UMFPACK direct solver
|
|
139
|
+
pip install pyamg # Algebraic multigrid preconditioner
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Installation from Source
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
git clone https://github.com/fangq/redbirdpy.git
|
|
146
|
+
cd redbirdpy
|
|
147
|
+
pip install -e .
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Or simply add the `redbirdpy` folder to your Python path.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Quick Start
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
import numpy as np
|
|
158
|
+
import redbirdpy as rb
|
|
159
|
+
from iso2mesh import meshabox
|
|
160
|
+
|
|
161
|
+
# Create mesh (iso2mesh returns 1-based indices)
|
|
162
|
+
node, face, elem = meshabox([0, 0, 0], [60, 60, 30], 5)
|
|
163
|
+
|
|
164
|
+
# Define optical properties [mua, mus, g, n]
|
|
165
|
+
prop = np.array([
|
|
166
|
+
[0.0, 0.0, 1.0, 1.0], # Label 0 (external/air)
|
|
167
|
+
[0.01, 1.0, 0.0, 1.37] # Label 1 (tissue)
|
|
168
|
+
])
|
|
169
|
+
|
|
170
|
+
# Configure simulation
|
|
171
|
+
cfg = {
|
|
172
|
+
'node': node,
|
|
173
|
+
'elem': elem,
|
|
174
|
+
'prop': prop,
|
|
175
|
+
'srcpos': np.array([[30, 30, 0]]),
|
|
176
|
+
'srcdir': np.array([[0, 0, 1]]),
|
|
177
|
+
'detpos': np.array([[30, 40, 0], [40, 30, 0]]),
|
|
178
|
+
'detdir': np.array([[0, 0, 1]]),
|
|
179
|
+
'seg': np.ones(elem.shape[0], dtype=int),
|
|
180
|
+
'omega': 0 # CW mode
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
# Prepare mesh and run forward simulation
|
|
184
|
+
cfg, sd = rb.meshprep(cfg)
|
|
185
|
+
detval, phi = rb.run(cfg)
|
|
186
|
+
|
|
187
|
+
print(f"Detector measurements: {detval}")
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Workflow Overview
|
|
193
|
+
|
|
194
|
+
Redbird performs two main tasks:
|
|
195
|
+
|
|
196
|
+
1. **Forward Simulation**: Computes light distribution (fluence, in 1/mm²) across source-detector arrays within a mesh-based medium with known optical properties.
|
|
197
|
+
|
|
198
|
+
2. **Image Reconstruction**: Iteratively recovers 3D distributions of unknown optical properties by fitting forward simulations to measured data.
|
|
199
|
+
|
|
200
|
+
### Reconstruction Modes
|
|
201
|
+
|
|
202
|
+
Redbird supports four types of image reconstructions:
|
|
203
|
+
|
|
204
|
+
| Mode | Description |
|
|
205
|
+
|------|-------------|
|
|
206
|
+
| **Bulk Fitting** | Estimate single set of properties for entire domain |
|
|
207
|
+
| **Segmented** | One property set per labeled tissue segment ("hard-prior") |
|
|
208
|
+
| **Soft-Prior** | Spatial priors as soft constraints (Laplacian, compositional) |
|
|
209
|
+
| **Unconstrained** | Independent properties per node with Tikhonov regularization |
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Module Structure
|
|
214
|
+
|
|
215
|
+
### `redbirdpy.forward` - Forward Modeling
|
|
216
|
+
|
|
217
|
+
| Function | Description |
|
|
218
|
+
|----------|-------------|
|
|
219
|
+
| `runforward(cfg)` | Main forward solver for all sources/wavelengths |
|
|
220
|
+
| `femlhs(cfg, deldotdel, wv)` | Build FEM stiffness matrix (LHS) |
|
|
221
|
+
| `femrhs(cfg, sd, wv)` | Build right-hand-side vectors |
|
|
222
|
+
| `femgetdet(phi, cfg, rhs)` | Extract detector values |
|
|
223
|
+
| `jac(sd, phi, ...)` | Build Jacobian matrices for mua |
|
|
224
|
+
| `jacchrome(Jmua, chromes)` | Build chromophore Jacobians |
|
|
225
|
+
|
|
226
|
+
### `redbirdpy.recon` - Reconstruction
|
|
227
|
+
|
|
228
|
+
| Function | Description |
|
|
229
|
+
|----------|-------------|
|
|
230
|
+
| `runrecon(cfg, recon, data, sd)` | Iterative Gauss-Newton reconstruction |
|
|
231
|
+
| `reginv(A, b, lambda)` | Regularized inversion (auto-selects method) |
|
|
232
|
+
| `reginvover(A, b, lambda)` | Overdetermined system solver |
|
|
233
|
+
| `reginvunder(A, b, lambda)` | Underdetermined system solver |
|
|
234
|
+
| `matreform(A, ymeas, ymodel, form)` | Matrix reformulation (real/complex/logphase) |
|
|
235
|
+
| `prior(seg, type)` | Structure-prior regularization matrices |
|
|
236
|
+
| `syncprop(cfg, recon)` | Synchronize properties between meshes |
|
|
237
|
+
|
|
238
|
+
### `redbirdpy.utility` - Utilities
|
|
239
|
+
|
|
240
|
+
| Function | Description |
|
|
241
|
+
|----------|-------------|
|
|
242
|
+
| `meshprep(cfg)` | Prepare mesh with all derived quantities |
|
|
243
|
+
| `sdmap(cfg, maxdist)` | Create source-detector mapping |
|
|
244
|
+
| `src2bc(cfg, isdet)` | Convert wide-field sources to boundary conditions |
|
|
245
|
+
| `getoptodes(cfg)` | Get displaced optode positions |
|
|
246
|
+
| `getdistance(src, det)` | Compute source-detector distances |
|
|
247
|
+
| `getreff(n_in, n_out)` | Effective reflection coefficient |
|
|
248
|
+
| `getltr(cfg)` | Transport mean-free path |
|
|
249
|
+
| `addnoise(data, snr)` | Add simulated shot/thermal noise |
|
|
250
|
+
| `elem2node(elem, val)` | Element to node interpolation |
|
|
251
|
+
| `meshinterp(...)` | Interpolate between meshes |
|
|
252
|
+
|
|
253
|
+
### `redbirdpy.property` - Optical Properties
|
|
254
|
+
|
|
255
|
+
| Function | Description |
|
|
256
|
+
|----------|-------------|
|
|
257
|
+
| `extinction(wavelengths, chromes)` | Molar extinction coefficients |
|
|
258
|
+
| `updateprop(cfg)` | Update props from chromophore concentrations |
|
|
259
|
+
| `getbulk(cfg)` | Get bulk/background properties |
|
|
260
|
+
| `musp2sasp(musp, wavelength)` | Convert μs' to scattering amplitude/power |
|
|
261
|
+
| `setmesh(cfg, node, elem)` | Associate new mesh with configuration |
|
|
262
|
+
|
|
263
|
+
### `redbirdpy.solver` - Linear Solvers
|
|
264
|
+
|
|
265
|
+
| Function | Description |
|
|
266
|
+
|----------|-------------|
|
|
267
|
+
| `femsolve(A, b, method)` | Solve linear system with auto-selection |
|
|
268
|
+
| `get_solver_info()` | Query available solver backends |
|
|
269
|
+
|
|
270
|
+
Supported solvers: `pardiso`, `umfpack`, `cholmod`, `superlu`, `blqmr`, `cg`, `cg+amg`, `gmres`, `bicgstab`
|
|
271
|
+
|
|
272
|
+
### `redbirdpy.analytical` - Analytical Solutions
|
|
273
|
+
|
|
274
|
+
| Function | Description |
|
|
275
|
+
|----------|-------------|
|
|
276
|
+
| `infinite_cw(...)` | CW fluence in infinite medium |
|
|
277
|
+
| `semi_infinite_cw(...)` | CW fluence in semi-infinite medium |
|
|
278
|
+
| `semi_infinite_cw_flux(...)` | Diffuse reflectance |
|
|
279
|
+
| `infinite_td(...)` | Time-domain in infinite medium |
|
|
280
|
+
| `semi_infinite_td(...)` | Time-domain in semi-infinite medium |
|
|
281
|
+
| `sphere_infinite(...)` | Sphere in infinite medium |
|
|
282
|
+
| `sphere_semi_infinite(...)` | Sphere in semi-infinite medium |
|
|
283
|
+
| `sphere_slab(...)` | Sphere in slab geometry |
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Data Structures
|
|
288
|
+
|
|
289
|
+
### Forward Structure `cfg`
|
|
290
|
+
|
|
291
|
+
The forward solver uses a dictionary with the following fields:
|
|
292
|
+
|
|
293
|
+
#### Required Fields
|
|
294
|
+
|
|
295
|
+
| Field | Type | Description |
|
|
296
|
+
|-------|------|-------------|
|
|
297
|
+
| `node` | (Nn, 3) float | Node coordinates in mm |
|
|
298
|
+
| `elem` | (Ne, 4+) int | Tetrahedral connectivity (1-based) |
|
|
299
|
+
| `prop` | (Nseg, 4) or dict | Optical properties [mua, mus, g, n] |
|
|
300
|
+
| `srcpos` | (Ns, 3) float | Source positions |
|
|
301
|
+
| `srcdir` | (Ns, 3) or (1, 3) | Source directions |
|
|
302
|
+
| `detpos` | (Nd, 3) float | Detector positions |
|
|
303
|
+
| `detdir` | (Nd, 3) or (1, 3) | Detector directions |
|
|
304
|
+
|
|
305
|
+
#### Optional Fields
|
|
306
|
+
|
|
307
|
+
| Field | Type | Description |
|
|
308
|
+
|-------|------|-------------|
|
|
309
|
+
| `seg` | (Ne,) int | Element labels for segmentation |
|
|
310
|
+
| `omega` | float or dict | Angular frequency (rad/s), 0 for CW |
|
|
311
|
+
| `srctype` | str | Source type: `'pencil'`, `'planar'`, `'pattern'`, `'fourier'` |
|
|
312
|
+
| `srcparam1` | (4,) float | Wide-field source parameter 1 |
|
|
313
|
+
| `srcparam2` | (4,) float | Wide-field source parameter 2 |
|
|
314
|
+
| `srcpattern` | (Nx, Ny) or (Nx, Ny, Np) | Pattern source data |
|
|
315
|
+
| `dettype` | str | Detector type (same options as srctype) |
|
|
316
|
+
| `detparam1` | (4,) float | Wide-field detector parameter 1 |
|
|
317
|
+
| `detparam2` | (4,) float | Wide-field detector parameter 2 |
|
|
318
|
+
| `detpattern` | array | Pattern detector data |
|
|
319
|
+
| `bulk` | dict | Background property values |
|
|
320
|
+
| `param` | dict | Chromophore concentrations |
|
|
321
|
+
|
|
322
|
+
#### Auto-Computed Fields (via `meshprep`)
|
|
323
|
+
|
|
324
|
+
| Field | Description |
|
|
325
|
+
|-------|-------------|
|
|
326
|
+
| `face` | Surface triangles (1-based) |
|
|
327
|
+
| `area` | Face areas |
|
|
328
|
+
| `evol` | Element volumes |
|
|
329
|
+
| `nvol` | Nodal volumes |
|
|
330
|
+
| `reff` | Effective reflection coefficient |
|
|
331
|
+
| `deldotdel` | Gradient operator matrix |
|
|
332
|
+
|
|
333
|
+
### Reconstruction Structure `recon`
|
|
334
|
+
|
|
335
|
+
| Field | Type | Description |
|
|
336
|
+
|-------|------|-------------|
|
|
337
|
+
| `node` | (Nn_r, 3) float | Reconstruction mesh nodes (optional) |
|
|
338
|
+
| `elem` | (Ne_r, 4) int | Reconstruction mesh elements (optional) |
|
|
339
|
+
| `prop` | (Nn_r, 4) float | Initial/recovered optical properties |
|
|
340
|
+
| `param` | dict | Multi-spectral parameters |
|
|
341
|
+
| `lambda` | float | Tikhonov regularization parameter |
|
|
342
|
+
| `bulk` | dict | Initial guess values |
|
|
343
|
+
| `mapid` | (Nn, ) float | Forward-to-recon mesh mapping (element IDs) |
|
|
344
|
+
| `mapweight` | (Nn, 4) float | Barycentric interpolation weights |
|
|
345
|
+
| `seg` | array | Segmentation labels for priors |
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## Wide-Field Sources and Detectors
|
|
350
|
+
|
|
351
|
+
Redbird supports wide-field illumination patterns for spatially-modulated imaging.
|
|
352
|
+
|
|
353
|
+
### Source Types
|
|
354
|
+
|
|
355
|
+
| Type | Description |
|
|
356
|
+
|------|-------------|
|
|
357
|
+
| `'pencil'` | Point source (default) |
|
|
358
|
+
| `'planar'` | Uniform rectangular illumination |
|
|
359
|
+
| `'pattern'` | User-defined 2D/3D pattern array |
|
|
360
|
+
| `'fourier'` | Fourier-basis spatial frequencies |
|
|
361
|
+
|
|
362
|
+
### Configuration Example
|
|
363
|
+
|
|
364
|
+
```python
|
|
365
|
+
cfg = {
|
|
366
|
+
# ... mesh and properties ...
|
|
367
|
+
|
|
368
|
+
# Planar source
|
|
369
|
+
'srctype': 'planar',
|
|
370
|
+
'srcpos': np.array([[10, 10, 0]]), # Corner position
|
|
371
|
+
'srcparam1': np.array([40, 0, 0, 0]), # Width in x (mm)
|
|
372
|
+
'srcparam2': np.array([0, 40, 0, 0]), # Width in y (mm)
|
|
373
|
+
'srcdir': np.array([[0, 0, 1]]),
|
|
374
|
+
|
|
375
|
+
# Pattern source (multiple patterns)
|
|
376
|
+
'srctype': 'pattern',
|
|
377
|
+
'srcpattern': patterns, # Shape: (Nx, Ny) or (Nx, Ny, Npatterns)
|
|
378
|
+
|
|
379
|
+
# Fourier source (kx × ky patterns)
|
|
380
|
+
'srctype': 'fourier',
|
|
381
|
+
'srcparam1': np.array([40, 0, 0, 3]), # Last value = kx
|
|
382
|
+
'srcparam2': np.array([0, 40, 0, 3]), # Last value = ky
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
### Wide-Field Detectors
|
|
387
|
+
|
|
388
|
+
Configure similarly using `dettype`, `detparam1`, `detparam2`, `detpattern`.
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## Multi-Spectral Simulations
|
|
393
|
+
|
|
394
|
+
### Wavelength-Dependent Properties
|
|
395
|
+
|
|
396
|
+
```python
|
|
397
|
+
cfg['prop'] = {
|
|
398
|
+
'690': np.array([[0, 0, 1, 1], [0.012, 1.1, 0, 1.37]]),
|
|
399
|
+
'830': np.array([[0, 0, 1, 1], [0.008, 0.9, 0, 1.37]])
|
|
400
|
+
}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### Chromophore-Based Properties
|
|
404
|
+
|
|
405
|
+
```python
|
|
406
|
+
cfg['param'] = {
|
|
407
|
+
'hbo': 50.0, # Oxyhemoglobin (μM)
|
|
408
|
+
'hbr': 25.0, # Deoxyhemoglobin (μM)
|
|
409
|
+
'water': 0.7, # Water volume fraction
|
|
410
|
+
'lipids': 0.1, # Lipid volume fraction
|
|
411
|
+
'scatamp': 10.0, # Scattering amplitude
|
|
412
|
+
'scatpow': 1.5 # Scattering power
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
# Properties computed via: μs' = scatamp × λ^(-scatpow)
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
### Available Chromophores
|
|
419
|
+
|
|
420
|
+
| Name | Units | Description |
|
|
421
|
+
|------|-------|-------------|
|
|
422
|
+
| `hbo` | μM | Oxyhemoglobin |
|
|
423
|
+
| `hbr` | μM | Deoxyhemoglobin |
|
|
424
|
+
| `water` | fraction | Water content |
|
|
425
|
+
| `lipids` | fraction | Lipid content |
|
|
426
|
+
| `aa3` | μM | Cytochrome c oxidase |
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## Examples
|
|
431
|
+
|
|
432
|
+
### Basic Forward Simulation
|
|
433
|
+
|
|
434
|
+
```python
|
|
435
|
+
import redbirdpy as rb
|
|
436
|
+
from iso2mesh import meshabox
|
|
437
|
+
|
|
438
|
+
node, face, elem = meshabox([0, 0, 0], [60, 60, 30], 5)
|
|
439
|
+
|
|
440
|
+
cfg = {
|
|
441
|
+
'node': node, 'elem': elem,
|
|
442
|
+
'prop': np.array([[0, 0, 1, 1], [0.01, 1, 0, 1.37]]),
|
|
443
|
+
'srcpos': np.array([[30, 30, 0]]),
|
|
444
|
+
'srcdir': np.array([[0, 0, 1]]),
|
|
445
|
+
'detpos': np.array([[30, 40, 0]]),
|
|
446
|
+
'detdir': np.array([[0, 0, 1]]),
|
|
447
|
+
'seg': np.ones(elem.shape[0], dtype=int),
|
|
448
|
+
'omega': 0
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
cfg, sd = rb.meshprep(cfg)
|
|
452
|
+
detval, phi = rb.run(cfg)
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### Frequency-Domain Simulation
|
|
456
|
+
|
|
457
|
+
```python
|
|
458
|
+
cfg['omega'] = 2 * np.pi * 100e6 # 100 MHz modulation
|
|
459
|
+
detval, phi = rb.run(cfg)
|
|
460
|
+
|
|
461
|
+
amplitude = np.abs(detval)
|
|
462
|
+
phase = np.angle(detval)
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
### Image Reconstruction
|
|
466
|
+
|
|
467
|
+
```python
|
|
468
|
+
# Generate synthetic measurement
|
|
469
|
+
detphi0, _ = rb.run(cfg0) # Heterogeneous ground truth
|
|
470
|
+
|
|
471
|
+
# Setup reconstruction
|
|
472
|
+
recon = {
|
|
473
|
+
'prop': initial_prop,
|
|
474
|
+
'lambda': 0.1,
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
# Run reconstruction
|
|
478
|
+
newrecon, resid, newcfg = rb.run(cfg, recon, detphi0,
|
|
479
|
+
lambda_=1e-4, maxiter=10)
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
### Dual-Mesh Reconstruction
|
|
483
|
+
|
|
484
|
+
```python
|
|
485
|
+
import iso2mesh as i2m
|
|
486
|
+
|
|
487
|
+
# Fine forward mesh
|
|
488
|
+
cfg, sd = rb.meshprep(cfg)
|
|
489
|
+
|
|
490
|
+
# Coarse reconstruction mesh
|
|
491
|
+
recon = {}
|
|
492
|
+
recon['node'], _, recon['elem'] = i2m.meshabox([0,0,0], [60,60,30], 15)
|
|
493
|
+
recon['mapid'], recon['mapweight'] = i2m.tsearchn(
|
|
494
|
+
recon['node'], recon['elem'], cfg['node']
|
|
495
|
+
)
|
|
496
|
+
recon['prop'] = np.tile(cfg['prop'][1,:], (recon['node'].shape[0], 1))
|
|
497
|
+
|
|
498
|
+
newrecon, resid = rb.run(cfg, recon, detphi0, lambda_=1e-4)[:2]
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
### Wide-Field Reconstruction
|
|
502
|
+
|
|
503
|
+
```python
|
|
504
|
+
# Create illumination patterns
|
|
505
|
+
srcpattern = np.zeros((16, 16, 32))
|
|
506
|
+
# ... define patterns ...
|
|
507
|
+
|
|
508
|
+
cfg = {
|
|
509
|
+
# ... mesh ...
|
|
510
|
+
'srctype': 'pattern',
|
|
511
|
+
'srcpos': np.array([[10, 10, 0]]),
|
|
512
|
+
'srcparam1': [100, 0, 0, 0],
|
|
513
|
+
'srcparam2': [0, 40, 0, 0],
|
|
514
|
+
'srcdir': np.array([[0, 0, 1]]),
|
|
515
|
+
'srcpattern': srcpattern,
|
|
516
|
+
'dettype': 'pattern',
|
|
517
|
+
'detpattern': srcpattern,
|
|
518
|
+
# ...
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
cfg, sd = rb.meshprep(cfg)
|
|
522
|
+
detval, phi = rb.run(cfg)
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
---
|
|
526
|
+
|
|
527
|
+
## Units
|
|
528
|
+
|
|
529
|
+
| Quantity | Unit |
|
|
530
|
+
|----------|------|
|
|
531
|
+
| Length | millimeters (mm) |
|
|
532
|
+
| Absorption coefficient (μa) | 1/mm |
|
|
533
|
+
| Scattering coefficient (μs') | 1/mm |
|
|
534
|
+
| Hemoglobin concentration | micromolar (μM) |
|
|
535
|
+
| Water/lipid content | volume fraction (0-1) |
|
|
536
|
+
| Frequency | Hz (converted to rad/s internally) |
|
|
537
|
+
| Fluence | 1/mm² |
|
|
538
|
+
|
|
539
|
+
---
|
|
540
|
+
|
|
541
|
+
## Running Tests
|
|
542
|
+
|
|
543
|
+
```bash
|
|
544
|
+
# Run all tests
|
|
545
|
+
python -m unittest discover -v -s test
|
|
546
|
+
|
|
547
|
+
# Run specific test module
|
|
548
|
+
python -m unittest test.test_forward -v
|
|
549
|
+
|
|
550
|
+
# Run with pytest (if installed)
|
|
551
|
+
pytest test/ -v
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
---
|
|
555
|
+
|
|
556
|
+
## How to Cite
|
|
557
|
+
|
|
558
|
+
If you use Redbird in your research, please cite:
|
|
559
|
+
|
|
560
|
+
**Software workflow:**
|
|
561
|
+
> Fang Q, et al., "A multi-modality image reconstruction platform for diffuse optical tomography," in Biomed. Opt., BMD24 (2008). https://doi.org/10.1364/BIOMED.2008.BMD24
|
|
562
|
+
|
|
563
|
+
**Validation and methodology:**
|
|
564
|
+
> Fang Q, Carp SA, Selb J, et al., "Combined optical Imaging and mammography of the healthy breast: optical contrast derives from breast structure and compression," IEEE Trans. Medical Imaging, vol. 28, issue 1, pp. 30–42, Jan. 2009.
|
|
565
|
+
|
|
566
|
+
**Compositional priors:**
|
|
567
|
+
> Fang Q, Moore RH, Kopans DB, Boas DA, "Compositional-prior-guided image reconstruction algorithm for multi-modality imaging," Biomedical Optics Express, vol. 1, issue 1, pp. 223-235, 2010.
|
|
568
|
+
|
|
569
|
+
**Multi-spectral reconstruction:**
|
|
570
|
+
> Fang Q, Meaney PM, Paulsen KD, "Microwave image reconstruction of tissue property dispersion characteristics utilizing multiple frequency information," IEEE Trans. Microwave Theory and Techniques, vol. 52, No. 8, pp. 1866-1875, Aug. 2004.
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
## References
|
|
575
|
+
|
|
576
|
+
1. Fang Q, "Computational methods for microwave medical imaging," Ph.D. dissertation, Dartmouth College, 2004.
|
|
577
|
+
|
|
578
|
+
2. Arridge SR, "Optical tomography in medical imaging," Inverse Problems 15(2):R41-R93 (1999).
|
|
579
|
+
|
|
580
|
+
3. Prahl S, "Optical Absorption of Hemoglobin," https://omlc.org/spectra/hemoglobin/
|
|
581
|
+
|
|
582
|
+
4. Haskell RC, et al., "Boundary conditions for the diffusion equation in radiative transfer," JOSA A 11(10):2727-2741 (1994).
|
|
583
|
+
|
|
584
|
+
---
|
|
585
|
+
|
|
586
|
+
## License
|
|
587
|
+
|
|
588
|
+
GNU General Public License v3.0 or later - see [LICENSE](LICENSE) file for details.
|
|
589
|
+
|
|
590
|
+
## Author
|
|
591
|
+
|
|
592
|
+
**Qianqian Fang** (q.fang@neu.edu)
|
|
593
|
+
Computational Optics & Translational Imaging Lab
|
|
594
|
+
Northeastern University
|
|
595
|
+
|
|
596
|
+
Python translation based on the [Redbird MATLAB toolbox](https://github.com/fangq/redbirdpy).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
redbirdpy/__init__.py,sha256=I0dQ6LYcRWSL0Z525n52VE2BLEDQeTOQqM_EUwilgxk,3379
|
|
2
|
+
redbirdpy/analytical.py,sha256=9mMTU8EwDbRn5JqPsFgSdh0LL4WXc4BaXQpsECl_Wg4,26681
|
|
3
|
+
redbirdpy/forward.py,sha256=Gtu7v41h_AVMQ5sfyMSDkOIzzYTP2vn0SoxUQDR_lS8,18785
|
|
4
|
+
redbirdpy/property.py,sha256=fb8tOc7TLS7h6GQ61GjAbEwawJb5kLFULFm6-4U3MT0,18804
|
|
5
|
+
redbirdpy/recon.py,sha256=tnsVIYc6dMB5p9iWXLdOtdMnAe_YLHruci9g-WmvvS8,30290
|
|
6
|
+
redbirdpy/solver.py,sha256=mhhbyxxZATm8v_lVRCsYnwug4fsVyOU2ym665jmFO2E,26049
|
|
7
|
+
redbirdpy/utility.py,sha256=F8JYSUex0zWPds-f1lerdcPRT3bvGEPVw2CinDvFzu0,35360
|
|
8
|
+
redbirdpy-0.1.0.dist-info/licenses/LICENSE.txt,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
|
|
9
|
+
redbirdpy-0.1.0.dist-info/METADATA,sha256=1FeYa9cvr6KwvOK-_nr9yfblMydktDCLQuv1mQDvAW8,19510
|
|
10
|
+
redbirdpy-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
11
|
+
redbirdpy-0.1.0.dist-info/top_level.txt,sha256=BbzExHReBzfre6x0TePxSeA7BZK4skcjnnTkHOTDoyA,10
|
|
12
|
+
redbirdpy-0.1.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
13
|
+
redbirdpy-0.1.0.dist-info/RECORD,,
|