Documentation and helper function

[JulesScholler]

This project is great and I fully grasp its potential. However, the status of the documentation and the multilayer OOP where object inherits from others makes it really hard to use.

For e.g. how can one get the energy or fluence as a numpy array to calculate custom metrics? Say I have a beam and want to know the local fluence at a given depth? It's great to have visualization functions, but it's hardly useful for any quantitative interpretation. I dived a bit in the code, but most of it is non-documented and there is no documentation to explain the overall philosophy of the library.

Thanks and keep up the good work!

[PyMarc2]

Hello @JulesScholler ! Thank you for the feedback, we appreciate it.
We are in a rather quiet period for the project, but @JLBegin has been working recently on making the package stable across platforms. Once we are done with this task, it is our desire to introduce more tools for quantitative analysis and other notable features such as optical axis, easier object positioning, etc. I agree that more documentation, specifically for quantitative analysis, is required.

It probably should not be accessed this way, but for now, one way you can access the data array is by using your Logger object after a simulation and asking for the data using PointCloudFactory object. The logger contains all the interaction data. This data was never binned because we wanted to have all the discrete information stored before proceeding to a potential binning, thus being more flexible.

    pointcloud = PointCloudFactory(logger)
    data = pointcloud.getPointCloudOfSolids()
    dataArray = data.solidPoints

The dataArray would here be an array of arrays. each array represent (absorbed energy weight, x, y, z), you could then use this data to get energy only in a certain region, or bin it yourself.

@JLBegin might have a better way of getting this info, he is more aware of this section of the code than I am.

[JLBegin]

Thanks for your interest in the project.

Regarding fluence data, there are no endpoints for that yet. You can access the raw data under Logger._data which includes the deposited energy points mentionned above as well as their interaction key. Each interaction key maps to the solid involved and includes the corresponding absorption coefficient mu_a. Using this, you can estimate the fluence in absorbing regions with A/mu_a.

Calculating robust fluence data in low absorbing regions via photon pathlengths is a high-priority feature that we will tackle next.