Merge pull request #26 from bonsai-rx/docs-dev

Update docs to latest docfx infrastructure and theme

.bonsai/Bonsai.config

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<PackageConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <Packages>
+    <Package id="Bonsai" version="2.8.3" />
+    <Package id="Bonsai.Core" version="2.8.2" />
+    <Package id="Bonsai.Design" version="2.8.1" />
+    <Package id="Bonsai.Editor" version="2.8.2" />
+    <Package id="jacobslusser.ScintillaNET" version="3.6.3" />
+    <Package id="Markdig" version="0.18.1" />
+    <Package id="Microsoft.Web.WebView2" version="1.0.1823.32" />
+    <Package id="Rx-Core" version="2.2.5" />
+    <Package id="Rx-Interfaces" version="2.2.5" />
+    <Package id="Rx-Linq" version="2.2.5" />
+    <Package id="Rx-PlatformServices" version="2.2.5" />
+    <Package id="SvgNet" version="3.3.3" />
+    <Package id="YamlDotNet" version="13.1.1" />
+  </Packages>
+  <AssemblyReferences>
+    <AssemblyReference assemblyName="Bonsai" />
+    <AssemblyReference assemblyName="Bonsai.Core" />
+    <AssemblyReference assemblyName="Bonsai.Design" />
+    <AssemblyReference assemblyName="Bonsai.Editor" />
+  </AssemblyReferences>
+  <AssemblyLocations>
+    <AssemblyLocation assemblyName="Bonsai" processorArchitecture="MSIL" location="Packages\Bonsai.2.8.3\lib\net48\Bonsai.exe" />
+    <AssemblyLocation assemblyName="Bonsai.Core" processorArchitecture="MSIL" location="Packages\Bonsai.Core.2.8.2\lib\net462\Bonsai.Core.dll" />
+    <AssemblyLocation assemblyName="Bonsai.Design" processorArchitecture="MSIL" location="Packages\Bonsai.Design.2.8.1\lib\net462\Bonsai.Design.dll" />
+    <AssemblyLocation assemblyName="Bonsai.Editor" processorArchitecture="MSIL" location="Packages\Bonsai.Editor.2.8.2\lib\net472\Bonsai.Editor.dll" />
+    <AssemblyLocation assemblyName="Markdig" processorArchitecture="MSIL" location="Packages\Markdig.0.18.1\lib\net40\Markdig.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.Core" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.Core.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.WinForms" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.WinForms.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.Wpf" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.Wpf.dll" />
+    <AssemblyLocation assemblyName="ScintillaNET" processorArchitecture="MSIL" location="Packages\jacobslusser.ScintillaNET.3.6.3\lib\net40\ScintillaNET.dll" />
+    <AssemblyLocation assemblyName="SVG" processorArchitecture="MSIL" location="Packages\SvgNet.3.3.3\lib\net462\SVG.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Core" processorArchitecture="MSIL" location="Packages\Rx-Core.2.2.5\lib\net45\System.Reactive.Core.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Interfaces" processorArchitecture="MSIL" location="Packages\Rx-Interfaces.2.2.5\lib\net45\System.Reactive.Interfaces.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Linq" processorArchitecture="MSIL" location="Packages\Rx-Linq.2.2.5\lib\net45\System.Reactive.Linq.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.PlatformServices" processorArchitecture="MSIL" location="Packages\Rx-PlatformServices.2.2.5\lib\net45\System.Reactive.PlatformServices.dll" />
+    <AssemblyLocation assemblyName="YamlDotNet" processorArchitecture="MSIL" location="Packages\YamlDotNet.13.1.1\lib\net47\YamlDotNet.dll" />
+  </AssemblyLocations>
+  <LibraryFolders>
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-arm64\native" platform="arm64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-arm64\native_uap" platform="arm64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x64\native" platform="x64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x64\native_uap" platform="x64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x86\native" platform="x86" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x86\native_uap" platform="x86" />
+  </LibraryFolders>
+</PackageConfiguration>

.bonsai/NuGet.config

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <add key="Gallery" value="Gallery" />
+    <add key="Bonsai Packages" value="https://www.myget.org/F/bonsai/api/v3/index.json" />
+    <add key="Community Packages" value="https://www.myget.org/F/bonsai-community/api/v3/index.json" />
+  </packageSources>
+</configuration>

.bonsai/Setup.ps1

@@ -0,0 +1,21 @@
+Push-Location $PSScriptRoot
+if (!(Test-Path "./Bonsai.exe")) {
+    $release = "https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip"
+    $configPath = "./Bonsai.config"
+    if (Test-Path $configPath) {
+        [xml]$config = Get-Content $configPath
+        $bootstrapper = $config.PackageConfiguration.Packages.Package.where{$_.id -eq 'Bonsai'}
+        if ($bootstrapper) {
+            $version = $bootstrapper.version
+            $release = "https://github.com/bonsai-rx/bonsai/releases/download/$version/Bonsai.zip"
+        }
+    }
+    Invoke-WebRequest $release -OutFile "temp.zip"
+    Move-Item -Path "NuGet.config" "temp.config" -ErrorAction SilentlyContinue
+    Expand-Archive "temp.zip" -DestinationPath "." -Force
+    Move-Item -Path "temp.config" "NuGet.config" -Force -ErrorAction SilentlyContinue
+    Remove-Item -Path "temp.zip"
+    Remove-Item -Path "Bonsai32.exe"
+}
+& .\Bonsai.exe --no-editor
+Pop-Location

.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.75.3",
+      "commands": [
+        "docfx"
+      ]
+    }
+  }
+}

.github/workflows/docs.yml

@@ -8,30 +8,40 @@ jobs:
   build:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
-
+      - name: Checkout
+        uses: actions/[email protected]
+        with:
+          submodules: true
+
+      - name: Setup .NET Core SDK
+        uses: actions/[email protected]
+        with:
+          dotnet-version: 7.x
+
       - name: Setup MSBuild
-        uses: microsoft/setup-msbuild@v1
-
+        uses: microsoft/setup-msbuild@v2
+        
       - name: Restore NuGet Packages
-        run: msbuild -t:restore src\Bonsai.Sleap.sln
+        run: msbuild -t:restore src/Bonsai.Sleap.sln
 
+      - name: Build Solution
+        run: msbuild src/Bonsai.Sleap.sln /p:Configuration=Release
+
       - name: Setup DocFX
-        uses: crazy-max/ghaction-chocolatey@v1
-        with:
-          args: install docfx
+        run: dotnet tool restore
 
+      - name: Setup Bonsai
+        working-directory: .bonsai
+        run: ./Setup.ps1
+
       - name: Build Documentation
-        run: docfx docs/docfx.json
-
-      - name: Checkout gh-pages
-        uses: actions/checkout@v2
-        with:
-          ref: gh-pages
-          path: gh-pages
+        working-directory: docs
+        run: ./build.ps1
+
       - name: Publish to github pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v3.9.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: docs/_site
+          publish_branch: gh-pages
           force_orphan: true

.gitignore

@@ -6,3 +6,10 @@ obj
 *.layout
 movies
 models
+
+# bonsai environment
+Packages
+*.dll
+*.exe
+*.exe.old
+*.exe.settings

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "docs/bonsai"]
+	path = docs/bonsai
+	url = https://github.com/bonsai-rx/docfx-tools
+[submodule "docs/assets"]
+	path = docs/assets
+	url = https://github.com/bonsai-rx/docfx-assets

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Bonsai Foundation CIC
+Copyright (c) 2024 Bonsai Foundation CIC and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

docs/articles/manual.md

@@ -1,23 +1,42 @@
 How to use
 ==========
 
-`Bonsai.SLEAP` currently implements real-time inference on four distinct SLEAP networks through their corresponding Bonsai `Predict` operators.
+`Bonsai.Sleap` currently implements real-time inference on four distinct SLEAP networks through their corresponding Bonsai `Predict` operators.
 
-![SleapOperators](~/images/SleapSchematic.svg)
+```mermaid
+flowchart TD
 
-In order to use the `Predict` operators, you will need to provide the `ModelFileName` to the exported .pb file folder containing your pre-trained SLEAP model, along with the corresponding `PoseConfigFileName` to the `training_config.json` file.
+id1("`**IplImage**`") --> id7(Multiple Instances)
+
+id1 --> id8(Single Instance)
+
+id7 -- centroid --> id3("`**PredictCentroids** 
+
+Returns multiple: 
+*Centroid*`")
+
+id7 -- top-down-model --> id4("`**PredictPoses**
 
-The simplest Bonsai workflow for running the complete model will thus be:
+Returns multiple:
+*Centroid*, *Pose*`")
 
-:::workflow
-![PredictPoseIdentities](~/workflows/PredictPoseIdentities.bonsai)
-:::
 
-If everything works out, you should see some indication in the Bonsai command line window that the GPU was successfully detected and enabled. The first frame will cold start the inference graph and this may take a bit of time, but after that, your poses should start streaming through!
+id7 -- top-down-id-model --> id5("`**PredictPoseIdentities**
+
+Returns multiple:
+*Centroid*, *Pose*, *Identity*`")
+
+id8 -- single_instance --> id2("`**PredictSinglePose**
+
+Returns single:
+*Pose*`")
+```
+
+In order to use the `Predict` operators, you will need to provide the `ModelFileName` to the exported .pb file folder containing your pre-trained SLEAP model, along with the corresponding `PoseConfigFileName` to the `training_config.json` file.
 
-![Bonsai_Pipeline_expanded](~/images/demo.gif)
+[!include[Introduction](~/articles/sleap-intro.md)]
 
-Working examples for each of these operators can be found in the extended description for each operator, which we cover below.
+Working examples for each of these operators can be found in the extended descriptions, which we cover below.
 
 ## PredictCentroids
 [!include[PredictCentroids](~/articles/sleap-predictcentroids.md)]

docs/articles/sleap-intro.md

@@ -0,0 +1,13 @@
+---
+uid: sleap-intro
+---
+
+The simplest Bonsai workflow for running the complete SLEAP `top-down-id-model` is:
+
+:::workflow
+![PredictPoseIdentities](~/workflows/PredictPoseIdentities.bonsai)
+:::
+
+If everything works out, you should see some indication in the Bonsai command line window that the GPU was successfully detected and enabled. The first frame will cold start the inference graph and this may take a bit of time, but after that, your poses should start streaming through!
+
+![Bonsai_Pipeline_expanded](~/images/demo.gif)

docs/articles/sleap-predictcentroids.md

@@ -3,7 +3,7 @@ uid: sleap-predictcentroids
 title: PredictCentroids
 ---
 
-[`PredictCentroids`](xref:Bonsai.Sleap.PredictCentroids) implements the [*centroid* network](https://sleap.ai/develop/api/sleap.nn.config.model.html?highlight=centroid#sleap.nn.config.model.CentroidsHeadConfig). This operator is most commonly used to find a set of candidate centroids from a full-resolution image. For each frame, it will return a [`CentroidCollection`](xref:Bonsai.Sleap.CentroidCollection) that can be further indexed to access the individual instances.
+[`PredictCentroids`](xref:Bonsai.Sleap.PredictCentroids) implements the [*centroid* network](https://sleap.ai/develop/api/sleap.nn.config.model.html?highlight=centroid#sleap.nn.config.model.CentroidsHeadConfig). This model is most commonly used to find a set of candidate centroids from a full-resolution image. For each frame, it will return a [`CentroidCollection`](xref:Bonsai.Sleap.CentroidCollection) which can be further indexed to access the individual instances.
 
 As an example application, the output of this operator is also fully compatible with the [`CropCenter`](xref:Bonsai.Vision.CropCenter) transform node, which can be used to easily generate smaller crops centered on the detected centroid instance (i.e. [`Centroid`](xref:Bonsai.Sleap.Centroid))
 

docs/articles/sleap-predictposeidentities.md

@@ -3,8 +3,9 @@ uid: sleap-predictposeidentities
 title: PredictPoseIdentities
 ---
 
-[`PredictPoseIdentities`](xref:Bonsai.Sleap.PredictPoseIdentities) evaluates the full SLEAP model network. In addition to extracting pose information for each detected instance in the image, it also returns the inferred identity of the object (i.e. it implements a [*top-down-id-model* network](https://sleap.ai/develop/api/sleap.nn.config.model.html#sleap.nn.config.model.MultiClassTopDownConfig).
-In addition to the properties of the [`Pose`](xref:Bonsai.Sleap.Pose) object, the extended [`PoseIdentity`](xref:Bonsai.Sleap.PoseIdentity) class adds the [`Identity`](xref:Bonsai.Sleap.PoseIdentity.Identity) property that corresponds to the highest confidence identity. This will match one of the class labels found in `training_config.json`.
+[`PredictPoseIdentities`](xref:Bonsai.Sleap.PredictPoseIdentities) evaluates the full SLEAP model network. In addition to extracting pose information for each detected instance in the image, it also returns the inferred identity of the object, i.e. it performs inference on the [*top-down-id-model* network](https://sleap.ai/develop/api/sleap.nn.config.model.html#sleap.nn.config.model.MultiClassTopDownConfig).
+
+In addition to the properties of the [`Pose`](xref:Bonsai.Sleap.Pose) object, the extended [`PoseIdentity`](xref:Bonsai.Sleap.PoseIdentity) class adds [`Identity`](xref:Bonsai.Sleap.PoseIdentity.Identity) property that indicates the highest confidence identity. This will match one of the class labels found in `training_config.json`. The [`IdentityScores`](xref:Bonsai.Sleap.PoseIdentity.IdentityScores) property indicates the confidence values for all class labels.
 
 Since we are very often only interested in the instance with the highest identification confidence we have added the operator [`GetMaximumConfidencePoseIdentity`](xref:Bonsai.Sleap.GetMaximumConfidencePoseIdentity) which returns the [`PoseIdentity`](xref:Bonsai.Sleap.PoseIdentity) with the highest confidence from the input [`PoseIdentityCollection`](xref:Bonsai.Sleap.PoseIdentityCollection). Moreover, by specifying a value in the optional [`Identity`](xref:Bonsai.Sleap.GetMaximumConfidencePoseIdentity.Identity) property, the operator will return the instance will the highest confidence for that particular class.
 

docs/articles/sleap-predictsinglepose.md

@@ -11,4 +11,4 @@ The following example workflow highlights how combining [basic computer-vision a
 ![SingleInstanceModel](~/workflows/SingleInstanceModel.bonsai)
 :::
 
-Finally, it is worth noting that [`PredictSinglePose`](xref:Bonsai.Sleap.PredictSinglePose) affords two input overloads. When receiving a single image it will output a corresponding [`Pose`](xref:Bonsai.Sleap.Pose). Since the operator skips the centroid-detection stage, it won't embed a [`Centroid`](xref:Bonsai.Sleap.Centroid) field in[`Pose`](xref:Bonsai.Sleap.Pose). Alternatively, a *batch* mode can be accessed by providing an array of images to the operator, instead returning [`PoseCollection`](xref:Bonsai.Sleap.PoseCollection). This latter overload results in dramatic performance gains relative to single images.
+Finally, it is worth noting that [`PredictSinglePose`](xref:Bonsai.Sleap.PredictSinglePose) affords two input overloads. When receiving a single image it will output a corresponding [`Pose`](xref:Bonsai.Sleap.Pose). Since the operator skips the centroid-detection stage, it won't embed a [`Centroid`](xref:Bonsai.Sleap.Centroid) field in [`Pose`](xref:Bonsai.Sleap.Pose). Alternatively, a *batch* mode can be accessed by providing an array of images to the operator, instead returning [`PoseCollection`](xref:Bonsai.Sleap.PoseCollection). This latter overload results in dramatic performance gains relative to single images.

docs/articles/toc.yml

@@ -1,6 +1,2 @@
-- name: Getting Started
-  items:
-  - name: Quickstart
-    href: intro.md
-  - name: How to use
-    href: manual.md
+- href: ../index.md
+- href: manual.md

docs/build.ps1

@@ -0,0 +1,2 @@
+.\bonsai\modules\Export-Image.ps1 "..\src\Bonsai.Sleap.Design\bin\Release\net472"
+dotnet docfx @args