You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This python package is an object-oriented implementation of Monte Carlo modeling for light transport in diffuse media.
10
-
The package is very **easy to set up and use**, and its mesh-based approach makes it a **polyvalent** tool to simulate light transport in arbitrarily complex scenes.
11
-
The package offers both a native Python implementation and a hardware-accelerated version using OpenCL.
7
+
This python package is a fast and flexible implementation of Monte Carlo modeling for light transport in diffuse media.
8
+
The package is **easy to set up and use**, and its mesh-based approach makes it a polyvalent tool to simulate
9
+
light transport in **arbitrarily complex scenes**. The package offers both a native Python implementation
10
+
and a **hardware-accelerated** version using OpenCL which supports most GPUs and CPUs.
12
11
13
-
As discussed in the [why use this package](#why-use-this-package) section, computation time isn't the only variable at play. This code is **easy to understand**, **easily scalable**and **very simple to modify** for your need. It was designed with **research and education** in mind.
12
+
Designed with **research and education** in mind, the code aims to be clear, modular, and easy to extend for a wide range of applications.
14
13
15
14
## Notable features
16
-
- Arbitrarily complex 3D environments.
17
-
- Import external 3D models (.OBJ).
18
-
- Great data visualization with `Mayavi`.
19
-
- Multi-layered tissues.
20
-
- Hardware acceleration with `OpenCL`.
21
-
- Accurate Fresnel reflection and refraction with surface smoothing.
22
-
- Discard 3D data (auto-binning to 2D views).
23
-
- Independent 3D graphics framework under `scene`.
24
-
25
-
## Table of Contents
26
-
-[Installation](#installation)
27
-
-[Getting Started](#getting-started)
28
-
-[Hardware Acceleration](#hardware-acceleration)
29
-
-[Why Use This Package](#why-use-this-package)
30
-
-[Examples](#examples)
15
+
- Supports arbitrarily complex **mesh-based** 3D environments.
16
+
-**Normal smoothing** for accurate modeling of curved surfaces like lenses.
17
+
- Per-photon data points of deposited energy, fluence rate and intersection events.
18
+
-**Hardware accelerated** with `OpenCL` using [PyOpenCL](https://github.com/inducer/pyopencl).
19
+
- Photon traces & detectors.
20
+
- Import **external 3D models** (`.OBJ`).
21
+
- Many 3D visualization options built with [Mayavi](https://github.com/enthought/mayavi).
22
+
- Low memory mode with auto-binning to 2D views.
23
+
-**Reusable graphics framework** to kickstart other raytracing projects like [SensorSim](https://github.com/JLBegin/SensorSim).
31
24
32
25
## Installation
33
-
Requires Python >=3.9 installed on the device.
34
-
35
-
### Installing the latest release
36
-
> Currently, this `pip` version is outdated. We recommend installing the development version.
37
-
```shell
38
-
python -m pip install --upgrade pip
39
-
python -m pip install --upgrade pytissueoptics
40
-
```
26
+
Requires Python 3.9+ installed.
41
27
42
-
### Installing the development version
28
+
> Currently, the `pip` version is outdated. We recommend installing the development version.
43
29
1. Clone the repository.
44
30
2. Create a virtual environment inside the repository with `python -m venv venv`.
5. Install the package requirements with `python -m pip install -e .[dev]`.
50
36
51
37
## Getting started
52
-
A command-line interface is available to help you run examples and tests.
53
-
```shell
54
-
python -m pytissueoptics --help
55
-
python -m pytissueoptics --list
56
-
python -m pytissueoptics --examples 1,2,3
57
-
python -m pytissueoptics --tests
58
-
```
59
38
60
-
To launch a simple simulation on your own, follow these steps.
61
-
1. Import the `pytissueoptics` module
62
-
2. Define the following objects:
63
-
-`scene`: a `ScatteringScene` object, which defines the scene and the optical properties of the media, or use a pre-defined scene from the `samples` module. The scene takes in a list of `Solid` as its argument. These `Solid` will have a `ScatteringMaterial` and a position. This is clear in the examples below.
64
-
-`source`: a `Source` object, which defines the source of photons.
65
-
-`logger`: an `EnergyLogger` object, which logs the simulation progress ('keep3D=False' can be set to auto-bin to 2D views).
66
-
3. Propagate the photons in your `scene` with `source.propagate`.
67
-
4. Define a `Viewer` object and display the results by calling the desired methods. It offers various visualizations of the experiment as well as a statistics report.
68
-
69
-
Here's what it might look like:
70
-
```python
71
-
from pytissueoptics import*
72
-
73
-
material = ScatteringMaterial(mu_s=3.0, mu_a=1.0, g=0.8, n=1.5)
Hardware acceleration can offer a speed increase factor around 1000x depending on the scene.
93
-
By default, the program will try to use hardware acceleration if possible, which will require OpenCL drivers for your hardware of choice.
94
-
NVIDIA and AMD GPU drivers should contain their corresponding OpenCL driver by default.
95
-
To force the use of the native Python implementation, set `useHardwareAcceleration=False` when creating a light `Source`.
96
-
97
-
Follow the instructions on screen to get setup properly for the first hardware accelerated execution which will offer
98
-
to run a benchmark test to determine the ideal number of work units for your hardware.
99
-
100
-
## Why use this package
101
-
It is known, as April 2022, Python is **the most used** language ([Tiobe index](https://www.tiobe.com/tiobe-index/)).
102
-
This is due to the ease of use, the gentle learning curve, and growing community and tools. There was a need for
103
-
such a package in Python, so that not only long hardened C/C++ programmers could use the power of Monte Carlo simulations.
104
-
It is fairly reasonable to imagine you could start a calculation in Python in a few minutes, run it overnight and get
105
-
an answer the next day after a few hours of calculations. It is also reasonable to think you could **modify** the code
106
-
yourself to suit your exact needs! (Do not attempt this in C). This is the solution that the CPU-based portion of this package
107
-
offers you. With the new OpenCL implementation, speed is not an issue anymore, so using `pytissueoptics` should not even be a question.
108
-
109
-
### Known limitations
110
-
1. It uses Henyey-Greenstein approximation for scattering direction because it is sufficient most of the time.
111
-
2. Reflections are specular, which does not accounts for the roughness of materials. It is planned to implement Bling-Phong reflection model in a future release.
112
-
113
-
## Examples
114
44
115
-
### Multi-layered phantom tissue
116
-
Located at `pytissueoptics/examples/rayscattering/ex01.py`.
117
-
Using a pre-defined tissue from the `samples` module.
45
+
You can kick start your first simulation using one of our **pre-defined scene** under the `samples` module.
When the raw simulation data gets too large, the 3D data can be automatically binned to pre-defined 2D views.
84
+
#### Scene definition
85
+
Here is the explicit definition of the above scene sample. We recommend you look at other examples to get familiar with the API.
141
86
```python
142
-
logger = EnergyLogger(scene, keep3D=False)
143
-
```
144
-
All 2D views are unchanged, because they are included in the default 2D views tracked by the EnergyLogger.
145
-
The 1D profile and stats report are also properly computed from the stored 2D data.
146
-
The 3D display will auto-switch to Visibility.DEFAULT_2D which includes Visibility.VIEWS with ViewGroup.SCENE (XYZ projections of the whole scene) visible by default.
#### Display some 2D views with the 3D point cloud
150
-
The argument `viewsVisibility` can accept a `ViewGroup` tag like SCENE, SURFACES, etc., but also a list of indices for fine control. You can list all stored views with `logger.listViews()` or `viewer.listViews()`.
151
-
Here we toggle the visibility of 2D views along the default 3D visibility (which includes the point cloud).
If `keep3D=False`, the custom views (like slices, which are not included in the default views) have to be added to the logger before propagation like so:
If the logger keeps track of 3D data, then it's not a problem and the views can be added later with `logger.addView(customView)` or implicitly when asking for a 2D display from `viewer.show2D(customView)`.
Depending on your platform and GPU, you might already have OpenCL drivers installed, which should work out of the box.
103
+
Run a PyTissueOptics simulation first to see your current status.
104
+
105
+
> Follow the instructions on screen to get setup properly. It will offer to run a benchmark test to determine the ideal number of work units for your hardware.
106
+
For more help getting OpenCL to work, refer to [PyOpenCL's documentation](https://documen.tician.de/pyopencl/misc.html#enabling-access-to-cpus-and-gpus-via-py-opencl) on the matter. Note that you can disable hardware acceleration at any time with `disableOpenCL()` or by setting the environment variable `PTO_DISABLE_OPENCL=1`.
107
+
108
+
## Examples
109
+
110
+
All examples can be run using the CLI tool:
176
111
177
-
#### Save and append simulation results
178
-
The `EnergyLogger` data can be saved to file. This can also be used along with `keep3D=False` to only save 2D data. Every time the code is run, the previous data is loaded and extended. This is particularly useful to propagate a very large amount of photons (possibly infinite) in smaller batches so the hardware doesn't run out of memory.
1. It uses Henyey-Greenstein approximation for scattering direction because it is sufficient most of the time.
136
+
2. Reflections are specular, which does not account for the roughness of materials. A Bling-Phong reflection model could be added in a future release.
185
137
186
138
## Acknowledgment
139
+
187
140
This package was first inspired by the standard, tested, and loved [MCML from Wang, Jacques and Zheng](https://omlc.org/software/mc/mcpubs/1995LWCMPBMcml.pdf) , itself based on [Prahl](https://omlc.org/~prahl/pubs/abs/prahl89.html) and completely documented, explained, dissected by [Jacques](https://omlc.org/software/mc/) and [Prahl](https://omlc.org/~prahl/pubs/abs/prahl89.html). The original idea of using Monte Carlo for tissue optics calculations was [first proposed by Wilson and Adam in 1983](https://doi.org/10.1118/1.595361). This would not be possible without the work of these pioneers.
0 commit comments