From a611d4f5ce4607be56d58640258c6211d9c9f87d Mon Sep 17 00:00:00 2001 From: Richard Bowman Date: Thu, 19 Aug 2021 09:40:10 +0100 Subject: [PATCH 01/11] Deploy OpenAPI description properly --- .gitlab-ci.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index eb3fec24..cee8fff5 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -194,10 +194,7 @@ package: name: "dist" expire_in: 1 week paths: - - "./dist/openflexure-microscope-server-${CI_COMMIT_REF_NAME}.tar.gz" - - "./dist/openflexure-microscope-server-${CI_COMMIT_REF_NAME}.tar.gz.sha256" - - "./dist/openflexure-microscope-webapp-${CI_COMMIT_REF_NAME}.tar.gz" - - "./dist/openflexure-microscope-webapp-${CI_COMMIT_REF_NAME}.tar.gz.sha256" + - "./dist/" only: - master From 1cd097b7aa9e26200f53c677aeadd633d87d405d Mon Sep 17 00:00:00 2001 From: Richard Bowman Date: Thu, 19 Aug 2021 16:12:58 +0100 Subject: [PATCH 02/11] First attempt at fixing readthedocs This removes the API documentation - we will render it separately. --- docs/requirements.txt | 1 - docs/source/api.rst | 9 +++------ docs/source/conf.py | 2 -- 3 files changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 9aa2c29a..52b04f2e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1 @@ -sphinxcontrib.httpdomain sphinx_rtd_theme \ No newline at end of file diff --git a/docs/source/api.rst b/docs/source/api.rst index f33d32a0..f2ffdac2 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -6,10 +6,7 @@ Live documentation Full, interactive Swagger documentation for your microscopes web API is available from the microscope itself. From any browser, go to ``http://{your microscope IP address}/api/v2/docs/swagger-ui``. -.. note:: We should have an online copy of the API SwaggerUI documentation up soon. +The API is described in an OpenAPI description, available at ``http://{your microscope IP address}/api/v2/docs/openapi.yaml``. It is also available from our `build server`_. It can be conveniently viewed using Redoc, for example `link to test OpenAPI rendering`_ -The API is now also detailed below, or there is a more interactive version of the docs statically compiled using ReDoc_ - -.. openapi:: ../build/swagger.yaml - -.. _ReDoc: api_redoc.html \ No newline at end of file +.. _`build server`: https://build.openflexure.org/openflexure-microscope-server/ +.. _`link to test OpenAPI rendering`: https://redocly.github.io/redoc/?url=https://build.openflexure.org/temp/rwb34/swagger.yaml \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index e3550325..c6495bc0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -68,8 +68,6 @@ extensions = [ "sphinx.ext.viewcode", "sphinx.ext.githubpages", "sphinx.ext.ifconfig", - "sphinxcontrib.openapi", - "sphinxcontrib.redoc", ] # Override ordering From 3b40ae9918b1c0cbbf6514d32852d90efe8baf16 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 13:33:39 +0100 Subject: [PATCH 03/11] Don't build OpenAPI automatically Readthedocs won't be able to build OpenAPI, so I've removed this from the makefile. --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index d2829e5b..feb32403 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,5 +20,5 @@ $(BUILDDIR)/swagger.yaml: Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: openapi Makefile +html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file From a09d2411a026a2f9611c0511142c7913a4eff0f5 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 13:43:35 +0100 Subject: [PATCH 04/11] Add documentation of the web app A first pass of documentation describing the web app GUI. Screenshots are committed as LFS objects, I've been deliberately conservative here (only png files in the docs/ directory are LFSed) to avoid messing with any static files in the web app. --- docs/source/index.rst | 1 + docs/source/quickstart.rst | 14 +++++++++----- docs/source/webapp/index.rst | 22 ++++++++++++++++++++++ docs/source/webapp/pane_capture.png | 3 +++ docs/source/webapp/pane_capture.rst | 23 +++++++++++++++++++++++ docs/source/webapp/pane_gallery.png | 3 +++ docs/source/webapp/pane_gallery.rst | 10 ++++++++++ docs/source/webapp/pane_navigate.png | 3 +++ docs/source/webapp/pane_navigate.rst | 10 ++++++++++ docs/source/webapp/pane_settings.png | 3 +++ docs/source/webapp/pane_settings.rst | 12 ++++++++++++ docs/source/webapp/pane_view.png | 3 +++ docs/source/webapp/scan_dialog.png | 3 +++ 13 files changed, 105 insertions(+), 5 deletions(-) create mode 100644 docs/source/webapp/index.rst create mode 100644 docs/source/webapp/pane_capture.png create mode 100644 docs/source/webapp/pane_capture.rst create mode 100644 docs/source/webapp/pane_gallery.png create mode 100644 docs/source/webapp/pane_gallery.rst create mode 100644 docs/source/webapp/pane_navigate.png create mode 100644 docs/source/webapp/pane_navigate.rst create mode 100644 docs/source/webapp/pane_settings.png create mode 100644 docs/source/webapp/pane_settings.rst create mode 100644 docs/source/webapp/pane_view.png create mode 100644 docs/source/webapp/scan_dialog.png diff --git a/docs/source/index.rst b/docs/source/index.rst index d4d13333..d1d3a76d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,6 +6,7 @@ Welcome to OpenFlexure Microscope Software's documentation! :caption: Contents: quickstart.rst + webapp/index.rst config.rst microscope.rst camera.rst diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index abeaaf45..a0f4ebd5 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -6,17 +6,21 @@ Install Stable installation +++++++++++++++++++ -For most users, the OpenFlexure Microscope software should be installed using our `pre-built Raspbian SD card image. `_ +The OpenFlexure Microscope software is designed to be run on the embedded Raspberry Pi, in an OpenFlexure Microscope. For most users, our `pre-built Raspbian SD card image. `_ is the easiest way to get started. This SD card image is based on Raspberry Pi OS and includes both the microscope server and OpenFlexure Connect. A desktop shortcut will directly start OpenFlexure Connect if you are using the Raspberry Pi directly, or the microscope can be controlled over the network with its default hostname `raspberrypi.local`. Manual installation +++++++++++++++++++ -For offline (i.e. no real microscope connected) development, a basic development server can run on any system. +To install the server on a Raspberry Pi without using the pre-built OpenFlexure Raspbian image, or to install the server on a different system (this is useful for development), follow the instructions in the README file at the top level of the project's repository. -- (Recommended) create and activate a virtual environment -- Install non-python dependencies with ``sudo apt-get install libatlas-base-dev libjasper-dev libjpeg-dev`` -- Install `Poetry `_, clone this repo, and ``poetry install`` from inside the repo. +Usage +----- +The easiest way to use the microscope is through OpenFlexure Connect, our cross-platform application that handles discovering and connecting to the microscope. It is detailed on the `instruction page on our website `_ including a download link. OpenFlexure Connect is pre-installed on the full SD card image (not the "lite" image, as this does not have support for a graphical desktop). + +If you know the hostname or IP address of your microscope, you can also connect to the same interface using a web browser by entering `http://microscope.local:5000/` as the address. `microscope.local` is the default hostname of the microscope if you use our pre-built SD card image. If you know the IP address or have customised the hostname, you can use that instead. Note that the hostname is announced via mDNS, which is usually reliable if the microscope is connected via a network cable directly to your client computer but may not work if both devices are connected to a more complicated network. As support for mDNS varies between operating systems, OpenFlexure Connect often detects microscopes even if you cannot resolve the microscope using the mDNS hostname. + +Whether you connect with OpenFlexure Connect, or through a web browser, the web application interface is the same. See the "web application" section of this manual for more details. Managing the server ------------------- diff --git a/docs/source/webapp/index.rst b/docs/source/webapp/index.rst new file mode 100644 index 00000000..d479d04f --- /dev/null +++ b/docs/source/webapp/index.rst @@ -0,0 +1,22 @@ +Web Application interface +========================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + pane_navigate.rst + pane_capture.rst + pane_settings.rst + pane_gallery.rst + +The main graphical interface for the OpenFlexure Microscope is implemented as a web application, which allows it to be accessed either through OpenFlexure Connect or a web browser. See the :doc:`../quickstart.rst` page for connection instructions. A "tour" should guide users through the interface when they connect for the first time, and introduce the key interface elements. + +Interface structure +------------------- +The main interface has a tab bar on the left, which allows the operator to select different controls. By default, the "view" pane does not show any additional controls, and a video feed from the camera fills the window. + +.. image:: pane_view.png + +Selecting one of the tab icons on the left will bring up the corresponding interface. Most of the pages display the image on the right hand side, and add additional controls between the image display and the tab bar. + diff --git a/docs/source/webapp/pane_capture.png b/docs/source/webapp/pane_capture.png new file mode 100644 index 00000000..12aa7239 --- /dev/null +++ b/docs/source/webapp/pane_capture.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0dcbbfbc4d5ba77824083b497b015b4178ec47f375f8e0457cb103da5befd2cf +size 1971891 diff --git a/docs/source/webapp/pane_capture.rst b/docs/source/webapp/pane_capture.rst new file mode 100644 index 00000000..c4990818 --- /dev/null +++ b/docs/source/webapp/pane_capture.rst @@ -0,0 +1,23 @@ +Capture pane +============ +The capture pane allows images to be acquired through the interface. By default, a single image is captured to the microscope's internal SD card, and can be downloaded from the gallery. Various settings are available to control the resolution of the image captured: the "full resolution" checkbox will save the image at native resolution, and the "store raw data" checkbox saves raw pixel data as an EXIF annotation. + +Due to the underlying ``picamera`` library, images are always saved as JPEG files, and raw data is simply appended to the file for later extraction. If an image is saved with raw data, the JPEG image is still the processed, compressed version; an external tool must be used to extract and process the raw Bayer data. + +.. image:: pane_capture.png + +It is also possible to acquire a grid of images for stitching together into a mosaic, by expanding the "Stack and Scan" section and enabling the "Scan capture" checkbox. Scans are 3D by default (i.e. a mosaic of images in X and Y, with a Z stack at each position) but 2D or linear scans can be performed by setting the number of steps in the unused axes to 1. This allows XY mosaics or Z stacks to be performed. + +When scanning is enabled, the "capture" button is replaced by a "start scan" button, which will start the scan and display a progress indicator until scanning has finished. + +.. image:: scan_dialog.png + +The step sizes (in motor steps) for each axis specify the number of motor steps to move between images, then the "steps" fields specify the number of images to acquire along each axis. If "steps" is set to 1 for any axis, no scanning happens along that axis. + +The scan routine will move through XY coordinates, and at each XY position will optionally run an autofocus routine, then acquire either a single image or a Z stack depending on the value of "z steps". The autofocus options correspond to those available in the "move" pane, allowing "fast" autofocus, or conventional autofocus with coarse, medium, or fine steps to be used. Selecting "none" disables autofocus. The vast majority of the time, "fast" autofocus is both quicker and more accurate than the other methods. + +Various scan patterns are available for XY scanning. Raster scanning is the default, which scans columns (i.e. from lowest to highest Y coordinate) and works from low to high X coordinates as the "slow" scan axis. Snake scanning reverses every other column, such that there is a smaller distance from the end of one column to the beginning of the next. This can be helpful if the sample is not perfectly flat, as it avoids losing focus between columns. Finally, "spiral" scanning starts by taking an image at the current position, then works outwards in concentric squares. Spiral scans use the "x steps" value to set the number of rings, and ignore the "y steps" value. + +Images acquired during the scan will be saved to a folder on the Raspberry Pi. They can be named according to their coordinates in the scan (default) or numbered sequentially (in case the latter is easier to process). + +To retrieve images acquired during a scan, or captured individually, you can use the :doc:`pane_gallery.rst`. \ No newline at end of file diff --git a/docs/source/webapp/pane_gallery.png b/docs/source/webapp/pane_gallery.png new file mode 100644 index 00000000..d7f21d31 --- /dev/null +++ b/docs/source/webapp/pane_gallery.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4c5dc30ff335f782d9a5c9d5568e13787f63be7e5d0a46c73afd5d525e79d557 +size 1370769 diff --git a/docs/source/webapp/pane_gallery.rst b/docs/source/webapp/pane_gallery.rst new file mode 100644 index 00000000..415c360e --- /dev/null +++ b/docs/source/webapp/pane_gallery.rst @@ -0,0 +1,10 @@ +Gallery pane +============ + +.. image:: pane_gallery.png + +The gallery displays all the images currently stored on the microscope. Scans are grouped together into folders. Clicking on an image will display it in a "lightbox" view that allows scrolling through all images in the current view. When an image is displayed in the lightbox view, it may be right-clicked to download it. Multiple images can also be downloaded as a zip archive. + +Bulk transfer of images is often easier using SCP, and images are stored by default in ``/var/openflexure/data/micrographs/`` on the Raspberry Pi. + +Saving of images to external storage is possible - this can be configured using the "autostorage" plugin, which currently displays an SD card icon in the navigation bar at the left of the screen. \ No newline at end of file diff --git a/docs/source/webapp/pane_navigate.png b/docs/source/webapp/pane_navigate.png new file mode 100644 index 00000000..d8c816d2 --- /dev/null +++ b/docs/source/webapp/pane_navigate.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:400d4f25aef0fecddbab296d982fb881367f1c5b6cdbd83b592bbbd142f3ef04 +size 3184560 diff --git a/docs/source/webapp/pane_navigate.rst b/docs/source/webapp/pane_navigate.rst new file mode 100644 index 00000000..62d2c109 --- /dev/null +++ b/docs/source/webapp/pane_navigate.rst @@ -0,0 +1,10 @@ +Navigate pane +============= + +The navigate pane displays the current stage position. Editing the values for X, Y, and Z and then hitting "enter" or clicking "move" will move the stage to the specified coordinates. Using the arrow keys (or page up/down) when not editing a text box will also move the stage, and the step size used can be set in the "configure" section at the top of the pane (which is collapsed by default). Using the mouse scroll wheel on the image will also move in Z, using the same configured step size. Double clicking on the image will bring the point clicked to the centre of the field of view, if the camera-stage mapping has been calibrated (see :doc:`pane_settings.rst`). + +Autofocus can also be run from the navigate pane, by clicking the "fast", "medium" or "fine" buttons. Fast autofocus moves the stage up and down in a continuous motion, using the size of images in the MJPEG stream from the camera to determine the sharpest point. This is usually both faster and more accurate than the other methods, however the other two options use a different metric, and stop the stage for each measurement. This can lead to them being more reliable in some circumstances. + +.. image:: pane_navigate.png + + diff --git a/docs/source/webapp/pane_settings.png b/docs/source/webapp/pane_settings.png new file mode 100644 index 00000000..8bf0e7ce --- /dev/null +++ b/docs/source/webapp/pane_settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ac21613d68c30c3e9038f71d738d41a266e6d99f3f93c9b92f833f1564ccd179 +size 668472 diff --git a/docs/source/webapp/pane_settings.rst b/docs/source/webapp/pane_settings.rst new file mode 100644 index 00000000..00b0a85a --- /dev/null +++ b/docs/source/webapp/pane_settings.rst @@ -0,0 +1,12 @@ +Settings pane +============= + +The settings for the microscope are gathered together into a settings pane, which is further subdivided into sections. This page does not provide an exhaustive list, but a few of the notable controls are: + +* Adjusting exposure time and gain of the camera, including automatic adjustment. +* Automatic white balance and flat-field correction for the camera. +* Enabling or disabling certain features of the software (e.g. ImJoy integration). +* Enabling or disabling the video stream (this allows the native low-latency preview on the Raspberry Pi to be used instead). +* Calibrating the relationship between stage coordinates and pixel coordinates in the video stream, allowing click-to-move to function. + +Important calibration tasks (in particular camera settings adjustment and click-to-move calibration) will be prompted in a "wizard" dialogue when the software is first run, to help first time users set up their microscope. All of the auto calibration routines are also available from the settings pane. \ No newline at end of file diff --git a/docs/source/webapp/pane_view.png b/docs/source/webapp/pane_view.png new file mode 100644 index 00000000..0d92f958 --- /dev/null +++ b/docs/source/webapp/pane_view.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aca1cddcdd8038920748196f95307d8d0110ed702990dd4831b1566afe01dabd +size 1930201 diff --git a/docs/source/webapp/scan_dialog.png b/docs/source/webapp/scan_dialog.png new file mode 100644 index 00000000..06d74b02 --- /dev/null +++ b/docs/source/webapp/scan_dialog.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5bc4944c89be5f43b178145fc7ff8c414dac1716275dc83e02a4bc23493aa2fb +size 32284 From 151d9f1bc097274e2eae53bcdac277c535a3b7ae Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 13:55:29 +0100 Subject: [PATCH 05/11] Various fixes to docs I've added a lot more mock imports so the automatic documentation now works. I've updated the links between pages (removing .rst extension) so they work. I've added a link to the settings pane image. --- docs/source/conf.py | 26 +++++++++++++++----------- docs/source/webapp/index.rst | 10 +++++----- docs/source/webapp/pane_capture.rst | 2 +- docs/source/webapp/pane_navigate.rst | 2 +- docs/source/webapp/pane_settings.rst | 4 +++- 5 files changed, 25 insertions(+), 19 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c6495bc0..bb3a38c9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -34,7 +34,21 @@ class Mock(MagicMock): return MagicMock() -mock_imports = ["picamerax", "picamerax.array", "picamerax.mmalobj"] +mock_imports = [ + "picamerax", + "picamerax.array", + "picamerax.mmalobj", + "numpy", + "labthings", + "labthings.json", + "expiringdict", + "dateutil", + "dateutil.parser", + "typing_extensions", + "PIL", + "sangaboard", + "piexif", +] sys.modules.update((mod_name, Mock()) for mod_name in mock_imports) @@ -235,13 +249,3 @@ intersphinx_mapping = { # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True - -# -- Options for redoc extension --------------------------------------------- -redoc = [ - { - "name": "OpenFlexure Microscope HTTP API", - "page": "api_redoc", - "spec": "../build/swagger.yaml", - "embed": True, - } -] diff --git a/docs/source/webapp/index.rst b/docs/source/webapp/index.rst index d479d04f..7feb37fd 100644 --- a/docs/source/webapp/index.rst +++ b/docs/source/webapp/index.rst @@ -5,12 +5,12 @@ Web Application interface :maxdepth: 2 :caption: Contents: - pane_navigate.rst - pane_capture.rst - pane_settings.rst - pane_gallery.rst + pane_navigate + pane_capture + pane_settings + pane_gallery -The main graphical interface for the OpenFlexure Microscope is implemented as a web application, which allows it to be accessed either through OpenFlexure Connect or a web browser. See the :doc:`../quickstart.rst` page for connection instructions. A "tour" should guide users through the interface when they connect for the first time, and introduce the key interface elements. +The main graphical interface for the OpenFlexure Microscope is implemented as a web application, which allows it to be accessed either through OpenFlexure Connect or a web browser. See the :doc:`../quickstart` page for connection instructions. A "tour" should guide users through the interface when they connect for the first time, and introduce the key interface elements. Interface structure ------------------- diff --git a/docs/source/webapp/pane_capture.rst b/docs/source/webapp/pane_capture.rst index c4990818..dcbdbd42 100644 --- a/docs/source/webapp/pane_capture.rst +++ b/docs/source/webapp/pane_capture.rst @@ -20,4 +20,4 @@ Various scan patterns are available for XY scanning. Raster scanning is the def Images acquired during the scan will be saved to a folder on the Raspberry Pi. They can be named according to their coordinates in the scan (default) or numbered sequentially (in case the latter is easier to process). -To retrieve images acquired during a scan, or captured individually, you can use the :doc:`pane_gallery.rst`. \ No newline at end of file +To retrieve images acquired during a scan, or captured individually, you can use the :doc:`pane_gallery`. \ No newline at end of file diff --git a/docs/source/webapp/pane_navigate.rst b/docs/source/webapp/pane_navigate.rst index 62d2c109..d1f050bc 100644 --- a/docs/source/webapp/pane_navigate.rst +++ b/docs/source/webapp/pane_navigate.rst @@ -1,7 +1,7 @@ Navigate pane ============= -The navigate pane displays the current stage position. Editing the values for X, Y, and Z and then hitting "enter" or clicking "move" will move the stage to the specified coordinates. Using the arrow keys (or page up/down) when not editing a text box will also move the stage, and the step size used can be set in the "configure" section at the top of the pane (which is collapsed by default). Using the mouse scroll wheel on the image will also move in Z, using the same configured step size. Double clicking on the image will bring the point clicked to the centre of the field of view, if the camera-stage mapping has been calibrated (see :doc:`pane_settings.rst`). +The navigate pane displays the current stage position. Editing the values for X, Y, and Z and then hitting "enter" or clicking "move" will move the stage to the specified coordinates. Using the arrow keys (or page up/down) when not editing a text box will also move the stage, and the step size used can be set in the "configure" section at the top of the pane (which is collapsed by default). Using the mouse scroll wheel on the image will also move in Z, using the same configured step size. Double clicking on the image will bring the point clicked to the centre of the field of view, if the camera-stage mapping has been calibrated (see :doc:`pane_settings`). Autofocus can also be run from the navigate pane, by clicking the "fast", "medium" or "fine" buttons. Fast autofocus moves the stage up and down in a continuous motion, using the size of images in the MJPEG stream from the camera to determine the sharpest point. This is usually both faster and more accurate than the other methods, however the other two options use a different metric, and stop the stage for each measurement. This can lead to them being more reliable in some circumstances. diff --git a/docs/source/webapp/pane_settings.rst b/docs/source/webapp/pane_settings.rst index 00b0a85a..f25ff83b 100644 --- a/docs/source/webapp/pane_settings.rst +++ b/docs/source/webapp/pane_settings.rst @@ -9,4 +9,6 @@ The settings for the microscope are gathered together into a settings pane, whic * Enabling or disabling the video stream (this allows the native low-latency preview on the Raspberry Pi to be used instead). * Calibrating the relationship between stage coordinates and pixel coordinates in the video stream, allowing click-to-move to function. -Important calibration tasks (in particular camera settings adjustment and click-to-move calibration) will be prompted in a "wizard" dialogue when the software is first run, to help first time users set up their microscope. All of the auto calibration routines are also available from the settings pane. \ No newline at end of file +Important calibration tasks (in particular camera settings adjustment and click-to-move calibration) will be prompted in a "wizard" dialogue when the software is first run, to help first time users set up their microscope. All of the auto calibration routines are also available from the settings pane. + +.. image:: pane_settings.png \ No newline at end of file From 107ef80b9ea2dd870e607c23fce15781a693c4c8 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 14:03:21 +0100 Subject: [PATCH 06/11] Track documentation images with LFS PNG images in the docs/ directory will be tracked using LFS, to avoid the repo becoming unmanageable. --- .gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..9bafe31d --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/**/*.png filter=lfs diff=lfs merge=lfs -text From 72c060c21308b39b8cbdf27f608c7bef318557a6 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 14:22:22 +0100 Subject: [PATCH 07/11] Workaround for LFS images There is now code in `conf.py` to install git LFS and to check images are correctly fetched. --- docs/source/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index bb3a38c9..b6a99eff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,18 @@ import os import sys +# Workaround to install and execute git-lfs on Read the Docs +if os.system("git lfs env > /dev/null") == 0: + os.system("git lfs fetch") + os.system("git lfs checkout") +else: + print("Warning: it seems git lfs is not installed. Bodging our way around the problem to retrieve images...") + os.system('wget https://github.com/git-lfs/git-lfs/releases/download/v2.7.1/git-lfs-linux-amd64-v2.7.1.tar.gz') + os.system('tar xvfz git-lfs-linux-amd64-v2.7.1.tar.gz') + os.system('./git-lfs install') # make lfs available in current repository + os.system('./git-lfs fetch') # download content from remote + os.system('./git-lfs checkout') # make local files to have the real content on them + # Load module from relative imports by modifying the path module_path = os.path.abspath("../..") From ebf8376bd44239c15ce19369ef6d90b4b1ed25b6 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 14:48:41 +0100 Subject: [PATCH 08/11] Formatting fixes --- docs/source/conf.py | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b6a99eff..056851ff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,12 +20,16 @@ if os.system("git lfs env > /dev/null") == 0: os.system("git lfs fetch") os.system("git lfs checkout") else: - print("Warning: it seems git lfs is not installed. Bodging our way around the problem to retrieve images...") - os.system('wget https://github.com/git-lfs/git-lfs/releases/download/v2.7.1/git-lfs-linux-amd64-v2.7.1.tar.gz') - os.system('tar xvfz git-lfs-linux-amd64-v2.7.1.tar.gz') - os.system('./git-lfs install') # make lfs available in current repository - os.system('./git-lfs fetch') # download content from remote - os.system('./git-lfs checkout') # make local files to have the real content on them + print( + "Warning: it seems git lfs is not installed. Bodging our way around the problem to retrieve images..." + ) + os.system( + "wget https://github.com/git-lfs/git-lfs/releases/download/v2.7.1/git-lfs-linux-amd64-v2.7.1.tar.gz" + ) + os.system("tar xvfz git-lfs-linux-amd64-v2.7.1.tar.gz") + os.system("./git-lfs install") # make lfs available in current repository + os.system("./git-lfs fetch") # download content from remote + os.system("./git-lfs checkout") # make local files to have the real content on them # Load module from relative imports by modifying the path @@ -47,15 +51,15 @@ class Mock(MagicMock): mock_imports = [ - "picamerax", - "picamerax.array", - "picamerax.mmalobj", - "numpy", - "labthings", + "picamerax", + "picamerax.array", + "picamerax.mmalobj", + "numpy", + "labthings", "labthings.json", - "expiringdict", - "dateutil", - "dateutil.parser", + "expiringdict", + "dateutil", + "dateutil.parser", "typing_extensions", "PIL", "sangaboard", From f0fcd534878eb3a68b70b5d66ecd85b8743087cb Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 15:41:29 +0100 Subject: [PATCH 09/11] Update link to openapi documentation --- docs/source/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index f2ffdac2..5e0e9346 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -6,7 +6,7 @@ Live documentation Full, interactive Swagger documentation for your microscopes web API is available from the microscope itself. From any browser, go to ``http://{your microscope IP address}/api/v2/docs/swagger-ui``. -The API is described in an OpenAPI description, available at ``http://{your microscope IP address}/api/v2/docs/openapi.yaml``. It is also available from our `build server`_. It can be conveniently viewed using Redoc, for example `link to test OpenAPI rendering`_ +The API is described in an OpenAPI description, available at ``http://{your microscope IP address}/api/v2/docs/openapi.yaml``. It is also available from our `build server`_. It can be conveniently viewed using `Redoc's online preview`_. .. _`build server`: https://build.openflexure.org/openflexure-microscope-server/ -.. _`link to test OpenAPI rendering`: https://redocly.github.io/redoc/?url=https://build.openflexure.org/temp/rwb34/swagger.yaml \ No newline at end of file +.. _`Redoc's online preview`: https://redocly.github.io/redoc/?url=https://build.openflexure.org/openflexure-microscope-server/latest-api.yaml \ No newline at end of file From 3971a92a5f79b13e794a0f6c101bd65bb492e5f9 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 17:38:15 +0100 Subject: [PATCH 10/11] Install more dependencies This commit fixes a couple of errors in the Sphinx docs, by removing mock imports and replacing them with real ones. --- docs/requirements.txt | 10 +++++++++- docs/source/conf.py | 10 ---------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 52b04f2e..af0098a3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,9 @@ -sphinx_rtd_theme \ No newline at end of file +sphinx_rtd_theme +numpy +labthings +expiringdict +sangaboard +typing_extensions +pillow +piexif +python-dateutil \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 056851ff..a59f7712 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -54,16 +54,6 @@ mock_imports = [ "picamerax", "picamerax.array", "picamerax.mmalobj", - "numpy", - "labthings", - "labthings.json", - "expiringdict", - "dateutil", - "dateutil.parser", - "typing_extensions", - "PIL", - "sangaboard", - "piexif", ] sys.modules.update((mod_name, Mock()) for mod_name in mock_imports) From 67b57727f62b819745a0a8d1bc61bd3c0ba6a01f Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 21 Sep 2021 17:45:17 +0100 Subject: [PATCH 11/11] Format fixes --- docs/source/conf.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a59f7712..9fcccac4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,11 +50,7 @@ class Mock(MagicMock): return MagicMock() -mock_imports = [ - "picamerax", - "picamerax.array", - "picamerax.mmalobj", -] +mock_imports = ["picamerax", "picamerax.array", "picamerax.mmalobj"] sys.modules.update((mod_name, Mock()) for mod_name in mock_imports)