diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 57bcfb7..4fd23e7 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -43,7 +43,7 @@ jobs: run: | mkdir build cd build - cmake .. -DAARE_SYSTEM_LIBRARIES=ON -DAARE_DOCS=ON + cmake .. -DAARE_SYSTEM_LIBRARIES=ON -DAARE_PYTHON_BINDINGS=ON -DAARE_DOCS=ON make -j 2 make docs diff --git a/docs/src/ClusterFile.rst b/docs/src/ClusterFile.rst index 79de086..a2ee162 100644 --- a/docs/src/ClusterFile.rst +++ b/docs/src/ClusterFile.rst @@ -4,4 +4,5 @@ ClusterFile .. doxygenclass:: aare::ClusterFile :members: :undoc-members: - :private-members: \ No newline at end of file + :private-members: + diff --git a/docs/src/pyClusterFile.rst b/docs/src/pyClusterFile.rst index bdf898c..cd391e0 100644 --- a/docs/src/pyClusterFile.rst +++ b/docs/src/pyClusterFile.rst @@ -2,9 +2,24 @@ ClusterFile ============ + +The :class:`ClusterFile` class is the main interface to read and write clusters in aare. Unfortunately the +old file format does not include metadata like the cluster size and the data type. This means that the +user has to know this information from other sources. Specifying the wrong cluster size or data type +will lead to garbage data being read. + .. py:currentmodule:: aare .. autoclass:: ClusterFile + :members: + :undoc-members: + :inherited-members: + + +Below is the API of the ClusterFile_Cluster3x3i but all variants share the same API. + +.. autoclass:: aare._aare.ClusterFile_Cluster3x3i + :special-members: __init__ :members: :undoc-members: :show-inheritance: diff --git a/docs/src/pyClusterVector.rst b/docs/src/pyClusterVector.rst index 4277920..ff115c9 100644 --- a/docs/src/pyClusterVector.rst +++ b/docs/src/pyClusterVector.rst @@ -2,8 +2,10 @@ ClusterVector ================ The ClusterVector, holds clusters from the ClusterFinder. Since it is templated -in C++ we use a suffix indicating the data type in python. The suffix is -``_i`` for integer, ``_f`` for float, and ``_d`` for double. +in C++ we use a suffix indicating the type of cluster it holds. The suffix follows +the same pattern as for ClusterFile i.e. ``ClusterVector_Cluster3x3i`` +for a vector holding 3x3 integer clusters. + At the moment the functionality from python is limited and it is not supported to push_back clusters to the vector. The intended use case is to pass it to @@ -26,7 +28,8 @@ C++ functions that support the ClusterVector or to view it as a numpy array. .. py:currentmodule:: aare -.. autoclass:: ClusterVector_i +.. autoclass:: aare._aare.ClusterVector_Cluster3x3i + :special-members: __init__ :members: :undoc-members: :show-inheritance: diff --git a/etc/dev-env.yml b/etc/dev-env.yml index e580c81..4e4d08f 100644 --- a/etc/dev-env.yml +++ b/etc/dev-env.yml @@ -10,4 +10,5 @@ dependencies: - sphinx_rtd_theme - furo - zeromq + - pybind11 diff --git a/python/aare/ClusterFinder.py b/python/aare/ClusterFinder.py index 5509e51..251d938 100644 --- a/python/aare/ClusterFinder.py +++ b/python/aare/ClusterFinder.py @@ -70,6 +70,17 @@ def ClusterFile(fname, cluster_size=(3,3), dtype=np.int32, chunk_size = 1000): """ Factory function to create a ClusterFile object. Provides a cleaner syntax for the templated ClusterFile in C++. + + .. code-block:: python + + from aare import ClusterFile + + with ClusterFile("clusters.clust", cluster_size=(3,3), dtype=np.int32) as cf: + # cf is now a ClusterFile_Cluster3x3i object but you don't need to know that. + for clusters in cf: + # Loop over clusters in chunks of 1000 + # The type of clusters will be a ClusterVector_Cluster3x3i in this case + """ cls = _get_class("ClusterFile", cluster_size, dtype) diff --git a/python/src/bind_ClusterFile.hpp b/python/src/bind_ClusterFile.hpp index c2c801d..5d8aa88 100644 --- a/python/src/bind_ClusterFile.hpp +++ b/python/src/bind_ClusterFile.hpp @@ -38,19 +38,20 @@ void define_ClusterFile(py::module &m, const std::string &typestr) { self.read_clusters(n_clusters)); return v; }, - py::return_value_policy::take_ownership) + py::return_value_policy::take_ownership, py::arg("n_clusters")) .def("read_frame", [](ClusterFile &self) { auto v = new ClusterVector(self.read_frame()); return v; }) - .def("set_roi", &ClusterFile::set_roi) + .def("set_roi", &ClusterFile::set_roi, + py::arg("roi")) .def( "set_noise_map", [](ClusterFile &self, py::array_t noise_map) { auto view = make_view_2d(noise_map); self.set_noise_map(view); - }) + }, py::arg("noise_map")) .def("set_gain_map", [](ClusterFile &self, py::array_t gain_map) {