diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index f4fb00f..b0c45ce 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -12,6 +12,8 @@ set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}) set(SPHINX_SOURCE_FILES src/index.rst + src/Installation.rst + src/Requirements.rst src/NDArray.rst src/NDView.rst src/File.rst @@ -26,6 +28,7 @@ set(SPHINX_SOURCE_FILES src/pyVarClusterFinder.rst src/pyFile.rst src/pyCtbRawFile.rst + src/pyRawFile.rst src/pyRawMasterFile.rst ) diff --git a/docs/src/Installation.rst b/docs/src/Installation.rst new file mode 100644 index 0000000..250310f --- /dev/null +++ b/docs/src/Installation.rst @@ -0,0 +1,101 @@ +Installation +=============== + +conda/mamaba +~~~~~~~~~~~~~~~~ + +.. note :: + + aare is developing rapidly. Check for the latest release by + using: **conda search aare -c slsdetectorgroup** + + +.. code-block:: bash + + # Install a specific version: + conda install aare=2024.11.11.dev0 -c slsdetectorgroup + + +cmake (development install) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + git clone git@github.com:slsdetectorgroup/aare.git --branch=v1 #or using http... + mkdir build + cd build + + #configure using cmake + cmake ../aare + + #build (replace 4 with the number of threads you want to use) + make -j4 + + + # add the build folder to your PYTHONPATH + +cmake install and use in your C++ project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + #build and install aare + git clone git@github.com:slsdetectorgroup/aare.git --branch=v1 #or using http... + mkdir build + cd build + + #configure using cmake + cmake ../aare -DCMAKE_INSTALL_PREFIX=/where/to/put/aare + + #build (replace 4 with the number of threads you want to use) + make -j4 + + #install + make install + + + #Now configure your project + cmake .. -DCMAKE_PREFIX_PATH=SOME_PATH + + +cmake options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For detailed options see the CMakeLists.txt file in the root directory of the project. + +.. code-block:: bash + + # usage (or edit with ccmake .) + cmake ../aare -DOPTION1=ON -DOPTION2=OFF + + +**AARE_SYSTEM_LIBRARIES "Use system libraries" OFF** + +Use system libraries instead of using FetchContent to pull in dependencies. Default option is off. + + +**AARE_PYTHON_BINDINGS "Build python bindings" ON** + +Build the Python bindings. Default option is on. + +.. warning :: + + If you have a newer system Python compared to the one in your virtual environment, + you might have to pass -DPython_FIND_VIRTUALENV=ONLY to cmake. + +**AARE_TESTS "Build tests" OFF** + +Build unit tests. Default option is off. + +**AARE_EXAMPLES "Build examples" OFF** + +**AARE_DOCS "Build documentation" OFF** + +Build documentation. Needs doxygen, sphinx and breathe. Default option is off. +Requires a separate make docs. + +**AARE_VERBOSE "Verbose output" OFF** + +**AARE_CUSTOM_ASSERT "Use custom assert" OFF** + +Enable custom assert macro to check for errors. Default option is off. \ No newline at end of file diff --git a/docs/src/Requirements.rst b/docs/src/Requirements.rst new file mode 100644 index 0000000..c962f73 --- /dev/null +++ b/docs/src/Requirements.rst @@ -0,0 +1,23 @@ +Requirements +============================================== + +- C++17 compiler (gcc 8/clang 7) +- CMake 3.14+ + +**Internally used libraries** + +.. note :: + + These can also be picked up from the system/conda environment by specifying: + -DAARE_SYSTEM_LIBRARIES=ON during the cmake configuration. + +- pybind11 +- fmt +- nlohmann_json +- ZeroMQ + +**Extra dependencies for building documentation** + +- Sphinx +- Breathe +- Doxygen \ No newline at end of file diff --git a/docs/src/index.rst b/docs/src/index.rst index 7bac72f..d34d5e3 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -5,12 +5,22 @@ AARE Hello + +.. toctree:: + :caption: Installation + :maxdepth: 1 + + Installation + Requirements + + .. toctree:: :caption: Python API :maxdepth: 1 pyFile pyCtbRawFile + pyRawFile pyRawMasterFile pyVarClusterFinder diff --git a/docs/src/pyRawFile.rst b/docs/src/pyRawFile.rst new file mode 100644 index 0000000..b81f413 --- /dev/null +++ b/docs/src/pyRawFile.rst @@ -0,0 +1,10 @@ +RawFile +=================== + +.. py:currentmodule:: aare + +.. autoclass:: RawFile + :members: + :undoc-members: + :show-inheritance: + :inherited-members: \ No newline at end of file diff --git a/python/src/raw_file.hpp b/python/src/raw_file.hpp index 3ddbe9b..73442a4 100644 --- a/python/src/raw_file.hpp +++ b/python/src/raw_file.hpp @@ -23,63 +23,67 @@ using namespace ::aare; void define_raw_file_io_bindings(py::module &m) { py::class_(m, "RawFile") .def(py::init()) - .def("read_frame", [](RawFile &self) { - size_t image_size = self.bytes_per_frame(); - py::array image; - std::vector shape; - shape.reserve(2); - shape.push_back(self.rows()); - shape.push_back(self.cols()); + .def("read_frame", + [](RawFile &self) { + size_t image_size = self.bytes_per_frame(); + py::array image; + std::vector shape; + shape.reserve(2); + shape.push_back(self.rows()); + shape.push_back(self.cols()); - // return headers from all subfiles - py::array_t header(self.n_mod()); + // return headers from all subfiles + py::array_t header(self.n_mod()); - const uint8_t item_size = self.bytes_per_pixel(); - if (item_size == 1) { - image = py::array_t(shape); - } else if (item_size == 2) { - image = py::array_t(shape); - } else if (item_size == 4) { - image = py::array_t(shape); - } - self.read_into(reinterpret_cast(image.mutable_data()), - header.mutable_data()); + const uint8_t item_size = self.bytes_per_pixel(); + if (item_size == 1) { + image = py::array_t(shape); + } else if (item_size == 2) { + image = py::array_t(shape); + } else if (item_size == 4) { + image = py::array_t(shape); + } + self.read_into( + reinterpret_cast(image.mutable_data()), + header.mutable_data()); - return py::make_tuple(header, image); - }) - .def("read_n", [](RawFile &self, size_t n_frames) { - py::array image; - std::vector shape; - shape.reserve(3); - shape.push_back(n_frames); - shape.push_back(self.rows()); - shape.push_back(self.cols()); - - // return headers from all subfiles - py::array_t header({self.n_mod(),n_frames}); + return py::make_tuple(header, image); + }) + .def("read_n", + [](RawFile &self, size_t n_frames) { + py::array image; + std::vector shape; + shape.reserve(3); + shape.push_back(n_frames); + shape.push_back(self.rows()); + shape.push_back(self.cols()); - const uint8_t item_size = self.bytes_per_pixel(); - if (item_size == 1) { - image = py::array_t(shape); - } else if (item_size == 2) { - image = py::array_t(shape); - } else if (item_size == 4) { - image = py::array_t(shape); - } - self.read_into(reinterpret_cast(image.mutable_data()),n_frames, - header.mutable_data()); + // return headers from all subfiles + py::array_t header({self.n_mod(), n_frames}); - return py::make_tuple(header, image); + const uint8_t item_size = self.bytes_per_pixel(); + if (item_size == 1) { + image = py::array_t(shape); + } else if (item_size == 2) { + image = py::array_t(shape); + } else if (item_size == 4) { + image = py::array_t(shape); + } + self.read_into( + reinterpret_cast(image.mutable_data()), + n_frames, header.mutable_data()); - }) + return py::make_tuple(header, image); + }) .def("frame_number", &RawFile::frame_number) .def_property_readonly("bytes_per_frame", &RawFile::bytes_per_frame) .def_property_readonly("pixels_per_frame", &RawFile::pixels_per_frame) .def_property_readonly("bytes_per_pixel", &RawFile::bytes_per_pixel) .def("seek", &RawFile::seek, R"( - Seek to a specific frame number. + Seek to a frame index in file. )") - .def("tell", &RawFile::tell) + .def("tell", &RawFile::tell, R"( + Return the current frame number.)") .def_property_readonly("total_frames", &RawFile::total_frames) .def_property_readonly("rows", &RawFile::rows) .def_property_readonly("cols", &RawFile::cols) @@ -88,6 +92,4 @@ void define_raw_file_io_bindings(py::module &m) { .def_property_readonly("n_mod", &RawFile::n_mod) .def_property_readonly("detector_type", &RawFile::detector_type) .def_property_readonly("master", &RawFile::master); - - } \ No newline at end of file diff --git a/python/src/raw_master_file.hpp b/python/src/raw_master_file.hpp index 1411c6a..943437f 100644 --- a/python/src/raw_master_file.hpp +++ b/python/src/raw_master_file.hpp @@ -22,9 +22,23 @@ namespace py = pybind11; using namespace ::aare; void define_raw_master_file_bindings(py::module &m) { -py::class_(m, "RawMasterFile") + py::class_(m, "RawMasterFile") .def(py::init()) - .def("data_fname", &RawMasterFile::data_fname) + .def("data_fname", &RawMasterFile::data_fname, R"( + + Parameters + ------------ + module_index : int + module index (d0, d1 .. dN) + file_index : int + file index (f0, f1 .. fN) + + Returns + ---------- + os.PathLike + The name of the data file. + + )") .def_property_readonly("version", &RawMasterFile::version) .def_property_readonly("detector_type", &RawMasterFile::detector_type) .def_property_readonly("timing_mode", &RawMasterFile::timing_mode) @@ -43,9 +57,23 @@ py::class_(m, "RawMasterFile") .def_property_readonly("total_frames_expected", &RawMasterFile::total_frames_expected) .def_property_readonly("geometry", &RawMasterFile::geometry) - .def_property_readonly("analog_samples", &RawMasterFile::analog_samples) + .def_property_readonly("analog_samples", &RawMasterFile::analog_samples, R"( + Number of analog samples + + Returns + ---------- + int | None + The number of analog samples in the file (or None if not enabled) + )") .def_property_readonly("digital_samples", - &RawMasterFile::digital_samples) + &RawMasterFile::digital_samples, R"( + Number of digital samples + + Returns + ---------- + int | None + The number of digital samples in the file (or None if not enabled) + )") .def_property_readonly("transceiver_samples", &RawMasterFile::transceiver_samples) @@ -54,5 +82,4 @@ py::class_(m, "RawMasterFile") .def_property_readonly("scan_parameters", &RawMasterFile::scan_parameters) .def_property_readonly("roi", &RawMasterFile::roi); - }