Contributing to pyOsiriX

For general notes on contributing, please see the main contributing page for OsiriXgrpc as this sub-package follows the same processes. Specific instructions for code standards for conding conventions are provided below.

Code Conventions

All code must follow PEP-8 guidelines. Docstrings are written using the Google docstring standard. If in doubt, please look at existing code and follow the same syntax used, and/or raise an issue, so we can provide more clarity.

Package Structure

The main pyOsiriX package directory is called osirix.
Each python file within the package directory constitutes a distinct module.

Module Structure

Each module contains classes, each providing exposure to a specific aspect of OsiriX.
Except for the osirix.__init__ module, no functions are permitted within modules.
Each module should only contain classes that represent the same family of OsiriX objects (e.g. regions-of-interest, viewers, dicoms accessors).

Class structure

All methods must have the decorator @pyosirix_connection_check.
All class properties (get/set or just get) must include the decorator @property. Please ensure that attributes are chosen properly. For example color is an attribute. The method rotate is not.
Please include a docstring for each method. Ideally with an example if deemed necessary.
Please name the method appropriately using snake case. For example, if the method in OsiriXgrpc is ROIRotate, name it rotate.

Contributing pyOsiriX Example Scripts

We welcome example scripts from developers to help showcase its functionality to other users. We follow a blog-like format for examples so that information provided can be quite flexible. However, examples should follow the following basic premises:

Keep examples simple. We like to ensure that each example performs a specific operation rather than a complex processing pipeline. This ensures that examples remain modular and can be reused within different contexts. If your example contains different steps, think about how these can be broken down and submit as multiple example scripts.
Do not use complex/private datasets. This helps us reduce the need for hosting bespoke datasets within the pyOsiriX project. If certain data is needed (processing PET data for example), try to use public datasets, such as those provided by The Cancer Imaging Archive, and provide the data source in your example description.
Follow the Example Template when structuring the example description.
Ensure that the example covers one of the following script categories:
- Database: Performs operations on the OsiriX database.
- Image: Filters images displayed in the 2D viewer windows (including generation of regions of interest).
- ROI: Generates results from existing regions of interest within the 2D image viewer.
- VR: Filters data displayed within the volume render window.
Each example should consist of its own directory with the following content:
- README.md: A markdown page consisting of key information about the example, the script type, how it should be run, what data is needed (and the source if applicable), and the expected outcome (see below).
- script.py: A single python file containing the script that users can run.
- screenshot.py: A helpful, simple image that provides users with a pictorial representation of what the script does.
- requirements.txt: Any python requirements needed by the script. The user should be able to use this to install the necessary third-party packages needed to run your file using pip install -r requirements.txt. See the Requirements File Format for more information. Please try and minimize the number of requirements (do not just dump your current environment). Note: If no additional packages are required, please explicitly state this by providing an empty requirements.txt file.
- additional files (optional): Any other files that might be needed for running the script. Whilst it is possible to include additional dependent python module files to support you script, it is encouraged not to do this as it violates premise 1.

Example template

This file is also available in the project repository.

<!-- Choose a short, distinct and distinctive name for your script.  Should match name of parent directory -->
# Template

<!-- 
A short description of what the example script tries to achieve (single sentence/line).
Please ensure that the leading comment is left in! 
-->
<!-- shortdesc --> A template example script that may be used to format other scripts.

<!-- Choose the relevant categories out of "Database-blue", "Image-green", "ROI-purple" or "VR-red" -->
__Categories__:
![Database](https://img.shields.io/badge/Database-blue)
![Image](https://img.shields.io/badge/Image-green)
![Region of Interest](https://img.shields.io/badge/ROI-purple)
![Volume Render](https://img.shields.io/badge/VR-red)

<!-- Do not modify. Source image must have size 800 x 600 pixels. -->
<div style="text-align: center;">
<img alt="Script screenshot" height="300" src="screenshot.png" width="400" style="border: 1px solid grey;"/>
</div>

<!-- 
Please ensure that you (and your institution) get acknowledgment for your contribution!
Multiple entries should be comma-separated.
-->
## Authors
<table>
  <tr>
    <td> <b>Author(s)</b> </td>
    <td> Joe Bloggs<sup>1</sup> </td>
  </tr>
  <tr>
    <td> <b>Institution(s)</b> </td>
    <td> <sup>1</sup>The Institute of Research </td>
  </tr>
  <tr>
    <td> <b>Contact</b> </td>
    <td> joe.bloggs@institute.com </td>
  </tr>
</table>

<!-- Provide the data provenance (i.e. where it may be downloaded from). Use "Any data" if it works on any dataset. -->
## Datasets
Any data.

<!-- 
Here you can provide any additional details about the script to the user (e.g. use case or expected outcomes)
There is no limit on what information you wish to provide and subsection headings are flexible. 
-->
## Details
This example script is used to demonstrate how to write pyOsiriX examples. It can be run as any of the four categories.

### Expected Outcome
This should export the current date, time and python version to a file on the Desktop called `osirix_template_out.txt`.