Commit 67ee9816 authored by torsten.hopp's avatar torsten.hopp
Browse files

Update README.md.

Grammatical issues and some restructuring until attenuationCalculationWrapper
parent 560e74b5
# RaytracingX-RayProjectionSimulator
Simulation for x-ray projection with raytracing<br/>
Usable for Matlab using mex-interface
The x-ray projection simulator offers hardware accelerated projections for triangle meshed surface data. It features the usage for Matlab via mex-interfaces.
The x-ray projection simulator offers hardware accelerated projections for triangle meshed surface data. It enables simulation of x-ray projections with a straight raytracing. The simulator can be embedded in Matlab via a mex-interfaces <br>
Please report bugs and requests for features in the gitlab issue tracker!
......@@ -19,39 +16,42 @@ e-mail: [torsten.hopp@kit.edu](mailto:torsten.hopp@kit.edu)
[[_TOC_]]
## Prerequisites
* MATLAB R2020b or later but may run on older MATLAB versions
* Vulkan SDK 1.2.131.2 was used for Implementation, not other tested yet
* NVIDIA GPU with raytracing features (tested on RTX 2070)
* For own mesh creation, in this work http://iso2mesh.sourceforge.net/cgi-bin/index.cgi was used
* Vulkan SDK 1.2.131.2 was used for implementation: Other Vulkan versions have not been tested.
* NVIDIA GPU with RT cores. Code was tested on a NVidia RTX 2070
## How to use it
Run buildscript before usage. Look at "How to build it"
Run buildscript before usage. Please see [How to build](howToBuild)
### nv_ray_tracing_basic
Mex-interface for kernel call.<br>
Use always the same order for variables.<br>
For proper attenuation look at attenuationCalculationWrapper.
`nv_ray_tracing_basic` performs the ray tracing from the source position through the triangular mesh to the detector pixels and returns the attenuation of the ray given the material parameters. This function represents the mex-interface for the kernel call.<br>
Please note the order of input/output variables below<br>
To transform the attenuation values according to the Beer-Lambert law, please see [attenuationCalculationWrapper](#attenuationCalculationWrapper).
MATLAB interface:
```matlab
[attenuationValues, profiling] = nv_ray_tracing_basic(detectorPositionCoordinates, faces, nodes, source, detectorSizeUint,attenuationCoefficentValues);
```
- Input:
- **detectorPositionCoordinates**: x,y,z coordinates of the detector as row vector. Format (n,3) where 1 = x, 2, = y, 3 = z and n diffrent detector positions<br/>
- **faces**: IDs of the vertices from triangle. IDs refer to nodes which have the proper coordinates. Both together create the surfaces. Faces also save the region. The region safes the material information. Format: (n,4)<br/>
- **nodes**: Coordinates for triangle vertices. Format (n,3) where 1 = x, 2, = y, 3 = z<br/>
- **source**: Coordinates of the source. Format: (1,3) where 1 = x, 2, = y, 3 = z<br/>
- **detectorSizeUint**: real size of detector. It defines the size of the outputpicture. Format (1,2) where 1 = numberOfPixelX, 1 = numberOfPixelY. Important: uint32 conversion<br/>
- **attenuationCoefficentValues**: Attenuation coefficents for region. The first value will be mapped to region 1 of faces, second value will be mapped with region 2. etc. Format (1,n) n >= number of regions (every attenuation coefficient above number of regions has no effect)<br/>
- **detectorPositionCoordinates**: (x,y,z) coordinates of the detector pixels as row vector. Format: (n,3) where the first column is x coordinate, second column is the y coordinate and third column is the z coordinate. n is the number of diffrent detector positions<br>
- **faces**: IDs of the nodes which form triangles. IDs refer to nodes which hold the proper coordinates. Both together create the surfaces. Faces additionally hold the "region" a triangle belongs to, e.g. the material type. Format: (n,4) where the first column is the first node ID of the triangle, the second columen is the second ID of the triangle and the third columen is the third ID of the column. The fourth column holds a numerical identifier of the corresponding region.<br>
- **nodes**: Coordinates of triangle nodes. Format: (n,3) where the first column is x coordinate, second column is the y coordinate and third column is the z coordinate.<br>
- **source**: Coordinates of the X-ray source position. Format: (1,3) where the first column is x coordinate, second column is the y coordinate and third column is the z coordinate<br>
- **detectorSizeUint**: size of the detector in pixels. It thereby defines the size of the output image. Format (1,2) where the first column is the number of pixels in first direction and the second columen is the number of pixels in the second direction. Important: requires uint32 conversion!<br>
- **attenuationCoefficentValues**: Attenuation coefficents for regions. The first value will be mapped to region 1 of faces, second value will be mapped with region 2. etc. Format: (1,n) where n needs to be at least the number of regions contained in the faces structure (every attenuation coefficient above the number of regions in faces has no effect)<br/>
- Output:
- **attenuationValues**: the result in format of detectorSizeUint(1)*detectorSizeUint(2). Wrapper will reformat to picture. See: attenuationCalculationWrapper<br/>
- **profiling**: internal time measurement. It's not necessary for calculation but it does not effect the calculation time much, espacially for big problems.<br/>
- **attenuationValues**: the attenuation of the X-rays in format `detectorSizeUint(1)*detectorSizeUint(2)`. <br>
- **profiling**: Output of internal time profiling. It's not necessary for calculation but it does not effect the calculation time much, espacially for big problems.<br/>
//debug
//debugMiss would be possible
If you don't know how to get the needed values, have a look at the easyExample script.
Please refer to the easyExample script for explanation of usage of the profiling output.
### attenuationCalculationWrapper
### <a name="attenuationCalculationWrapper"></a>attenuationCalculationWrapper
Should be called for proper Beer-Lambert-calculation, because kernel does not execute exponantiell function, because it just offers single precision.
```matlab
[attenuationValues, attenuationPicture] = attenuationCalculationWrapper (detectorPositionCoordinates, faces, nodes, source, detectorSizeUint,attenuationCoefficentValues, photons)
......@@ -81,7 +81,7 @@ easyExample("easy",1)
- Output: figure with projection pops up <br/>
## How to build it
## <a name="howToBuild">How to build it
### raytracingBuilder
Build for raytracing functions and shader. If vulkan is installed and the files has same relativ position as the repo, the build works by itself and raytracingBuilderWrapper can be used.
```matlab
......@@ -139,6 +139,8 @@ Output: plots all inputs in one figure. One plot with detector, mesh, source
## Mesh structure
* For own mesh creation, in this work http://iso2mesh.sourceforge.net/cgi-bin/index.cgi was used.
Currently the result is depending on the mesh structures. Meshes can be build diffrently. In our case we used the vol2mesh method from http://iso2mesh.sourceforge.net/cgi-bin/index.cgi to create the meshes. The result has two layers between region transitions, which means two triangles on the exact same positions. That is show in the picture with the red and inner black lines, which representing each a diffrent region. Then the ray always travels in and out of an material before it reachs the next on or an detector.
![Correct mesh structure. The inner mesh structures are double layered](./Data/Images/MeshStructure.svg)<br>
In other words, the current algorithm always expects to leave a region after entering it and before entering the next one. As you can see that has effects on the number of hits. Normally we would expect 4 hit because of 2 diffrent regions. But with these double layers we get 6 hits. This is a property the mesh needs for correct calculation.<br>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment