pathtracer 0.3.0__tar.gz

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.
@@ -0,0 +1,8 @@
1
+ build/
2
+ __pycache__/
3
+ *.pyc
4
+ python/pathtracer/_core*.so
5
+ python/pathtracer/_core*.pyd
6
+ *.egg-info/
7
+ dist/
8
+ .DS_Store
@@ -0,0 +1,45 @@
1
+ cmake_minimum_required(VERSION 3.25)
2
+
3
+ project(PathTracer
4
+ VERSION 0.1.0
5
+ DESCRIPTION "Light transport on trimmed NURBS geometry: light tracing, path tracing, bidirectional, photon mapping"
6
+ LANGUAGES CXX)
7
+
8
+ set(CMAKE_CXX_STANDARD 20)
9
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
10
+ set(CMAKE_CXX_EXTENSIONS OFF)
11
+ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
12
+ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
13
+ set(CMAKE_BUILD_TYPE Release)
14
+ endif()
15
+
16
+ option(PT_BUILD_PYTHON "Build the Python package pathtracer (module pathtracer._core)" ON)
17
+ option(PT_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
18
+
19
+ find_package(Threads REQUIRED)
20
+
21
+ add_library(pathtracer STATIC
22
+ src/core.cpp src/mesh.cpp src/bvh.cpp src/material.cpp src/photometry.cpp
23
+ src/scene.cpp src/sensor.cpp src/integrator.cpp src/photon.cpp)
24
+ add_library(PathTracer::pathtracer ALIAS pathtracer)
25
+ target_include_directories(pathtracer PUBLIC include PRIVATE src)
26
+ target_link_libraries(pathtracer PUBLIC Threads::Threads)
27
+ set_target_properties(pathtracer PROPERTIES POSITION_INDEPENDENT_CODE ON)
28
+ if(MSVC)
29
+ add_compile_options(/utf-8) # the sources are UTF-8 (messages with °, …)
30
+ target_compile_options(pathtracer PRIVATE /W4 $<$<BOOL:${PT_WARNINGS_AS_ERRORS}>:/WX>)
31
+ target_compile_definitions(pathtracer PRIVATE _CRT_SECURE_NO_WARNINGS)
32
+ else()
33
+ target_compile_options(pathtracer PRIVATE -Wall -Wextra $<$<BOOL:${PT_WARNINGS_AS_ERRORS}>:-Werror>)
34
+ endif()
35
+
36
+ if(PT_BUILD_PYTHON)
37
+ find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
38
+ find_package(pybind11 CONFIG REQUIRED)
39
+ pybind11_add_module(_core bindings/module.cpp)
40
+ target_link_libraries(_core PRIVATE pathtracer)
41
+ # next to the Python sources, so that the package runs from the source tree after a build
42
+ set_target_properties(_core PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/python/pathtracer"
43
+ LIBRARY_OUTPUT_DIRECTORY_RELEASE "${CMAKE_CURRENT_SOURCE_DIR}/python/pathtracer")
44
+ install(TARGETS _core LIBRARY DESTINATION pathtracer)
45
+ endif()
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 KF
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,119 @@
1
+ Metadata-Version: 2.4
2
+ Name: pathtracer
3
+ Version: 0.3.0
4
+ Summary: Light transport on trimmed NURBS geometry: light tracing, path tracing, bidirectional, photon mapping
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: numpy>=1.24
9
+ Description-Content-Type: text/markdown
10
+
11
+ # PathTracer
12
+
13
+ Light transport on trimmed NURBS geometry, in C++ with a Python package: **light tracing, path
14
+ tracing, bidirectional path tracing and photon mapping** as estimators of the same quantities –
15
+ the irradiance on faces (a texture per face) and the radiance seen by a camera.
16
+
17
+ It is the C++ twin of the NumPy kernel of the *Path Tracer* plugin of Raytatouille Fusion
18
+ (`python/plugins/pathtracer/pt_*.py` there): the same model and the same estimators, written one
19
+ path at a time instead of arrays of paths, and run on all processor cores. The plugin's guide
20
+ describes the model; this file describes the library.
21
+
22
+ ## What is in it
23
+
24
+ | Part | File | |
25
+ |---|---|---|
26
+ | NURBS | `src/core.cpp` | curves and surfaces of the `.nfcad` format, points and first derivatives |
27
+ | Mesh | `src/mesh.cpp` | every face tessellated in its surface parameters to a chordal tolerance; trimming as a mask over (u, v) tested at every hit; face and texel areas over the same mask; the exact surface normal where a ray meets a curved face (Newton) |
28
+ | BVH | `src/bvh.cpp`, header | surface area heuristic; nearest hit and any hit with a filter |
29
+ | Materials | `src/material.cpp` | absorber, diffuse (with transmission), mirror, glossy, glass, detector, metal and frosted (GGX); by wavelength: index (Abbe number), reflectance, absorption |
30
+ | Sources | `src/scene.cpp`, `src/photometry.cpp` | surfaces (cone or a measured distribution), points, curves (thin wires); line spectra; luminaire files (IES LM-63, EULUMDAT) |
31
+ | Scene | `src/scene.cpp` | closed bodies oriented by counting crossings; glass bodies that touch or lie inside one another |
32
+ | Sensors | `src/sensor.cpp` | textures on faces, pinhole and lens camera; shares of the samples per texel / pixel that adapt |
33
+ | Estimators | `src/integrator.cpp`, `src/photon.cpp` | subpaths, connections, multiple importance sampling; photon mapping; batches on threads, standard errors; the light that leaves the scene |
34
+ | Python | `bindings/module.cpp`, `python/pathtracer` | geometry as `.nfcad` dicts in, NumPy arrays out |
35
+
36
+ Lengths in mm, power in W: radiance in W/(mm² sr), irradiance = flux per texel / texel area.
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ pip install pathtracer # wheels for Linux x86_64, Windows AMD64, macOS arm64; CPython 3.10–3.13
42
+ ```
43
+
44
+ Releases: a tag `v<version>` (the version of `pyproject.toml` and `python/pathtracer/__init__.py`)
45
+ builds the wheels and the sdist (`.github/workflows/wheels.yml`) and attaches them to a GitHub
46
+ release; *Run workflow* on the tag with `pypi` ticked uploads them to PyPI (Trusted Publishing,
47
+ environment `pypi`).
48
+
49
+ ## Build
50
+
51
+ Needs a C++20 compiler, CMake ≥ 3.25, Python ≥ 3.10 with NumPy and pybind11.
52
+
53
+ ```bash
54
+ pip install . # the package pathtracer
55
+ # or, in the source tree (the module lands in python/pathtracer):
56
+ cmake -S . -B build -G Ninja -Dpybind11_DIR=$(python -m pybind11 --cmakedir)
57
+ cmake --build build
58
+ python tests/test_kernel.py
59
+ ```
60
+
61
+ ## Use
62
+
63
+ ```python
64
+ import pathtracer as pt
65
+
66
+ mesh = pt.build_mesh(entities, 0.01) # dicts {"id", "geometry"}: surface, trimmed_surface, shell
67
+ scene = pt.Scene(mesh,
68
+ [{"name": "white", "kind": "diffuse", "reflectance": 0.8},
69
+ {"name": "glass", "kind": "glass", "ior": 1.5}],
70
+ entity_material=[0, 1], # one material number per entity
71
+ sources=[{"name": "lamp", "flux": 1.0, "points": [(0, 0, 50)]}],
72
+ closed=[1]) # entities that are closed bodies
73
+ sensor = pt.TexelSensor(scene, faces=[0], long_side=64)
74
+ out = pt.render(scene, sensor, "bidir", samples=1_000_000, depth=8, seed=1)
75
+ flux = out["values"] # W per texel; out["error"]: its standard error
76
+ image = pt.render(scene, pt.Camera((300, -300, 200), (0, 0, 0), (0, 0, 1), 40, 320, 240), "path",
77
+ samples=2_000_000, depth=8)["values"].reshape(240, 320)
78
+ ```
79
+
80
+ `render(scene, sensor, method, samples, depth, seed=0, threads=0, radius=0, adaptive=False,
81
+ weights=None, batch=0, progress=None, cancelled=None)` – methods `light`, `path`, `bidir`,
82
+ `photon`; `threads` 0: all cores; the result is the same for any number of threads up to rounding.
83
+
84
+ `escapes(scene, n, depth, seed=0, index=0, threads=0, skip=[])` – the light that leaves the scene (a far
85
+ field, e.g. the luminous intensity of a luminaire): n light subpaths of up to `depth` segments;
86
+ for every one that leaves, its direction `d`, its `flux` (the fluxes of one call add up to the
87
+ escaping flux), its wavelength's `channel`, its number of surface events `bounces` (0: straight
88
+ from the source) and the entities of its `first` and `last` surface (-1: none) – `first` passes
89
+ over the entities in `skip` (the first surface that is not one of them: e.g. what the light of a
90
+ lamp meets after its bulb). Batches of one seed are independent by `index`; the result does not
91
+ depend on the number of threads.
92
+
93
+ ## Tests
94
+
95
+ `tests/test_kernel.py` (about 10 s): the closed forms and cross-checks of the plugin's test –
96
+ point source over a plane, closed diffuse box, glass plates (also absorbing, dispersing,
97
+ touching, immersed), detectors, wires, measured distributions, cameras with and without a lens,
98
+ photon mapping through glass, microfacet sampling against its evaluation, standard errors,
99
+ adaptive sampling, threads, cancel.
100
+
101
+ ## Licence and sources
102
+
103
+ MIT, see [LICENSE](LICENSE). No third-party code is included; the package is built with
104
+ [pybind11](https://github.com/pybind/pybind11) (BSD-3-Clause) and uses NumPy (BSD-3-Clause) at run
105
+ time. The methods follow the literature:
106
+
107
+ - B-spline basis functions: Piegl, Tiller, *The NURBS Book*, algorithm A2.2
108
+ - ray–triangle intersection: Möller, Trumbore (1997)
109
+ - path space, bidirectional path tracing, multiple importance sampling: Veach (1997)
110
+ - microfacet reflection and refraction through rough surfaces: Walter, Marschner, Li, Torrance (2007);
111
+ sampling the visible normals of GGX: Heitz (2018)
112
+ - progressive photon mapping with a shrinking radius: Knaus, Zwicker (2011)
113
+ - random numbers: xoshiro256++ and SplitMix64 (Blackman, Vigna; public domain)
114
+ - photopic luminous efficiency V(λ): CIE 1924
115
+ - luminaire files: IES LM-63 and EULUMDAT, read from their format descriptions
116
+
117
+ ## Not here (yet)
118
+
119
+ Sources and cameras inside glass; polarisation; coatings; volumes.
@@ -0,0 +1,109 @@
1
+ # PathTracer
2
+
3
+ Light transport on trimmed NURBS geometry, in C++ with a Python package: **light tracing, path
4
+ tracing, bidirectional path tracing and photon mapping** as estimators of the same quantities –
5
+ the irradiance on faces (a texture per face) and the radiance seen by a camera.
6
+
7
+ It is the C++ twin of the NumPy kernel of the *Path Tracer* plugin of Raytatouille Fusion
8
+ (`python/plugins/pathtracer/pt_*.py` there): the same model and the same estimators, written one
9
+ path at a time instead of arrays of paths, and run on all processor cores. The plugin's guide
10
+ describes the model; this file describes the library.
11
+
12
+ ## What is in it
13
+
14
+ | Part | File | |
15
+ |---|---|---|
16
+ | NURBS | `src/core.cpp` | curves and surfaces of the `.nfcad` format, points and first derivatives |
17
+ | Mesh | `src/mesh.cpp` | every face tessellated in its surface parameters to a chordal tolerance; trimming as a mask over (u, v) tested at every hit; face and texel areas over the same mask; the exact surface normal where a ray meets a curved face (Newton) |
18
+ | BVH | `src/bvh.cpp`, header | surface area heuristic; nearest hit and any hit with a filter |
19
+ | Materials | `src/material.cpp` | absorber, diffuse (with transmission), mirror, glossy, glass, detector, metal and frosted (GGX); by wavelength: index (Abbe number), reflectance, absorption |
20
+ | Sources | `src/scene.cpp`, `src/photometry.cpp` | surfaces (cone or a measured distribution), points, curves (thin wires); line spectra; luminaire files (IES LM-63, EULUMDAT) |
21
+ | Scene | `src/scene.cpp` | closed bodies oriented by counting crossings; glass bodies that touch or lie inside one another |
22
+ | Sensors | `src/sensor.cpp` | textures on faces, pinhole and lens camera; shares of the samples per texel / pixel that adapt |
23
+ | Estimators | `src/integrator.cpp`, `src/photon.cpp` | subpaths, connections, multiple importance sampling; photon mapping; batches on threads, standard errors; the light that leaves the scene |
24
+ | Python | `bindings/module.cpp`, `python/pathtracer` | geometry as `.nfcad` dicts in, NumPy arrays out |
25
+
26
+ Lengths in mm, power in W: radiance in W/(mm² sr), irradiance = flux per texel / texel area.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install pathtracer # wheels for Linux x86_64, Windows AMD64, macOS arm64; CPython 3.10–3.13
32
+ ```
33
+
34
+ Releases: a tag `v<version>` (the version of `pyproject.toml` and `python/pathtracer/__init__.py`)
35
+ builds the wheels and the sdist (`.github/workflows/wheels.yml`) and attaches them to a GitHub
36
+ release; *Run workflow* on the tag with `pypi` ticked uploads them to PyPI (Trusted Publishing,
37
+ environment `pypi`).
38
+
39
+ ## Build
40
+
41
+ Needs a C++20 compiler, CMake ≥ 3.25, Python ≥ 3.10 with NumPy and pybind11.
42
+
43
+ ```bash
44
+ pip install . # the package pathtracer
45
+ # or, in the source tree (the module lands in python/pathtracer):
46
+ cmake -S . -B build -G Ninja -Dpybind11_DIR=$(python -m pybind11 --cmakedir)
47
+ cmake --build build
48
+ python tests/test_kernel.py
49
+ ```
50
+
51
+ ## Use
52
+
53
+ ```python
54
+ import pathtracer as pt
55
+
56
+ mesh = pt.build_mesh(entities, 0.01) # dicts {"id", "geometry"}: surface, trimmed_surface, shell
57
+ scene = pt.Scene(mesh,
58
+ [{"name": "white", "kind": "diffuse", "reflectance": 0.8},
59
+ {"name": "glass", "kind": "glass", "ior": 1.5}],
60
+ entity_material=[0, 1], # one material number per entity
61
+ sources=[{"name": "lamp", "flux": 1.0, "points": [(0, 0, 50)]}],
62
+ closed=[1]) # entities that are closed bodies
63
+ sensor = pt.TexelSensor(scene, faces=[0], long_side=64)
64
+ out = pt.render(scene, sensor, "bidir", samples=1_000_000, depth=8, seed=1)
65
+ flux = out["values"] # W per texel; out["error"]: its standard error
66
+ image = pt.render(scene, pt.Camera((300, -300, 200), (0, 0, 0), (0, 0, 1), 40, 320, 240), "path",
67
+ samples=2_000_000, depth=8)["values"].reshape(240, 320)
68
+ ```
69
+
70
+ `render(scene, sensor, method, samples, depth, seed=0, threads=0, radius=0, adaptive=False,
71
+ weights=None, batch=0, progress=None, cancelled=None)` – methods `light`, `path`, `bidir`,
72
+ `photon`; `threads` 0: all cores; the result is the same for any number of threads up to rounding.
73
+
74
+ `escapes(scene, n, depth, seed=0, index=0, threads=0, skip=[])` – the light that leaves the scene (a far
75
+ field, e.g. the luminous intensity of a luminaire): n light subpaths of up to `depth` segments;
76
+ for every one that leaves, its direction `d`, its `flux` (the fluxes of one call add up to the
77
+ escaping flux), its wavelength's `channel`, its number of surface events `bounces` (0: straight
78
+ from the source) and the entities of its `first` and `last` surface (-1: none) – `first` passes
79
+ over the entities in `skip` (the first surface that is not one of them: e.g. what the light of a
80
+ lamp meets after its bulb). Batches of one seed are independent by `index`; the result does not
81
+ depend on the number of threads.
82
+
83
+ ## Tests
84
+
85
+ `tests/test_kernel.py` (about 10 s): the closed forms and cross-checks of the plugin's test –
86
+ point source over a plane, closed diffuse box, glass plates (also absorbing, dispersing,
87
+ touching, immersed), detectors, wires, measured distributions, cameras with and without a lens,
88
+ photon mapping through glass, microfacet sampling against its evaluation, standard errors,
89
+ adaptive sampling, threads, cancel.
90
+
91
+ ## Licence and sources
92
+
93
+ MIT, see [LICENSE](LICENSE). No third-party code is included; the package is built with
94
+ [pybind11](https://github.com/pybind/pybind11) (BSD-3-Clause) and uses NumPy (BSD-3-Clause) at run
95
+ time. The methods follow the literature:
96
+
97
+ - B-spline basis functions: Piegl, Tiller, *The NURBS Book*, algorithm A2.2
98
+ - ray–triangle intersection: Möller, Trumbore (1997)
99
+ - path space, bidirectional path tracing, multiple importance sampling: Veach (1997)
100
+ - microfacet reflection and refraction through rough surfaces: Walter, Marschner, Li, Torrance (2007);
101
+ sampling the visible normals of GGX: Heitz (2018)
102
+ - progressive photon mapping with a shrinking radius: Knaus, Zwicker (2011)
103
+ - random numbers: xoshiro256++ and SplitMix64 (Blackman, Vigna; public domain)
104
+ - photopic luminous efficiency V(λ): CIE 1924
105
+ - luminaire files: IES LM-63 and EULUMDAT, read from their format descriptions
106
+
107
+ ## Not here (yet)
108
+
109
+ Sources and cameras inside glass; polarisation; coatings; volumes.