Merge branch 'main' into remove-members

dgmccart · web-flow · commit 850d8709dba6 · 2024-09-04T10:26:12.000-07:00
diff --git 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/examples/livestream_napari.py b/docs/examples/livestream_napari.py
@@ -1,5 +1,5 @@
 """
-This script will livestream data to the [napari viewer](https://napari.org/stable/). You may also utilize the `Acquire` napari plugin, which is provided in the `acquire-imaging` package on PyPI upon install. You can access the plugin in the napari plugins menu once `Acquire` is installed. You can review the [plugin code here](https://github.com/acquire-project/acquire-python/blob/main/python/acquire/__init__.py).
+This script will livestream data to the [napari viewer](https://napari.org/stable/). You may also utilize the `Acquire` napari plugin, which is provided in the `acquire-imaging` package on PyPI upon install. You can access the plugin in the napari plugins menu once `Acquire` is installed. You can review the [plugin code in `acquire-imaging`](https://github.com/acquire-project/acquire-python/blob/main/python/acquire/__init__.py).
 """
 
 import acquire
diff --git a/docs/index.md b/docs/index.md
@@ -50,15 +50,15 @@ 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:
 
 - [Tiff](https://en.wikipedia.org/wiki/TIFF)
 - [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 [this 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
 
@@ -67,4 +67,4 @@ Acquire also supports raw and trash storage devices. For more information on sup
 ~~~
 
 ## Acquire License
-`Acquire` is provided under an [Apache 2.0 license](https://github.com/acquire-project/acquire-python/blob/main/LICENSE). You can learn more about the Apache license in the [documentation here](https://www.apache.org/licenses/LICENSE-2.0).
+`Acquire` is provided under an [Apache 2.0 license](https://github.com/acquire-project/acquire-python/blob/main/LICENSE). [Learn more about the Apache license](https://www.apache.org/licenses/LICENSE-2.0).
diff --git a/docs/tutorials/access_data/framedata.md b/docs/tutorials/access_data/framedata.md
diff --git a/docs/tutorials/access_data/index.md 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/access_data/livestream.md b/docs/tutorials/access_data/livestream.md
@@ -0,0 +1,9 @@
+# Livestream to napari
+
+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" %}
+~~~
+
+[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
@@ -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).
+
+<div class="cards">
+    <div class="card">
+        <h4>Setup acquisition</h4>
+        <p>Learn how to configure and run an acquisition</p>
+        <a href="setup_acquisition" class="button">Setup acquisition</a>
+    </div>
+    <div class="card">
+        <h4>Using JSON</h4>
+        <p>Learn how to save and retrieve acquisition settings</p>
+        <a href="using_json" class="button">Using JSON</a>
+    </div>
+    <div class="card">
+        <h4>Data</h4>
+        <p>Learn how to access data during acquisition</p>
+        <a href="access_data" class="button">Data</a>
+    </div>
+    <div class="card">
+        <h4>Zarr</h4>
+        <p>Learn about using OME-Zarr with Acquire</p>
+        <a href="zarr" class="button">Zarr</a>
+    </div>
+</div>
diff --git a/docs/tutorials/livestream.md b/docs/tutorials/livestream.md
diff --git a/docs/tutorials/setup_acquisition/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 [this tutorial](https://acquire-project.github.io/acquire-docs/tutorials/trig_json/).
+`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 the [multiscale tutorial](multiscale.md) for more information. The `chunking` attribute is an instance of the `ChunkingProperties` class, used for Zarr storage. See the [chunking tutorial](multiscale.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/setup_acquisition/drivers.md b/docs/tutorials/setup_acquisition/drivers.md
diff --git a/docs/tutorials/setup_acquisition/index.md 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/setup_acquisition/select.md b/docs/tutorials/setup_acquisition/select.md
diff --git a/docs/tutorials/setup_acquisition/setup.md b/docs/tutorials/setup_acquisition/setup.md
@@ -1,6 +1,6 @@
 # Utilizing the Setup Method
 
-This tutorial will provide an example of utilizing the [setup method](https://github.com/acquire-project/acquire-python/blob/ce0764e86bf1d10eb3a447eb670c28808ab3da3b/python/acquire/__init__.py#L41) to configure `Runtime` and specify some basic properties.
+This tutorial will provide an example of utilizing the [setup method][acquire.setup] to configure `Runtime` and specify some basic properties.
 
 ## Setup Function Definition
 
diff --git a/docs/tutorials/setup_acquisition/start_stop.md b/docs/tutorials/setup_acquisition/start_stop.md
@@ -4,7 +4,7 @@ This tutorial will provide an example of starting, stopping, and restarting acqu
 
 ## Configure Streaming
 
-To start, we'll create a `Runtime` object and configure the streaming process. To do this, we'll utilize the setup method. More information on that method is detailed in [this tutorial](https://acquire-project.github.io/acquire-docs/tutorials/setup).
+To start, we'll create a `Runtime` object and configure the streaming process. To do this, we'll utilize the setup method. More information on that method is detailed in [Utilizing the Setup Method](setup.md).
 
 ```python
 import acquire
diff --git a/docs/tutorials/setup_acquisition/storage.md b/docs/tutorials/setup_acquisition/storage.md
@@ -34,7 +34,7 @@ The output of that script will be:
 
 `Acquire` supports streaming data to [bigtiff](http://bigtiff.org/) and [Zarr V2](https://zarr.readthedocs.io/en/stable/spec/v2.html).
 
-Zarr has additional capabilities relative to the basic storage devices, namely _chunking_, _compression_, and _multiscale storage_. You can learn more about the Zarr capabilities in `Acquire` [here](https://github.com/acquire-project/acquire-driver-zarr).
+Zarr has additional capabilities relative to the basic storage devices, namely _chunking_, _compression_, and _multiscale storage_. You can learn more about the Zarr capabilities in `Acquire` in [the Acquire Zarr documentation](https://github.com/acquire-project/acquire-driver-zarr/blob/main/README.md).
 
 - **raw** - Streams to a raw binary file.
 
diff --git a/docs/tutorials/setup_acquisition/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 [this tutorial](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()
@@ -39,7 +39,7 @@ config.video[0].camera.identifier = runtime.device_manager().select(acquire.Devi
 
 Next we'll choose the settings for the Hamamatsu camera. The `CameraProperties` class describes the available settings, which include exposure time (in microseconds), binning, pixel data type (e.g. u16), and how many frames to acquire.
 
-Every property can be set using the following syntax, but in this example, we will only change a few of the available settings. [Check out this tutorial](configure.md) for an explanation of camera properties.
+Every property can be set using the following syntax, but in this example, we will only change a few of the available settings. Check out [Configure an Acquisition](configure.md) for an explanation of camera properties.
 
 ```python
 config.video[0].camera.settings.binning = 1 # no pixels will be combined
@@ -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 [this tutorial](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 [this tutorial](https://acquire-project.github.io/acquire-docs/tutorials/props_json/) 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
@@ -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/using_json/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 [this tutorial](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/using_json/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/zarr/chunked.md b/docs/tutorials/zarr/chunked.md
@@ -2,7 +2,7 @@
 
 This tutorial will provide an example of writing chunked data to a Zarr storage device.
 
-Zarr has additional capabilities relative to the basic storage devices, namely _chunking_, _compression_, and _multiscale storage_. To enable _chunking_, set the attributes in an instance of the `ChunkingProperties` class. You can learn more about the Zarr capabilities in `Acquire` [here](https://github.com/acquire-project/acquire-driver-zarr).
+Zarr has additional capabilities relative to the basic storage devices, namely _chunking_, _compression_, and _multiscale storage_. To enable _chunking_, set the attributes in an instance of the `ChunkingProperties` class. You can learn more about the Zarr capabilities in `Acquire` in [the Acquire Zarr documentation](https://github.com/acquire-project/acquire-driver-zarr/blob/main/README.md).
 
 ## Configure `Runtime`
 To start, we'll create a `Runtime` object and configure the streaming process, selecting `Zarr` as the storage device to enable chunking the data.
diff --git a/docs/tutorials/zarr/compressed.md b/docs/tutorials/zarr/compressed.md
diff --git a/docs/tutorials/zarr/index.md b/docs/tutorials/zarr/index.md
diff --git a/docs/tutorials/zarr/multiscale.md b/docs/tutorials/zarr/multiscale.md
diff --git a/mkdocs.yml b/mkdocs.yml
