added/updated documentation and related files

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Changes in this pull request
+
+
+## Testing performed
+
+
+## Related issues
+<!-- Use keywords such as "fixes", "closes", see https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue -->
+
+
+## Checklist before requesting a review
+
+- [ ] I have performed a self-review of my code
+- [ ] I have added docstrings/doxygen in line with the guidance in the developer guide
+- [ ] The code builds and runs on my machine
+
+## Contribution Notes
+
+Please read and adhere to the [contribution guidelines](https://github.com/ETSInitiative/PRDdefinition/blob/master/CONTRIBUTING.md).
+
+Please tick the following: 
+
+ - [ ] The content of this Pull Request (the Contribution) is intentionally submitted for inclusion in the ETSI software (the Work) under the terms and conditions of the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) License.

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+Contributing
+============
+
+(This document largely follows the [SIRF Contribution guidelines](https://github.com/SyneRBI/SIRF/blob/master/CONTRIBUTING.md).)
+
+Please help us by finding problems, discussing on the mailing lists, contributing documentation,
+bug fixes or even features. Below are some brief guidelines.
+
+## Reporting a problem
+
+Please use our [issue-tracker].
+
+## Submitting a patch
+
+For contributing any code or documentation that is non-trivial, we require a
+signed Contributor License Agreement, stating clearly that your
+conributions are licensed appropriately. This will normally need to be signed by your
+employer/university, unless you own your own copyright.
+You will have to do this only once. Please contact us for more information.
+
+Please keep a patch focused on a single issue/feature. This is important to keep our history clean,
+but will also help reviewing things and therefore speed-up acceptance.
+
+### Process
+
+This is our recommended process. If it sounds too daunting, ask for help.
+
+1. Create a new issue (see above). State that you will contribute a fix if you intend to do so.
+2. Create a [fork](https://help.github.com/articles/fork-a-repo) on github and work from there.
+3. Create a branch in your fork with a descriptive name and put your fixes there. If your fix is
+simple you could do it on github by editing a file, otherwise clone your project (or add a remote
+to your current git clone) and work as usual.
+4. If your change is important, add yourself to `NOTICE.txt` <!-- it to [CHANGES.md](https://github.com/SyneRBI/SIRF/blob/master/CHANGES.md)
+and even [UserGuide.md](https://github.com/SyneRBI/SIRF/blob/master/doc/UserGuide.md) or other documentation files.-->
+5. Use [well-formed commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+for each change (in particular with a single "subject" line
+followed by an empty line and then more details).
+6. Push the commits to your fork and submit a [pull request (PR)](https://help.github.com/articles/creating-a-pull-request)
+(enable changes by project admins.) Be prepared to add further commits to your branch after discussion.
+In the description of the PR, add a statement about which Issue this applies to
+using [a phrase such that github auto-closes the issue when merged to master](https://help.github.com/articles/closing-issues-using-keywords/).
+7. Be prepared to add further commits to your branch after discussion.
+Please by mindful about the resources used by our Continuous Integration (CI) workflows:
+  - Group your commits and only push once your code compiles and tests succeed on your machine
+  - Use specific keywords in the body of the last commit that you push to prevent CI being run:
+     - `[ci skip]` skips all CI runs (e.g. when you only change documentation, or when your update isn't ready yet)
+     - `[actions skip]` does not run GitHub Actions, see [here](https://github.blog/changelog/2021-02-08-github-actions-skip-pull-request-and-push-workflows-with-skip-ci/).
+8. After acceptance of your PR, go home with a nice warm feeling.
+
+Suggested reading: 
+https://help.github.com/articles/fork-a-repo/, https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project or https://guides.github.com/activities/forking/.
+
+### A note on copyright dates and notices (and licenses)
+
+(Almost) all SIRF files start with a copyright and license header. Please do this for your files as well.
+If you modify an existing file, you need to make sure the copyright header is up-to-date for your changes
+(unless it's a trivial change).
+
+If you copied code from somewhere, you need to preserve its copyright date/notice. If you copied external code,
+you need to make sure its license is compatible with the Apache 2.0 license, and indicate clearly what the license
+of the copied code is (and follow its terms of course).
+
+## Project rules
+
+- Only one official, stable, up-to-date branch: **main**
+    + Essentially "latest stable beta version with no known bugs
+      since the last official release version"
+    + Never knowingly add a bug to **main**
+- Any work-in-progress commits should be in their own branches.
+- GitHub assigns a unique number to each issue, c.f. the [issue-tracker].
+- A pull request (PR) is an issue with an associated branch,
+  c.f. [pull-requests]. Even for "internal" development, we prefer a PR for
+  a branch to allow review and discussion.
+- Branches and PRs are kept small (ideally one 'feature' only) and branch from **main**,
+  not from another branch, unless required. This allows
+  commenting/improving/merging this branch/PR
+  independent of other developments.
+- Contributions of new features should also update documentation and release notes. After version 1.0,
+  this documentation needs to state something like "introduced after version 1.xxx".
+- We prefer issues to be opened via [github][issue-tracker] due to the following reasons:
+    + Ensures issues will never get lost in emails
+        * Facilitates issue status tracking
+    + Allows focused comments/discussion
+        * Easy cross-referencing of related issues, PRs, and commits
+
+```
+
+[issue-tracker]: https://github.com/ETSInitiative/PRDdefinition/issues
+[submodules]: https://git-scm.com/docs/gitsubmodules
+[pull-requests]: https://github.com/SyneRBI/SIRF/pulls

LICENSE.txt

@@ -0,0 +1,53 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. 
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

NOTICE.txt

@@ -0,0 +1,14 @@
+Copyright 2023 University College London (UCL)
+Copyright 2022-2023 Microsoft Corporation
+
+This software product is developed for the Emission Tomography Standardization
+Initiative (ETSI), https://etisinitiative.org.
+
+Main contributors:
+Kris Thielemans (UCL)
+John Stairs (Microsoft Corporation)
+Michael Hansen (Microsoft Corporation)
+
+### Apache License ###
+
+All documents are covered by the Apache 2.0 license, unless specified.

README.md

@@ -1,31 +1,25 @@
-# PET data model
+# PETSIRF draft data model and examples
 
-The purpose of this repo is to have a simple working example of a data model for PET imaging (list mode data). This is not a working example yet for the actual representation of PET data.
+The purpose of this repo is to have a simple working example of a data model for PET imaging (list mode data). This is **not complete**, and aspects do not follow the actual proposal of PETSIRD yet.
 
-The specification uses the [yardl](https://github.com/Microsoft/yardl) tool to define the model.
+## Background
+The [Emission Tomography Standardization Initiative (ETSI)](https://etsinitiative.org/)
+is working towards establishing a standard for PET Raw Data, called PETSIRD ("PET ETSI Raw Data").
 
-## To get started quickly:
-
-1. Open this repo in [GitHub Codespaces](https://code.visualstudio.com/docs/remote/codespaces) or in a [VS Code devcontainer](https://code.visualstudio.com/docs/devcontainers/containers).
-2. There is a model package in the `model` directory. `cd` into it and run `yardl generate` to generate C++ and Python code for the model.
-
-### C++
-
-The C++ code shows writing to and reading from an HDF5 file
+The specification uses the [yardl](https://aka.ms/yardl) tool to define the model.
+`yardl` can be used to read the specification (in the `model` directory) and
+generate an SDK for both C++ and API to read/write PETSIRD data.
 
-1. Compile the code:
-    - `cd ../cpp && mkdir -p build && cd build`
-    - `cmake -G Ninja -S ..` (if you installed HDF5 via `conda`, add `-DHDF5_ROOT=$CONDA_PREFIX`)
-    - `ninja`
-1. Run the generator: `./prd_generator test.h5`
-1. Run the analyzer: `./prd_analysis test.h5`
-1. You can inspect the HDF5 file by running `h5dump test.h5`
-
-
-### Python
-
-The Python code shows piping the compact binary format to standard out and
-reading it from standard in.
+## To get started quickly:
 
-1. From the repo root `cd python`
-1. `python prd_generator.py | python prd_analysis.py`
+1. Open this repo in [GitHub Codespaces](https://code.visualstudio.com/docs/remote/codespaces) or
+in a [VS Code devcontainer](https://code.visualstudio.com/docs/devcontainers/containers).
+This codespace/container will contain all necessary tools, including `yardl` itself, as well as the current repository.
+2. Browse the [`model`](./model/README.md) directory.
+3. Use `yardl` to generate C++ and Python code for the model:
+  ```sh
+  cd model
+  yardl generate
+  ```
+4. Have a look at (and try!) the examples in the [`cpp`](cpp/README.md) and/or
+[`python`](python/README.md) directories.

SUPPORT.md

@@ -0,0 +1,13 @@
+# Support
+
+## How to file issues and get help
+
+This project uses GitHub Issues to track bugs and feature requests. Please search the existing
+issues before filing new issues to avoid duplicates.  For new issues, file your bug or
+feature request as a new Issue.
+
+For help and questions about using this project, please [start a discussion](https://github.com/ETSInitiative/PRDdefinitions/discussions).
+
+## Support Policy
+
+Support for this project is limited to the resources listed above.

cpp/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 17)
 if(WIN32)
   add_compile_options(/W3 /WX)
 else()
-  add_compile_options(-Wall -Wextra -pedantic -Werror)
+  add_compile_options(-Wall -Wextra -pedantic)
 endif()
 
 add_executable(prd_generator prd_generator.cpp)

cpp/README.md

@@ -0,0 +1,19 @@
+# PETSIRD basic C++ example
+
+This directory contains some C++ example code to read/write PETSIRD data. You need to `yardl generate` in the `model` directory first.
+
+The C++ code shows writing to and reading from an HDF5 file
+
+1. Compile the code:
+   ```sh
+   cd /whereever/cpp
+   mkdir -p build && cd build`
+   cmake -G Ninja -S .. -DHDF5_ROOT=$CONDA_PREFIX
+   ninja`
+   ```
+   If you did not use `conda` to install HDF5, do not add the `-DHDF5_ROOT=$CONDA_PREFIX` part of the `cmake` line.
+
+2. Run the generator: `./prd_generator test.h5`
+3. Run the analyzer: `./prd_analysis test.h5`
+4. You can inspect the HDF5 file by running `h5dump test.h5`
+

environment.yml

@@ -6,8 +6,7 @@ dependencies:
   - bash-completion=2.11
   - cmake=3.21.3
   - fmt=8.1.1
-  - gcc_linux-64=11.2.0
-  - gxx_linux-64=11.2.0
+  - compilers
   - h5py=3.7.0
   - hdf5=1.12.1
   - howardhinnant_date=3.0.1
@@ -17,6 +16,5 @@ dependencies:
   - numpy=1.24.3
   - python=3.11.3
   - shellcheck=0.8.0
-  - valgrind=3.18.1
   - xtensor-fftw=0.2.5
   - xtensor=0.24.2