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.

Please report bugs and requests for features in the gitlab issue tracker!

Written by J. Maul

Maintained by J. Maul & T. Hopp

Institute for Data Processing and Electronics (IPE)

-**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/>

- 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/>

//debug

//debugMiss would be possible

If you don't know how to get the needed values, have a look at the easyExample script.

### attenuationCalculationWrapper

Should be called for proper Beer-Lambert-calculation, because kernel does not execute exponantiell function, because it just offers single precision.

-**detectorPositionCoordinates**: equal to kernel nv_ray_tracing_basic<br/>

-**faces**: equal to kernel nv_ray_tracing_basic<br/>

-**nodes**: equal to kernel nv_ray_tracing_basic<br/>

-**source**: equal to kernel nv_ray_tracing_basic<br/>

-**detectorSizeUint**: equal to kernel nv_ray_tracing_basic<br/>

-**attenuationCoefficentValues**: equal to kernel nv_ray_tracing_basic<br/>

-**photons**: initial photon number. Photon = 1 => result = attenuation value Photon != 1 => result = x-ray strength on detector<br/>

- Output:

-**attenuationValues**: equal to kernel<br/>

-**attenuationPicture**: attenuation values in format of picutre. Picture has the same size as defined with detectorSizeUint<br/>

### easyExample

Small example with projection image as result. It shows the process from voxel data to image.

```matlab

easyExample("easy",1)

```

- Input:

-**exampleType**: string which example should be shown. "test", "easy", "real"<br/>

-**buildDefault**: is a build needed before? 0 = no build, 1 = build with default settings, see raytracingBuilderWrapper.<br/>

- Output: figure with projection pops up <br/>

## 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

raytracingBuilder("","","","","",1)

```

If you call the builder like shown, you can also use raytracingBuilderWrapper, which doesn't need inputs, because of default usage.

- Input:

-**cSourceFilesPath**: new c source file path <br/>

-**cHeadersFilesPath**: new c header file path<br/>

-**vulkanIncludePath**: new vulkan include file path <br/>

-**VulkanLibPath**: new vulkan lib file path <br/>

-**shaderBuildPath**: new shader file path <br/>

-**buildShader**: bool if shader should also compiled. 0 = no shader build, 1 = build shader <br/>

- Output: generated files in the expected folder <br/>

### raytracingBuilderWrapper

Starts raytracingBuilder with default settings. If vulkan is installed and the files has same relativ position, the build works from alone, else use raytracingBuilder and set parameters manually.

```matlab

raytracingBuilderWrapper()

```

- Input: none <br/>

- Output: generated files in the expected folder (equal to raytracingBuilder) <br/>

## Helper Functions

### reformatProfile

Reformats profile data from nv_ray_tracing_basic output and labels the time for better association

-**profile**: profiling output from nv_ray_tracing_basic <br/>

- Output:

-**times**: labeled times in a 2xn array <br/>

### printAll

Helper function to visualize and proof mesh, detector and source position and all or a certain ray

```matlab

printAll(nodes,faces,source,detectors,14327)

```

-Input:

-**nodes**: equal to kernel nv_ray_tracing_basic<br/>

-**faces**: equal to kernel nv_ray_tracing_basic<br/>

-**source**: equal to kernel nv_ray_tracing_basic<br/>

-**detectors**: equal to kernel nv_ray_tracing_basic<br/>

-**detectorId**: id of a ray (from source to detectorId) if 0 or non value it plots every ray, to show the how the mesh gets hit by the rays. Id stands for linear index of detector.<br/>

Output: plots all inputs in one figure. One plot with detector, mesh, source and ray pops up