RadFiled3D 1.0.2__tar.gz

RadFiled3D-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Felix Lehner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

RadFiled3D-1.0.2/MANIFEST.in

@@ -0,0 +1 @@
+graft RadFiled3D

RadFiled3D-1.0.2/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.1
+Name: RadFiled3D
+Version: 1.0.2
+Summary: # RadFiled3D
+Author: Felix Lehner
+Author-email: felix.lehner@ptb.de
+License: MIT License
+        
+        Copyright (c) 2024 Felix Lehner
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+License-File: LICENSE

RadFiled3D-1.0.2/README.md

@@ -0,0 +1,134 @@
+# RadFiled3D
+This Repository holds the Fileformat and API according to the Paper: "RadField3D: A Data Generator and Data Format for Deep Learning in Radiation-Protection Dosimetry for Medical Applications".
+
+The aim of this library is, to provide a simple to use API for a structured, binary file format, that can store all relevant information from a three dimensional radiation field calculated by applications that use algorithms like Monte-Carlo radiation transport simulations. Such a binary file format is useful, when one needs to process a huge amount of radiation field files like when training a neural network. With that use-case in mind, RadFiled3D also provides a python interface with a pyTorch integration.
+
+## Building and Installing
+You can build and install this library and python module from source by using CMake and a C++ compiler. The CMake Project will be 
+built automatically, but will take some time.
+
+### Prerequisites
+- C++ Compiler
+  - g++ or clang for Linux
+  - MSVC or clang from Visual Studio 2022 for Windows
+- CMake >= 3.30
+- Python >= 3.11
+
+### CMake
+In order to use the module directly from another C++ Project, you can integrate it by adding the local location of this repository via `add_submodule()` and then link against the target `libRadFiled3D`. All classes are then available from the namespace `RadFiled3D`. Check the [Example](./examples/cxx/example01.cpp) or the [First Test File](./tests/basic.cpp) as a first reference.
+
+### Python
+In order to use the Module from Python, we provide a setup.py file that handles the compilation and integration automatically from the python setuptools.
+#### Installing locally
+`python -m pip install .`
+
+#### Building a wheel
+`python -m build --wheel`
+
+## Getting Started
+## From C++
+
+Simple example on how to create and store a radiation field. Find more in the example file: [Example](./examples/cxx/example01.cpp)
+```c++
+#include <RadFiled3D/storage/RadiationFieldStore.hpp>
+#include <RadFiled3D/RadiationField.hpp>
+
+using namespace RadFiled3D;
+using namespace RadFiled3D::Storage;
+
+void main() {
+    auto field = std::make_shared<CartesianRadiationField>(glm::vec3(2.5f), glm::vec3(0.05f)); // field extents: 2.5 m x 2.5 m x 2.5 m and voxel extents: 5 cm x 5 cm x 5 cm
+
+    auto metadata = std::make_shared<RadFiled3D::Storage::V1::RadiationFieldMetadata>(
+        // learn about the existing data fields from the example file in ./examples/cxx/examples01.cpp
+    )
+
+    FieldStore::store(field, metadata, "test_field.rf3", StoreVersion::V1);
+
+    auto field2 = FieldStore::load("test_field.rf3");
+}
+```
+
+## From Python
+Simple example on how to create and store a radiation field. Find more in the example file: [Example](./examples/python/example01.py)
+```python
+from RadFiled3D.RadFiled3D import CartesianRadiationField, FieldStore, StoreVersion, DType
+
+# Creating a cartesian radiation field
+field = CartesianRadiationField(vec3(2.5, 2.5, 2.5), vec3(0.05, 0.05, 0.05))
+# defining a channel and a layer on it
+field.get_channel("channel1").add_layer("layer1", "unit1", DType.FLOAT32)
+
+# accessing the voxels by using numpy arrays
+array = field.get_channel("channel1").get_layer_as_ndarray("layer1")
+assert array.shape == (50, 50, 50)
+# modify voxels content by using numpy array as no data is copied, just referenced
+array[2:5, 2:5, 2:5] = 2.0
+
+# addressing a voxel by providing a point in space
+voxel = field.get_channel("channel1").get_voxel_by_coord("layer1", 0.1, 2.4, 5)
+
+# Store changes to a file
+metadata = RadiationFieldMetadataV1(...)
+FieldStore.store(field, metadata, "test01.rf3", StoreVersion.V1)
+
+# load data
+field2 = FieldStore.load("test01.rf3")
+metadata2 = FieldStore.load_metadata("test01.rf3")
+```
+
+### Integrating with pyTorch
+RadFiled3D comes with a submodule at `RadFiled3D.pytorch`. This module provides some dataset classes to support the usage. Datasets can be loaded from folders or .zip-Files.
+```python
+from RadFiled3D.pytorch import MetadataLoadMode, CartesianFieldSingleLayerDataset, DatasetBuilder
+from RadFiled3D.pytorch.helpers import load_tensor_from_layer
+from RadFiled3D.RadFiled3D import VoxelGrid
+from torch import Tensor
+
+
+# Extend one of the provided dataset classes to match the output to the current needs
+# The argument type of 'field' may vary depending on the dataset type between RadiationField (Whole field), VoxelGridBuffer (Channel), VoxelGrid (Layer) and Voxel (Single Voxel)
+class MyLayerDataset(CartesianFieldSingleLayerDataset):
+    def transform_field(self, field: VoxelGrid) -> Tensor:
+        return load_tensor_from_layer(field)
+
+
+# Pass the dataset class and other options to the DatasetBuilder
+builder = DatasetBuilder(
+    "./test_dataset.zip",
+    train_ratio=0.7,
+    val_ratio=0.15,
+    test_ratio=0.15,
+    dataset_class=MyLayerDataset
+)
+# Build and finalize the training dataset
+train_ds = builder.build_train_dataset()
+# define the channel and layer to load from each field and spare out all other data
+train_ds.set_channel_and_layer("test_channel", "test_layer")
+# Load the metadata header for each radiation field, but not the dynamic metadata to speed up the loading
+train_ds.metadata_load_mode = MetadataLoadMode.HEADER
+
+# iterate over the dataset
+for field, metadata in train_ds:
+    pass
+```
+
+### Field Structure
+RadFiled3D defines a field structure, that provides the user with the possibility to first define in which kind of space he wants to operate. Therefore one can choose between `CartesianRadiationField` and `PolarRadiationField`.
+- *CartesianRadiationField*: Segments a room defined by an extent of the room itself and each cuboid voxel into a set of voxels. Each voxel can be addressed by a 3D position (coordinate: x, y, z), a 3D index (number of the voxel in each dimension) or a flat 1D index.
+- *PolarRadiationField*: Segements the surface of a unit sphere into surface segments. Each segment (voxel) can be addressed by a 2D position (coordinate: theta, phi), a 2D index (number of the segment in each dimension) or a flat 1D index.
+
+Fields are then partitioned into channels (`VoxelGridBuffer`/`PolarSegmentsBuffer`). All channels share the same size and resolution. A channel is again partitioned into layers (`VoxelGrid`/`PolarSegment`). Each layer holds the actual voxel data and can be constructed from various data types (int, float, double, uint32_t, uint64_t, glm::vec2, glm::vec3, glm::vec4, N-D-Histogram). Additionally, a layer has a unit string assigned to it as well as a statistical uncertainty to perserve those information.
+
+## Dependencies
+RadFiled3D comes with a possibly low amount of dependencies. We integrated the OpenGL Math Library (GLM) just to provide those datatypes out of the box and as GLM is a head-only library we suspect no issues by doing so.
+
+All C++ dependencies:
+- [GLM](https://github.com/g-truc/glm)
+
+All python dependencies:
+- [PyBind11](https://github.com/pybind/pybind11)
+- [rich](https://github.com/Textualize/rich)
+- [numpy](https://numpy.org/)
+- Optional:
+  - [pyTorch](https://pytorch.org/)