diff --git a/.github/workflows/convert.sh b/.github/workflows/convert.sh index 84968699..db27123e 100644 --- a/.github/workflows/convert.sh +++ b/.github/workflows/convert.sh @@ -2,10 +2,14 @@ echo "Converting all .md tutorials to .py files..." TUTS_DIR="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )/../../docs/tutorials" pushd ${TUTS_DIR} -for file in *.md; do - if [ "$file" != "index.md" ] && [ "$file" != "livestream.md" ]; then - jupytext --to py $file - fi +for subdir in */; do + pushd $subdir + for file in *.md; do + if [ "$file" != "index.md" ] && [ "$file" != "livestream.md" ]; then + jupytext --to py $file + fi + done + popd done popd echo "Done." diff --git a/docs/index.md b/docs/index.md index 19ab0b5e..872d3125 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,7 +50,7 @@ Acquire supports the following cameras (currently only on Windows): - [FLIR Blackfly USB3 (BFLY-U3-23S6M-C)](https://www.flir.com/products/blackfly-usb3/?model=BFLY-U3-23S6M-C&vertical=machine+vision&segment=iis) - [FLIR Oryx 10GigE (ORX-10GS-51S5M-C)](https://www.flir.com/products/oryx-10gige/?model=ORX-10GS-51S5M-C&vertical=machine+vision&segment=iis) -For testing and demonstration purposes, Acquire also provides a few simulated video sources. For more information on supported cameras and video sources, check out [this tutorial](./tutorials/drivers.md). +For testing and demonstration purposes, Acquire also provides a few simulated video sources. For more information on supported cameras and video sources, check out [this tutorial](./tutorials/setup_acquisition/drivers.md). Acquire supports the following output file formats: @@ -58,7 +58,7 @@ Acquire supports the following output file formats: - [OME-Zarr](https://ngff.openmicroscopy.org/latest/) for [Zarr v2](https://zarr.readthedocs.io/en/stable/spec/v2.html) - [Zarr v3](https://zarr.readthedocs.io/en/stable/spec/v3.html) -Acquire also supports raw and trash storage devices. For more information on supported file formats and storage devices, check out the [Storage Device Selection tutorial](./tutorials/storage.md). +Acquire also supports raw and trash storage devices. For more information on supported file formats and storage devices, check out the [Storage Device Selection tutorial](./tutorials/setup_acquisition/storage.md). ## Citing Acquire diff --git a/docs/tutorials/framedata.md b/docs/tutorials/access_data/framedata.md similarity index 100% rename from docs/tutorials/framedata.md rename to docs/tutorials/access_data/framedata.md diff --git a/docs/tutorials/access_data/index.md b/docs/tutorials/access_data/index.md new file mode 100644 index 00000000..5fad37b4 --- /dev/null +++ b/docs/tutorials/access_data/index.md @@ -0,0 +1,7 @@ +# Data + +These tutorials will help you learn how to access data during acquisition. +Please [submit an issue on GitHub](https://github.com/acquire-project/acquire-docs/issues/new) +if you'd like to request a tutorial. If you are also interested in contributing +to this documentation, please visit our +[contribution guide](https://acquire-project.github.io/acquire-docs/dev/for_contributors/). diff --git a/docs/tutorials/livestream.md b/docs/tutorials/access_data/livestream.md similarity index 77% rename from docs/tutorials/livestream.md rename to docs/tutorials/access_data/livestream.md index 084fb025..b251ff46 100644 --- a/docs/tutorials/livestream.md +++ b/docs/tutorials/access_data/livestream.md @@ -3,7 +3,7 @@ The below script can be used to livestream data to the [napari viewer](https://napari.org/stable/). You may also utilize the `Acquire` napari plugin, which is provided in the package upon install. You can access the plugin in the napari plugins menu once `Acquire` is installed. You can review the [plugin code in the `acquire-imaging` repository](https://github.com/acquire-project/acquire-python/blob/d4a927079830dd9b61289e19e68dafdff4e8e643/python/acquire/__init__.py#L134). You may also stream using other packages such at `matplotlib`. ~~~python -{% include "../examples/livestream_napari.py" %} +{% include "../../examples/livestream_napari.py" %} ~~~ -[Download this tutorial as a Python script](../examples/livestream_napari.py){ .md-button .md-button-center } +[Download this tutorial as a Python script](../../examples/livestream_napari.py){ .md-button .md-button-center } diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 40896dd9..83ef526e 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -5,3 +5,26 @@ examples of using the API. Please submit an [issue on Github](https://github.com request a tutorial, or if you are also interested in contributing to a tutorial to this documentation please visit our [contribution guide](../for_contributors/index.md). + +
+
+

Setup acquisition

+

Learn how to configure and run an acquisition

+ Setup acquisition +
+
+

Using JSON

+

Learn how to save and retrieve acquisition settings

+ Using JSON +
+
+

Data

+

Learn how to access data during acquisition

+ Data +
+
+

Zarr

+

Learn about using OME-Zarr with Acquire

+ Zarr +
+
\ No newline at end of file diff --git a/docs/tutorials/configure.md b/docs/tutorials/setup_acquisition/configure.md similarity index 94% rename from docs/tutorials/configure.md rename to docs/tutorials/setup_acquisition/configure.md index a79b5d61..dd084bd6 100644 --- a/docs/tutorials/configure.md +++ b/docs/tutorials/setup_acquisition/configure.md @@ -47,7 +47,7 @@ config.video[0].max_frame_count = 100 ## Configure `Camera` `Camera` class objects have 2 attributes, `settings`, a `CameraProperties` object, and an optional attribute `identifier`, which is a `DeviceIdentifier` object. -`CameraProperties` has 5 attributes that are numbers and specify the exposure time and line interval in microseconds, how many pixels, if any, to bin (set to 1 by default to disable), and tuples for the image size and location on the camera chip. The other attributes are all instances of different classes. The `pixel_type` attribute is a `SampleType` object which indicates the data type of the pixel values in the image, such as Uint8. The `readout_direction` attribute is a `Direction` object specifying whether the data is read forwards or backwards from the camera. The `input_triggers` attribute is an `InputTriggers` object that details the characteristics of any input triggers in the system. The `output_triggers` attribute is an `OutputTriggers` object that details the characteristics of any output triggers in the system. All of the attributes of `InputTriggers` and `OutputTriggers` objects are instances of the `Trigger` class. The `Trigger` class is described in [Triggers from a JSON file](trig_json.md). +`CameraProperties` has 5 attributes that are numbers and specify the exposure time and line interval in microseconds, how many pixels, if any, to bin (set to 1 by default to disable), and tuples for the image size and location on the camera chip. The other attributes are all instances of different classes. The `pixel_type` attribute is a `SampleType` object which indicates the data type of the pixel values in the image, such as Uint8. The `readout_direction` attribute is a `Direction` object specifying whether the data is read forwards or backwards from the camera. The `input_triggers` attribute is an `InputTriggers` object that details the characteristics of any input triggers in the system. The `output_triggers` attribute is an `OutputTriggers` object that details the characteristics of any output triggers in the system. All of the attributes of `InputTriggers` and `OutputTriggers` objects are instances of the `Trigger` class. The `Trigger` class is described in [Triggers from a JSON file](../using_json/trig_json.md). We'll configure some camera settings below. @@ -65,7 +65,7 @@ config.video[0].camera.settings.pixel_type = acquire.SampleType.U32 ## Configure `Storage` `Storage` objects have 2 attributes, `settings`, a `StorageProperties` object, and an optional attribute `identifier`, which is an instance of the `DeviceIdentifier` class described above. -`StorageProperties` has 2 attributes `external_metadata_json` and `filename` which are strings of the filename or filetree of the output metadata in JSON format and image data in whatever format corresponds to the selected storage device, respectively. `first_frame_id` is an integer ID that corresponds to the first frame of the current acquisition and is typically 0. `pixel_scale_um` is the camera pixel size in microns. `enable_multiscale` is a boolean used to specify if the data should be saved as an image pyramid. See [Multiscale Data Acqusition](multiscale.md) for more information. The `chunking` attribute is an instance of the `ChunkingProperties` class, used for Zarr storage. See [Chunking Data for Zarr Storage](chunked.md) for more information. +`StorageProperties` has 2 attributes `external_metadata_json` and `filename` which are strings of the filename or filetree of the output metadata in JSON format and image data in whatever format corresponds to the selected storage device, respectively. `first_frame_id` is an integer ID that corresponds to the first frame of the current acquisition and is typically 0. `pixel_scale_um` is the camera pixel size in microns. `enable_multiscale` is a boolean used to specify if the data should be saved as an image pyramid. See [Multiscale Data Acqusition](../zarr/multiscale.md) for more information. The `chunking` attribute is an instance of the `ChunkingProperties` class, used for Zarr storage. See [Chunking Data for Zarr Storage](../zarr/chunked.md) for more information. We'll specify the name of the output image file below. diff --git a/docs/tutorials/drivers.md b/docs/tutorials/setup_acquisition/drivers.md similarity index 100% rename from docs/tutorials/drivers.md rename to docs/tutorials/setup_acquisition/drivers.md diff --git a/docs/tutorials/setup_acquisition/index.md b/docs/tutorials/setup_acquisition/index.md new file mode 100644 index 00000000..8d231115 --- /dev/null +++ b/docs/tutorials/setup_acquisition/index.md @@ -0,0 +1,7 @@ +# Setup acquisition + +These tutorials will help you learn how to configure and run an acquisition. +Please [submit an issue on GitHub](https://github.com/acquire-project/acquire-docs/issues/new) +if you'd like to request a tutorial. If you are also interested in contributing +to this documentation, please visit our +[contribution guide](https://acquire-project.github.io/acquire-docs/dev/for_contributors/). diff --git a/docs/tutorials/select.md b/docs/tutorials/setup_acquisition/select.md similarity index 100% rename from docs/tutorials/select.md rename to docs/tutorials/setup_acquisition/select.md diff --git a/docs/tutorials/setup.md b/docs/tutorials/setup_acquisition/setup.md similarity index 100% rename from docs/tutorials/setup.md rename to docs/tutorials/setup_acquisition/setup.md diff --git a/docs/tutorials/start_stop.md b/docs/tutorials/setup_acquisition/start_stop.md similarity index 100% rename from docs/tutorials/start_stop.md rename to docs/tutorials/setup_acquisition/start_stop.md diff --git a/docs/tutorials/storage.md b/docs/tutorials/setup_acquisition/storage.md similarity index 100% rename from docs/tutorials/storage.md rename to docs/tutorials/setup_acquisition/storage.md diff --git a/docs/tutorials/trigger.md b/docs/tutorials/setup_acquisition/trigger.md similarity index 92% rename from docs/tutorials/trigger.md rename to docs/tutorials/setup_acquisition/trigger.md index ad5d25ad..75a10e5d 100644 --- a/docs/tutorials/trigger.md +++ b/docs/tutorials/setup_acquisition/trigger.md @@ -15,7 +15,7 @@ runtime = acquire.Runtime() ## Configure Camera -All camera settings can be captured by an instance of the `Properties` class, which will be associated with a given camera acquisition. The settings can be stored in a dictionary (e.g: `Properties.dict()`). These settings can be saved to a JSON file to be subsequently loaded, (e.g. `Properties(**json.load(open('acquire.json')))`), using the [json library](https://docs.python.org/3/library/json.html#). Check out [Properties from a JSON file](props_json.md) for a more detailed example, but in brief, you would use something like: +All camera settings can be captured by an instance of the `Properties` class, which will be associated with a given camera acquisition. The settings can be stored in a dictionary (e.g: `Properties.dict()`). These settings can be saved to a JSON file to be subsequently loaded, (e.g. `Properties(**json.load(open('acquire.json')))`), using the [json library](https://docs.python.org/3/library/json.html#). Check out [Properties from a JSON file](../using_json/props_json.md) for a more detailed example, but in brief, you would use something like: ```python config = runtime.get_configuration() @@ -49,7 +49,7 @@ config.video[0].camera.settings.pixel_type = acquire.SampleType.U16 # sets the p config.video[0].max_frame_count = 10 # finite acquisition of 10 frames. Use 0 for infinite acquisition. ``` -Triggers can also be set in the `CameraProperties` object. The parameters can be stored in a dictionary (e.g: `Trigger.dict()`). You can construct a `Trigger` from a JSON file (e.g. `acquire.Trigger(**json.loads(open('trigger.json')))` ), using the [json library](https://docs.python.org/3/library/json.html#). Check out [Triggers from a JSON file](trig_json.md) for a more detailed example, but in brief, you would use something like: +Triggers can also be set in the `CameraProperties` object. The parameters can be stored in a dictionary (e.g: `Trigger.dict()`). You can construct a `Trigger` from a JSON file (e.g. `acquire.Trigger(**json.loads(open('trigger.json')))` ), using the [json library](https://docs.python.org/3/library/json.html#). Check out [Triggers from a JSON file](../using_json/trig_json.md) for a more detailed example, but in brief, you would use something like: ```python trig = acquire.Trigger() @@ -98,7 +98,7 @@ from rich.pretty import pprint pprint(config.dict()) ``` -Check out [Properties from a JSON file](props_json.md) for a more detailed example of saving `Properties`. +Check out [Properties from a JSON file](../using_json/props_json.md) for a more detailed example of saving `Properties`. ## Acquire data diff --git a/docs/tutorials/using_json/index.md b/docs/tutorials/using_json/index.md new file mode 100644 index 00000000..736c8772 --- /dev/null +++ b/docs/tutorials/using_json/index.md @@ -0,0 +1,7 @@ +# Using JSON + +These tutorials will help you learn how to save and retrieve acquisition +settings. Please [submit an issue on GitHub](https://github.com/acquire-project/acquire-docs/issues/new) +if you'd like to request a tutorial. If you are also interested in contributing +to this documentation, please visit our +[contribution guide](https://acquire-project.github.io/acquire-docs/dev/for_contributors/). diff --git a/docs/tutorials/props_json.md b/docs/tutorials/using_json/props_json.md similarity index 93% rename from docs/tutorials/props_json.md rename to docs/tutorials/using_json/props_json.md index e71cfe81..3b56f99d 100644 --- a/docs/tutorials/props_json.md +++ b/docs/tutorials/using_json/props_json.md @@ -20,7 +20,7 @@ All camera settings are captured by an instance of the `Properties` class, which config = runtime.get_configuration() ``` -You can update any of the settings in this instance of `Properties`. To save any updated settings, use the `set_configuration` method. For this tutorial, we'll simply specify a camera, and then save these new settings. Note that more settings must be provided before this `Properties` object could be used for an acquistion. Check out [Configure an Acquisition](configure.md) for more information on configuring an acquisition. +You can update any of the settings in this instance of `Properties`. To save any updated settings, use the `set_configuration` method. For this tutorial, we'll simply specify a camera, and then save these new settings. Note that more settings must be provided before this `Properties` object could be used for an acquistion. Check out [Configure an Acquisition](../setup_acquisition/configure.md) for more information on configuring an acquisition. ```python # set the radial sine simulated camera as the first video stream @@ -51,7 +51,7 @@ with open("sample_props.json", "w") as outfile: The resulting sample_props.json file is below: ~~~json -{% include "../examples/sample_props.json" %} +{% include "../../examples/sample_props.json" %} ~~~ ## Load Properties from a JSON file diff --git a/docs/tutorials/trig_json.md b/docs/tutorials/using_json/trig_json.md similarity index 97% rename from docs/tutorials/trig_json.md rename to docs/tutorials/using_json/trig_json.md index b0401e13..5106136e 100644 --- a/docs/tutorials/trig_json.md +++ b/docs/tutorials/using_json/trig_json.md @@ -44,7 +44,7 @@ with open("sample_trig.json", "w") as outfile: The resulting sample_trig.json file is below: ~~~json -{% include "../examples/sample_trig.json" %} +{% include "../../examples/sample_trig.json" %} ~~~ ## Load Properties from a JSON file diff --git a/docs/tutorials/chunked.md b/docs/tutorials/zarr/chunked.md similarity index 100% rename from docs/tutorials/chunked.md rename to docs/tutorials/zarr/chunked.md diff --git a/docs/tutorials/compressed.md b/docs/tutorials/zarr/compressed.md similarity index 100% rename from docs/tutorials/compressed.md rename to docs/tutorials/zarr/compressed.md diff --git a/docs/tutorials/zarr/index.md b/docs/tutorials/zarr/index.md new file mode 100644 index 00000000..613abcfa --- /dev/null +++ b/docs/tutorials/zarr/index.md @@ -0,0 +1,7 @@ +# Zarr + +These tutorials will help you learn about using OME-Zarr with Acquire. Please +[submit an issue on GitHub](https://github.com/acquire-project/acquire-docs/issues/new) +if you'd like to request a tutorial. If you are also interested in contributing +to this documentation, please visit our +[contribution guide](https://acquire-project.github.io/acquire-docs/dev/for_contributors/). diff --git a/docs/tutorials/multiscale.md b/docs/tutorials/zarr/multiscale.md similarity index 100% rename from docs/tutorials/multiscale.md rename to docs/tutorials/zarr/multiscale.md diff --git a/mkdocs.yml b/mkdocs.yml index a1b4ee26..66a79834 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,20 +38,28 @@ nav: - API Reference: api_reference.md - Tutorials: - tutorials/index.md - - tutorials/trigger.md - - tutorials/configure.md - - tutorials/framedata.md - - tutorials/start_stop.md - - tutorials/livestream.md - - tutorials/select.md - - tutorials/setup.md - - tutorials/props_json.md - - tutorials/trig_json.md - - tutorials/multiscale.md - - tutorials/chunked.md - - tutorials/drivers.md - - tutorials/storage.md - - tutorials/compressed.md + - Setup acquisition: + - tutorials/setup_acquisition/index.md + - tutorials/setup_acquisition/trigger.md + - tutorials/setup_acquisition/configure.md + - tutorials/setup_acquisition/start_stop.md + - tutorials/setup_acquisition/select.md + - tutorials/setup_acquisition/setup.md + - tutorials/setup_acquisition/drivers.md + - tutorials/setup_acquisition/storage.md + - Using JSON: + - tutorials/using_json/index.md + - tutorials/using_json/trig_json.md + - tutorials/using_json/props_json.md + - Data: + - tutorials/access_data/index.md + - tutorials/access_data/framedata.md + - tutorials/access_data/livestream.md + - Zarr: + - tutorials/zarr/index.md + - tutorials/zarr/multiscale.md + - tutorials/zarr/chunked.md + - tutorials/zarr/compressed.md - For contributors: - for_contributors/index.md - for_contributors/docs_contribution_quickstart.md