Merge pull request #164 from allen-cell-animated/feature/1.6-docs

Feature/1.6 docs
allen-cell-animated · Feb 14, 2024 · 7fb2b81 · 7fb2b81
2 parents b0ab640 + f52cd3c
commit 7fb2b81
Show file tree

Hide file tree

Showing 8 changed files with 90 additions and 65 deletions.
diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml
@@ -7,7 +7,7 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - uses: ammaraskar/sphinx-action@master
@@ -18,44 +18,36 @@ jobs:
           docs-folder: "docs/"
           pre-build-command: "apt-get --allow-releaseinfo-change update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
           build-command: "make latexpdf"
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationHTML
           path: docs/_build/html/
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
-          name: agave-macos
-          path: docs/_build/latex/agave.pdf
-      - uses: actions/upload-artifact@v3
-        with:
-          name: agave-win
+          name: DocumentationPDF
           path: docs/_build/latex/agave.pdf
   docs_pythonclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - uses: ammaraskar/sphinx-action@master
         with:
+          pre-build-command: "pip install -e agave_pyclient/"
           docs-folder: "agave_pyclient/docs/"
-          pre-build-command: "pip install -e ./agave_pyclient"
       - uses: ammaraskar/sphinx-action@master
         with:
           docs-folder: "agave_pyclient/docs/"
-          pre-build-command: "pip install -e ./agave_pyclient && apt-get --allow-releaseinfo-change update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
+          pre-build-command: "pip install -e agave_pyclient/ && apt-get --allow-releaseinfo-change update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
           build-command: "make latexpdf"
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationPythonClientHTML
           path: agave_pyclient/docs/_build/html/
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
-          name: agave-macos
-          path: agave_pyclient/docs/_build/latex/agave_pyclient.pdf
-      - uses: actions/upload-artifact@v3
-        with:
-          name: agave-win
+          name: DocumentationPythonClientPDF
           path: agave_pyclient/docs/_build/latex/agave_pyclient.pdf
   cmake-build:
     strategy:
@@ -66,7 +58,7 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - name: Install Qt
@@ -98,7 +90,7 @@ jobs:
         shell: bash
       - name: Upload mac artifact
         if: matrix.os == 'macos-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: agave-macos
           path: ./build/agave-macos.zip
@@ -150,20 +142,20 @@ jobs:
         shell: cmd
       - name: Upload windows artifact
         if: matrix.os == 'windows-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: agave-win
           path: ./build/agave-win.zip
 
   lint-and-test-webclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version: 20
           registry-url: https://registry.npmjs.org/
       - run: |
           cd webclient
@@ -175,11 +167,11 @@ jobs:
   lint-and-test-pyclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - name: Install Dependencies
         run: |
           python -m pip install --upgrade pip

diff --git a/.github/workflows/tagged_master_release.yml b/.github/workflows/tagged_master_release.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - name: Install Qt
@@ -45,7 +45,7 @@ jobs:
         shell: bash
       - name: Upload mac artifact
         if: matrix.os == 'macos-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: agave-macos
           path: ./build/agave-macos.zip
@@ -98,20 +98,20 @@ jobs:
         shell: cmd
       - name: Upload windows artifact
         if: matrix.os == 'windows-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: agave-win
           path: ./build/agave-win.zip
 
   publish_webclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version: 20
           registry-url: https://registry.npmjs.org/
       - run: |
           cd webclient
@@ -124,13 +124,13 @@ jobs:
   publish_pythonclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
-      - name: Install Python 3.9 version
-        uses: actions/setup-python@v4
+      - name: Install Python
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.10"
           architecture: "x64"
       - name: Install Dependencies
         run: |
@@ -145,12 +145,12 @@ jobs:
         with:
           user: __token__
           password: ${{ secrets.PYPI_TOKEN }}
-          packages_dir: agave_pyclient/dist/
+          packages-dir: agave_pyclient/dist/
           verbose: true
   docs_pythonclient:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - run: |
@@ -165,26 +165,26 @@ jobs:
           docs-folder: "agave_pyclient/docs/"
           pre-build-command: "pip install -e ./agave_pyclient && apt-get --allow-releaseinfo-change update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
           build-command: "make latexpdf"
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationPythonClientHTML
           path: agave_pyclient/docs/_build/html/
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationPythonClientPDF
           path: agave_pyclient/docs/_build/latex/agave_pyclient.pdf
       - name: Publish Docs
-        uses: JamesIves/github-pages-deploy-action@4.1.4
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
-          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+          token: ${{ secrets.ACCESS_TOKEN }}
           branch: gh-pages # The branch the action should deploy to.
           folder: agave_pyclient/docs/_build/html/ # The folder the action should deploy.
           target-folder: agave_pyclient/
           clean: false
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
       - uses: ammaraskar/sphinx-action@master
@@ -195,18 +195,18 @@ jobs:
           docs-folder: "docs/"
           pre-build-command: "apt-get --allow-releaseinfo-change update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
           build-command: "make latexpdf"
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationHTML
           path: docs/_build/html/
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: DocumentationPDF
           path: docs/_build/latex/agave.pdf
       - name: Publish Docs
-        uses: JamesIves/github-pages-deploy-action@4.1.4
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
-          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+          token: ${{ secrets.ACCESS_TOKEN }}
           branch: gh-pages # The branch the action should deploy to.
           folder: docs/_build/html/ # The folder the action should deploy.
           clean: false
@@ -223,17 +223,17 @@ jobs:
           echo ${GITHUB_REF/refs\/tags\/v/}
           echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\/v/}
       - name: Get mac build artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: agave-macos
           path: agave-macos
       - name: Get windows build artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: agave-win
           path: agave-win
       - name: Get PDF documentation build artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: DocumentationPDF
           path: DocumentationPDF

diff --git a/agave_app/Controls.cpp b/agave_app/Controls.cpp
@@ -405,10 +405,10 @@ QIntSlider::QIntSlider(QWidget* pParent /*= NULL*/)
     this->m_spinner.setValue(v);
     this->m_spinner.blockSignals(false);
   });
-  // keep slider and spinner in sync
-  QObject::connect(&m_slider, &QSlider::sliderReleased, [this]() {
+  // note that m_slider's tracking state controls how often the valueChanged signal is emitted.
+  QObject::connect(&m_slider, &QSlider::valueChanged, [this](int v) {
     this->m_spinner.blockSignals(true);
-    this->m_spinner.setValue(this->m_slider.value());
+    this->m_spinner.setValue(v);
     this->m_spinner.blockSignals(false);
   });
 

diff --git a/agave_pyclient/docs/requirements.txt b/agave_pyclient/docs/requirements.txt
@@ -1,3 +1,2 @@
 m2r2
 sphinx_rtd_theme
-
diff --git a/docs/agave.rst b/docs/agave.rst
@@ -127,6 +127,12 @@ Subregion
 For OME-Zarr data, you may select a sub-region in X, Y, and Z. This is useful for loading a subset of a large dataset.
 A typical usage might be to first load a very low resolution level and then select a sub-region of interest to then load at a higher resolution.
 
+Keep Current AGAVE Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have already loaded a volume file and have made changes to the appearance, channel intensities, lighting, etc., you can choose to keep those settings when loading a new volume file.
+This is useful if you are loading several images consecutively that have similar channels and dimensions, and want to apply a consistent appearance to each.
+
 Adjusting the camera view
 -------------------------
 
@@ -249,6 +255,16 @@ Click the checkbox to show or hide a bounding box line around the volume data.
 Clicking on the color square allows you to select a color for the bounding
 box lines.
 
+Scale Bar
+^^^^^^^^^
+
+Click the checkbox to show or hide a scale bar at the bottom right corner
+of the display.  In a perspective camera, due to foreshortening, the
+scale bar will represent the distance between tickmarks shown on the 
+bounding box of the volume.  You will have to have the bounding box turned on
+in order to see it.  The scale bar will use physical units if available 
+in the loaded volume data.
+
 Volume Scale
 ~~~~~~~~~~~~
 
@@ -286,6 +302,17 @@ These three coordinates let you position the light anywhere on a sphere
 around the volume. Theta and Phi are in radians (where 3.14159 radians
 is half a circle).
 
+Viewport controls
+^^^^^^^^^^^^^^^^^
+
+If you check "Viewport controls" (or press the R key), an
+interactive rotation widget will appear in the viewport.  You can click
+and drag on the widget to rotate the light direction around the volume.
+If you click on the colored lines of the axes, rotation will be 
+constrained to that axis.  Press R again or uncheck the checkbox to
+hide the rotate manipulator.
+
+
 |image0|
 
 Area Light Size
@@ -489,7 +516,7 @@ Camera Panel
 The camera panel controls will let you affect the image's exposure
 amount, and control the focus blurring.
 
-Film Exposure
+Exposure
 ~~~~~~~~~~~~~
 
 The exposure value will brighten or darken the overall image.
@@ -518,7 +545,7 @@ focus. A small aperture size will keep the entire image in focus at all
 times. A large aperture size will let you only focus on a thin plane a
 specific distance from the camera.
 
-Projection Field of View
+Field of View
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The field of view is an angle in degrees describing how narrow or wide
@@ -542,11 +569,11 @@ Time Panel
 
 For time series data, move the time
 slider or change the numeric input to load a new time sample. Beware
-that this is loading a whole new volume and can take some time. If your
-dataset only has a single time, then the slider will have no effect.
-Nothing will be loaded while dragging the
-slider; AGAVE will load the new time sample when the slider is released
-or the numeric input is incremented.
+that this is loading a whole new volume and can take some time. Nothing
+will be loaded while dragging the slider; AGAVE will load the new time
+sample when the slider is released or the numeric input is incremented.
+If your dataset only has a single time, then the Time Panel will be
+hidden.
 
 
 Python Interface

diff --git a/docs/index.rst b/docs/index.rst
@@ -11,7 +11,7 @@ Advanced GPU Accelerated Volume Explorer
 
 AGAVE is a desktop application for viewing multichannel volume data.
 
-AGAVE’s core viewing engine uses a "progressive path tracer". During interactive use, your image will appear grainy at first, but will refine over time as the rendering system builds up more and more render passes. The speed of refinement depends on your hardware, the size and complexity of the image, and the AGAVE parameters you set, i.e., the faster your GPU, the quicker a rendering will resolve. GPU memory dictates the maximum size of the files AGAVE can load. As soon as you change any viewing parameter, including your camera angle, the rendering will start over.
+AGAVE's core viewing engine uses a "progressive path tracer". During interactive use, your image will appear grainy at first, but will refine over time as the rendering system builds up more and more render passes. The speed of refinement depends on your hardware, the size and complexity of the image, and the AGAVE parameters you set, i.e., the faster your GPU, the quicker a rendering will resolve. GPU memory dictates the maximum size of the files AGAVE can load. As soon as you change any viewing parameter, including your camera angle, the rendering will start over.
 
 .. toctree::
    :includehidden:
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,2 @@
		m2r2
Check warning on line 1 in agave_pyclient/docs/requirements.txt View workflow job for this annotation GitHub Actions / docs_pythonclient `document isn't included in any toctree`
		sphinx_rtd_theme