From 9b636da0d5094b9febdcd10d8b9140a457aa37f5 Mon Sep 17 00:00:00 2001
From: We-Gold <we.goldm@gmail.com>
Date: Wed, 7 Aug 2024 17:58:29 +0000
Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20We-Gold/?=
 =?UTF-8?q?ouroboros@4358ebc1c502698c03bd7d7d2c8371d68882c798=20?=
 =?UTF-8?q?=F0=9F=9A=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 guide/backproject/index.html | 17 ++++++++++++++++-
 guide/downloading/index.html |  7 ++++---
 guide/slicing/index.html     | 24 +++++++++++++++++++++++-
 index.html                   |  4 ++--
 search/search_index.json     |  2 +-
 5 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/guide/backproject/index.html b/guide/backproject/index.html
index bf5dbf3..0bfe508 100644
--- a/guide/backproject/index.html
+++ b/guide/backproject/index.html
@@ -381,7 +381,7 @@
 <nav>
     <ul>
         <li><a href="#backprojection">Backprojection</a></li>
-        <li><a href="#using-the-backproject-page">Using the Backproject Page</a></li><li><a href="#how-does-backprojection-work">How Does Backprojection Work?</a></li>
+        <li><a href="#using-the-backproject-page">Using the Backproject Page</a></li><li><a href="#slicing-options">Slicing Options</a></li><li><a href="#how-does-backprojection-work">How Does Backprojection Work?</a></li>
     </ul>
 </nav>
 </aside>
@@ -406,6 +406,21 @@ <h3 id="using-the-backproject-page">Using the Backproject Page</h3>
 <p><strong>Output Position Offset</strong></p>
 <p>By default, the slicing output tiff image is backprojected into the space of its minimum bounding box, rather than the space of the entire source scan.</p>
 <p>The offset of the minimum bounding box is stored in the output tiff's description metadata. It is also stored in the configuration file (which is modified by the backproject step).</p>
+<h3 id="slicing-options">Slicing Options</h3>
+<p>📁 - Drag and drop files from File Explorer panel into this option.</p>
+<ul>
+<li>📁 <code>Straightened Volume File</code> - Path to the volume of slices to backproject (e.g. the output tif of the slicing step).</li>
+<li>📁 <code>Slice Configuration File</code> - Path to the <code>-configuration.json</code> file which includes information generated during slicing needed for backprojection.</li>
+<li>📁 <code>Output File Folder</code> - The folder to save all the resulting files into.</li>
+<li><code>Output File Name</code> - Base name for all output files.</li>
+<li><code>Output MIP Level</code> - The mip level to output the backprojection in (essentially an upsample option). Use this if you downsampled in the slicing step.</li>
+<li><code>Upsample Order</code> - The interpolation order Ouroboros uses to interpolate values from a lower MIP level. If you check the binary option, feel free to set this to 0.</li>
+<li><code>Backprojection Compression</code> - The compression option to use for the backprojected tiff(s). Recommended options: <code>none</code>, <code>zlib</code>, <code>zstd</code>.</li>
+<li><code>Output Single File</code> - Whether to output one tiff stack file or a folder of files.</li>
+<li><code>Output Min Bounding Box</code> - Save only the minimum volume needed to contain the backprojected slices. The offset will be stored in the <code>-configuration.json</code> file under <code>backprojection_offset</code>. This value is the (x_min, y_min, z_min).</li>
+<li><code>Binary Backprojection</code> - Whether or not to binarize all the values of the backprojection. Enable this to backproject a segmentation.</li>
+<li><code>Max RAM (GB)</code> - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM.</li>
+</ul>
 <h3 id="how-does-backprojection-work">How Does Backprojection Work?</h3>
 <p>A large amount of helpful data is saved in <code>*-configuration.json</code> file after the slicing process. This data contains all of the rectangle corners from slicing, and the bounding boxes the slices are associated with. With this data, Ouroboros recalculates the 2D coordinate grids of 3D points for each slice.</p>
 <p><strong>Trilinear Interpolation</strong></p>
diff --git a/guide/downloading/index.html b/guide/downloading/index.html
index da25900..a335b24 100644
--- a/guide/downloading/index.html
+++ b/guide/downloading/index.html
@@ -388,15 +388,16 @@
             <main id="terminal-mkdocs-main-content">
 <section id="mkdocs-terminal-content">
     <h1 id="download-ouroboros">Download Ouroboros</h1>
-<p>There are prebuilt applications available in <a href="https://github.com/We-Gold/ouroboros/releases">Releases</a>.</p>
+<p><a href="https://www.docker.com/">Docker</a> <strong>is required</strong> to run Ouroboros. Make sure to install and run it before running Ouroboros.</p>
+<p>Prebuilt applications are available in <a href="https://github.com/We-Gold/ouroboros/releases">Releases</a>.</p>
 <ul>
 <li>Windows: <code>*-setup.exe</code></li>
 <li>Mac: <code>*.dmg</code></li>
 <li>Linux: Multiple options available</li>
 </ul>
-<p>When you open the app, the GUI will open immediately, but <strong>the local server that runs the processing could take up to 15 seconds to start</strong>. There is an indicator in the GUI that shows if the server is connected.</p>
+<p>When you open the app, the GUI will open immediately, but <strong>the local server that runs the processing could take up a minute to start</strong> the first time it is run. There is an indicator in the GUI that shows if the server is connected.</p>
 <p>Currently, none of the apps are notarized. </p>
-<p>For Mac, if an error occurs when you try to run the app, find the app installation (should be called <code>ouroboros.app</code>) and run <code>xattr -d com.apple.quarantine ouroboros.app</code>. </p>
+<p>For Mac, if an error occurs when you try to run the app, find the app installation (should be called <code>Ouroboros.app</code>) and run <code>xattr -d com.apple.quarantine Ouroboros.app</code>. </p>
 </section>
 
             </main>
diff --git a/guide/slicing/index.html b/guide/slicing/index.html
index b59aa1b..89cbbc9 100644
--- a/guide/slicing/index.html
+++ b/guide/slicing/index.html
@@ -381,7 +381,7 @@
 <nav>
     <ul>
         <li><a href="#slicing">Slicing</a></li>
-        <li><a href="#using-the-slice-page">Using the Slice Page</a></li><li><a href="#how-does-slicing-work">How Does Slicing Work?</a></li>
+        <li><a href="#using-the-slice-page">Using the Slice Page</a></li><li><a href="#slicing-options">Slicing Options</a></li><li><a href="#how-does-slicing-work">How Does Slicing Work?</a></li>
     </ul>
 </nav>
 </aside>
@@ -395,6 +395,28 @@ <h3 id="using-the-slice-page">Using the Slice Page</h3>
 <p><img alt="Basic Usage Demo" src="../../assets/slicing/Slice%20Page%20Demo.gif" /></p>
 <p><strong>Reusing Options from a Previous Run</strong></p>
 <p><img alt="Reusing Options from a Previous Run" src="../../assets/slicing/Slice%20Page%20Options%20Demo.gif" /></p>
+<h3 id="slicing-options">Slicing Options</h3>
+<p>📁 - Drag and drop files from File Explorer panel into this option.</p>
+<ul>
+<li>📁 <code>Neuroglancer JSON</code> - Path to the Neuroglancer configuration JSON file (exported from Neuroglancer with <code>{}</code> icon, or through the Neuroglancer Plugin)</li>
+<li><code>Neuroglancer Image Layer</code> - Select Neuroglancer image layer to slice from.</li>
+<li><code>Neuroglancer Annotation Layer</code> - Select Neuroglancer annotation layer to slice from.</li>
+<li><code>Slice Width</code> - The output width of each slice image.</li>
+<li><code>Slice Height</code> - The output height of each slice image.</li>
+<li>📁 <code>Output File Folder</code> - The folder to save all the resulting files into.</li>
+<li><code>Output File Name</code> - Base name for all output files.</li>
+<li><code>Annotation MIP Level</code> - The annotation layer's MIP level. </li>
+<li><code>Output MIP Level</code> - The mip level to output slices in (essentially a downsample option).</li>
+<li><code>Distance Between Slices</code> - The distance between each slice along the annotation path.</li>
+<li><code>Output Single File</code> - Whether to output one tiff stack file or a folder of files.</li>
+<li><code>Connect Endpoints</code> - Connect the first point in the path to the last point. This is not recommended.</li>
+<li><code>Bounding Box Parameters</code><ul>
+<li><code>Max Depth</code> - The maximum depth for binary space partitioning. It is not recommended to change this option unless you encounter RAM issues.</li>
+<li><code>Target Slices Per Box</code> - If you are running on a low-RAM system, or you are taking very large slices, you may want to decrease this.</li>
+</ul>
+</li>
+<li><code>Max RAM (GB)</code> - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM.</li>
+</ul>
 <h3 id="how-does-slicing-work">How Does Slicing Work?</h3>
 <p><strong>Spline Fitting</strong></p>
 <p>Ouroboros fits a spline curve to the annotation path from the Neuroglancer JSON file. This produces a smooth, differentiable curve along the length of the annotations. </p>
diff --git a/index.html b/index.html
index 045d302..806116d 100644
--- a/index.html
+++ b/index.html
@@ -396,9 +396,9 @@ <h1 id="ouroboros">Ouroboros</h1>
 <p><img alt="" src="assets/slicing/long-slice.png" /></p>
 <p>Extract ROIs from cloud-hosted medical scans.</p>
 <p>Ouroboros is a desktop app (built with Electron) and a Python package (with a CLI). </p>
-<p>The desktop app comes with a pre-compiled Python server (from the Python package). It runs the server in the background to handle all processing and calculations.</p>
+<p>The desktop app uses Docker to build and run its Python server. For this reason, <strong>Docker is required</strong> to run Ouroboros.</p>
 <p>If you are interested in using the Python package for its CLI or for a custom usecase, check out the <a href="https://github.com/We-Gold/ouroboros/tree/main/python">python</a> folder in the main repository.</p>
-<p>Ouroboros also supports a plugin system. A plugin usage guide is forthcoming.</p>
+<p>Ouroboros also has a <a href="guide/plugins/">Plugin System</a>. Plugin servers are also run in Docker.</p>
 <h2 id="usage-guide">Usage Guide</h2>
 <p><em>It is recommended that you read these pages in order.</em></p>
 <ul>
diff --git a/search/search_index.json b/search/search_index.json
index adb8999..71a0b8d 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Ouroboros or-uh-bore-us Extract ROIs from cloud-hosted medical scans. Ouroboros is a desktop app (built with Electron) and a Python package (with a CLI). The desktop app comes with a pre-compiled Python server (from the Python package). It runs the server in the background to handle all processing and calculations. If you are interested in using the Python package for its CLI or for a custom usecase, check out the python folder in the main repository. Ouroboros also supports a plugin system. A plugin usage guide is forthcoming. Usage Guide It is recommended that you read these pages in order. Download and Install Ouroboros Slicing Backprojection Plugins Ouroboros Explanation A user of Ouroboros may have a multi-terabyte volumetric scan, hosted with the Neuroglancer family of tools (i.e. cloud-volume ). Perhaps there is a long, relatively sparse structure (ROI), like a nerve or a blood vessel that crosses the entire scan. Even with a well-equipped computer, it would be difficult to segment the entire stucture in one pass due to RAM limitations. Ouroboros provides a solution. A user first traces the structure in Neuroglancer with sequential annotation points, and then saves the JSON configuration to a file. Ouroboros opens this configuration file and cuts rectangular slices along the annotation path, producing a straightened volume with the ROI at the center of each slice (usually much smaller than the original scan). Every tenth slice in a circular annotation path, rendered in Ouroboros's Slicing Page. From there, the user segments the much smaller straightened volume with their choice of segmentation system. Then, Ouroboros backprojects the segmented slices into the original volume space (unstraightens it), producing a full segmentation.","title":"Home"},{"location":"#ouroboros","text":"or-uh-bore-us Extract ROIs from cloud-hosted medical scans. Ouroboros is a desktop app (built with Electron) and a Python package (with a CLI). The desktop app comes with a pre-compiled Python server (from the Python package). It runs the server in the background to handle all processing and calculations. If you are interested in using the Python package for its CLI or for a custom usecase, check out the python folder in the main repository. Ouroboros also supports a plugin system. A plugin usage guide is forthcoming.","title":"Ouroboros"},{"location":"#usage-guide","text":"It is recommended that you read these pages in order. Download and Install Ouroboros Slicing Backprojection Plugins","title":"Usage Guide"},{"location":"#ouroboros-explanation","text":"A user of Ouroboros may have a multi-terabyte volumetric scan, hosted with the Neuroglancer family of tools (i.e. cloud-volume ). Perhaps there is a long, relatively sparse structure (ROI), like a nerve or a blood vessel that crosses the entire scan. Even with a well-equipped computer, it would be difficult to segment the entire stucture in one pass due to RAM limitations. Ouroboros provides a solution. A user first traces the structure in Neuroglancer with sequential annotation points, and then saves the JSON configuration to a file. Ouroboros opens this configuration file and cuts rectangular slices along the annotation path, producing a straightened volume with the ROI at the center of each slice (usually much smaller than the original scan). Every tenth slice in a circular annotation path, rendered in Ouroboros's Slicing Page. From there, the user segments the much smaller straightened volume with their choice of segmentation system. Then, Ouroboros backprojects the segmented slices into the original volume space (unstraightens it), producing a full segmentation.","title":"Ouroboros Explanation"},{"location":"guide/backproject/","text":"Backprojection After straightened volume produced by the slicing step is segmented, Ouroboros's Backproject Page can be used to project the segmentation back into the coordinate space of the original volume. Using the Backproject Page Basic Usage Demo Reusing Options from a Previous Run See the same section under Slice Page . Compression Options One of the options on the Backproject page allows the user to configure the output compression format. Common options zlib zstd none (no compression, not recommended) For more information, see Tifffile , the Python package responsible for the compression. Output Position Offset By default, the slicing output tiff image is backprojected into the space of its minimum bounding box, rather than the space of the entire source scan. The offset of the minimum bounding box is stored in the output tiff's description metadata. It is also stored in the configuration file (which is modified by the backproject step). How Does Backprojection Work? A large amount of helpful data is saved in *-configuration.json file after the slicing process. This data contains all of the rectangle corners from slicing, and the bounding boxes the slices are associated with. With this data, Ouroboros recalculates the 2D coordinate grids of 3D points for each slice. Trilinear Interpolation The straightened volume slices are loaded in as a memmap (an in-memory reference to the tiff image on the hard-drive or SSD). Then, an empty volume is created with the same dimensions as the bounding box. A custom trilinear interpolation implementation is used to copy the slice data into the empty volume. These volumes are saved to local tiff images. After all volumes have been calculated, Ouroboros creates chunks of an empty volume (same size as the original volume) and copies the data from the smaller volumes into the chunk, and then saves that chunk as a tiff with compression. Finally, all chunks are combined to produce either a minimum bounding box in the space of the original volume with all of the backprojected data, or a full-size volume with the backprojected data. Why Is Interpolation Needed? The slices in the straightened volume were originally produced through interpolation. Each slice has a 2D grid of 3D points, and the values at these points were approximated through interpolation. In order to put the data back, we have to interpolate in the opposite direction. Each point contributes to the value of its neighbors based on how close it is to them.","title":"Backprojection"},{"location":"guide/backproject/#backprojection","text":"After straightened volume produced by the slicing step is segmented, Ouroboros's Backproject Page can be used to project the segmentation back into the coordinate space of the original volume.","title":"Backprojection"},{"location":"guide/backproject/#using-the-backproject-page","text":"Basic Usage Demo Reusing Options from a Previous Run See the same section under Slice Page . Compression Options One of the options on the Backproject page allows the user to configure the output compression format. Common options zlib zstd none (no compression, not recommended) For more information, see Tifffile , the Python package responsible for the compression. Output Position Offset By default, the slicing output tiff image is backprojected into the space of its minimum bounding box, rather than the space of the entire source scan. The offset of the minimum bounding box is stored in the output tiff's description metadata. It is also stored in the configuration file (which is modified by the backproject step).","title":"Using the Backproject Page"},{"location":"guide/backproject/#how-does-backprojection-work","text":"A large amount of helpful data is saved in *-configuration.json file after the slicing process. This data contains all of the rectangle corners from slicing, and the bounding boxes the slices are associated with. With this data, Ouroboros recalculates the 2D coordinate grids of 3D points for each slice. Trilinear Interpolation The straightened volume slices are loaded in as a memmap (an in-memory reference to the tiff image on the hard-drive or SSD). Then, an empty volume is created with the same dimensions as the bounding box. A custom trilinear interpolation implementation is used to copy the slice data into the empty volume. These volumes are saved to local tiff images. After all volumes have been calculated, Ouroboros creates chunks of an empty volume (same size as the original volume) and copies the data from the smaller volumes into the chunk, and then saves that chunk as a tiff with compression. Finally, all chunks are combined to produce either a minimum bounding box in the space of the original volume with all of the backprojected data, or a full-size volume with the backprojected data. Why Is Interpolation Needed? The slices in the straightened volume were originally produced through interpolation. Each slice has a 2D grid of 3D points, and the values at these points were approximated through interpolation. In order to put the data back, we have to interpolate in the opposite direction. Each point contributes to the value of its neighbors based on how close it is to them.","title":"How Does Backprojection Work?"},{"location":"guide/downloading/","text":"Download Ouroboros There are prebuilt applications available in Releases . Windows: *-setup.exe Mac: *.dmg Linux: Multiple options available When you open the app, the GUI will open immediately, but the local server that runs the processing could take up to 15 seconds to start . There is an indicator in the GUI that shows if the server is connected. Currently, none of the apps are notarized. For Mac, if an error occurs when you try to run the app, find the app installation (should be called ouroboros.app ) and run xattr -d com.apple.quarantine ouroboros.app .","title":"Download Ouroboros"},{"location":"guide/downloading/#download-ouroboros","text":"There are prebuilt applications available in Releases . Windows: *-setup.exe Mac: *.dmg Linux: Multiple options available When you open the app, the GUI will open immediately, but the local server that runs the processing could take up to 15 seconds to start . There is an indicator in the GUI that shows if the server is connected. Currently, none of the apps are notarized. For Mac, if an error occurs when you try to run the app, find the app installation (should be called ouroboros.app ) and run xattr -d com.apple.quarantine ouroboros.app .","title":"Download Ouroboros"},{"location":"guide/plugins/","text":"Ouroboros Plugins Recommended Plugins Neuroglancer Plugin Embeds Neuroglancer as a page in the app. Supports loading from and saving to JSON configuration files in Ouroboros's File Explorer. Has additional features like fullscreen mode and screenshots. Assisted Automatic Segmentation Plugin Coming Soon! Based on Segment Anything, it attempts to automatically segment the ROI. Benefits from the assumption that the desired structure is centered in each slice. Supports human input via bounding boxes and positive or negative annotations. Installing a Plugin Open the Plugin Manager: File > Manage Plugins . Press the Plus Icon Paste the GitHub URL of the plugin. Press Download (Ouroboros downloads and installs the plugin for you) Where are plugins installed? In the appData /ouroboros folder. This folder is different on each OS. Creating a Plugin See the template README for more information.","title":"Plugins"},{"location":"guide/plugins/#ouroboros-plugins","text":"","title":"Ouroboros Plugins"},{"location":"guide/plugins/#recommended-plugins","text":"Neuroglancer Plugin Embeds Neuroglancer as a page in the app. Supports loading from and saving to JSON configuration files in Ouroboros's File Explorer. Has additional features like fullscreen mode and screenshots. Assisted Automatic Segmentation Plugin Coming Soon! Based on Segment Anything, it attempts to automatically segment the ROI. Benefits from the assumption that the desired structure is centered in each slice. Supports human input via bounding boxes and positive or negative annotations.","title":"Recommended Plugins"},{"location":"guide/plugins/#installing-a-plugin","text":"Open the Plugin Manager: File > Manage Plugins . Press the Plus Icon Paste the GitHub URL of the plugin. Press Download (Ouroboros downloads and installs the plugin for you) Where are plugins installed? In the appData /ouroboros folder. This folder is different on each OS.","title":"Installing a Plugin"},{"location":"guide/plugins/#creating-a-plugin","text":"See the template README for more information.","title":"Creating a Plugin"},{"location":"guide/slicing/","text":"Slicing Slicing is one of the primary features of Ouroboros, available in the CLI and the desktop app. Using the Slice Page Basic Usage Demo Reusing Options from a Previous Run How Does Slicing Work? Spline Fitting Ouroboros fits a spline curve to the annotation path from the Neuroglancer JSON file. This produces a smooth, differentiable curve along the length of the annotations. If the line segments between annotation points were used, then there would could be highly discontinuous slice transitions around sharp corners. Slice Coordinate Frames Ouroboros calculates equidistant points along the spline curve. Each point is \"1\" apart from the previous to match the appearance of isotropic slices taken from one of the axes of the coordinate space of the full volume (the coordinate space of the annotation points). To follow any possible path, each point must have its own coordinate frame normal to the spline. For easier segmentation, it is also important that the axes of the point coordinate frames don't flip between points. To achieve this, Ouroboros calculates rotation-minimizing frames based on the change in orientation of the tangent vectors of adjacent points. Rectangles and Grids Ouroboros calculates the corners of the slice rectangle at using each point and its associated coordinate axes (as vectors). Pseudocode width_vector # 'u' unit vector scaled to slice width / 2 height_vector # 'v' unit vector scaled to slice height / 2 top_left = point - width_vector + height_vector top_right = point + width_vector + height_vector bottom_right = point + width_vector - height_vector bottom_left = point - width_vector - height_vector Then, for each point, a 2D grid is generated with given dimensions (slice width and height). Each point in the 2D grid is a 3D point which is calculated by interpolating between the four corner points. Volumes and Trilinear Interpolation At this point, Ouroboros has a full grid of 3D points associated with each slice, but has yet to download any data from the cloud-hosted volume. To avoid downloading unnecessary data, Ouroboros employs binary space partitioning to divide the minimum bounding box of the ROI recursively until each volume contains few enough slices to fit into available RAM. Ouroboros then downloads the data for each of these bounding boxes from the cloud-hosted volume. As each download completes, a new process is spawned to handle calculations. For each volume, scipy.ndimage.map_coordinates is used to extract the values at the coordinates of the slice grids from the 3D volume using trilinear interpolation. Each of these slices are saved as local tiff images and are later combined into a single output tiff.","title":"Slicing"},{"location":"guide/slicing/#slicing","text":"Slicing is one of the primary features of Ouroboros, available in the CLI and the desktop app.","title":"Slicing"},{"location":"guide/slicing/#using-the-slice-page","text":"Basic Usage Demo Reusing Options from a Previous Run","title":"Using the Slice Page"},{"location":"guide/slicing/#how-does-slicing-work","text":"Spline Fitting Ouroboros fits a spline curve to the annotation path from the Neuroglancer JSON file. This produces a smooth, differentiable curve along the length of the annotations. If the line segments between annotation points were used, then there would could be highly discontinuous slice transitions around sharp corners. Slice Coordinate Frames Ouroboros calculates equidistant points along the spline curve. Each point is \"1\" apart from the previous to match the appearance of isotropic slices taken from one of the axes of the coordinate space of the full volume (the coordinate space of the annotation points). To follow any possible path, each point must have its own coordinate frame normal to the spline. For easier segmentation, it is also important that the axes of the point coordinate frames don't flip between points. To achieve this, Ouroboros calculates rotation-minimizing frames based on the change in orientation of the tangent vectors of adjacent points. Rectangles and Grids Ouroboros calculates the corners of the slice rectangle at using each point and its associated coordinate axes (as vectors). Pseudocode width_vector # 'u' unit vector scaled to slice width / 2 height_vector # 'v' unit vector scaled to slice height / 2 top_left = point - width_vector + height_vector top_right = point + width_vector + height_vector bottom_right = point + width_vector - height_vector bottom_left = point - width_vector - height_vector Then, for each point, a 2D grid is generated with given dimensions (slice width and height). Each point in the 2D grid is a 3D point which is calculated by interpolating between the four corner points. Volumes and Trilinear Interpolation At this point, Ouroboros has a full grid of 3D points associated with each slice, but has yet to download any data from the cloud-hosted volume. To avoid downloading unnecessary data, Ouroboros employs binary space partitioning to divide the minimum bounding box of the ROI recursively until each volume contains few enough slices to fit into available RAM. Ouroboros then downloads the data for each of these bounding boxes from the cloud-hosted volume. As each download completes, a new process is spawned to handle calculations. For each volume, scipy.ndimage.map_coordinates is used to extract the values at the coordinates of the slice grids from the 3D volume using trilinear interpolation. Each of these slices are saved as local tiff images and are later combined into a single output tiff.","title":"How Does Slicing Work?"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Ouroboros or-uh-bore-us Extract ROIs from cloud-hosted medical scans. Ouroboros is a desktop app (built with Electron) and a Python package (with a CLI). The desktop app uses Docker to build and run its Python server. For this reason, Docker is required to run Ouroboros. If you are interested in using the Python package for its CLI or for a custom usecase, check out the python folder in the main repository. Ouroboros also has a Plugin System . Plugin servers are also run in Docker. Usage Guide It is recommended that you read these pages in order. Download and Install Ouroboros Slicing Backprojection Plugins Ouroboros Explanation A user of Ouroboros may have a multi-terabyte volumetric scan, hosted with the Neuroglancer family of tools (i.e. cloud-volume ). Perhaps there is a long, relatively sparse structure (ROI), like a nerve or a blood vessel that crosses the entire scan. Even with a well-equipped computer, it would be difficult to segment the entire stucture in one pass due to RAM limitations. Ouroboros provides a solution. A user first traces the structure in Neuroglancer with sequential annotation points, and then saves the JSON configuration to a file. Ouroboros opens this configuration file and cuts rectangular slices along the annotation path, producing a straightened volume with the ROI at the center of each slice (usually much smaller than the original scan). Every tenth slice in a circular annotation path, rendered in Ouroboros's Slicing Page. From there, the user segments the much smaller straightened volume with their choice of segmentation system. Then, Ouroboros backprojects the segmented slices into the original volume space (unstraightens it), producing a full segmentation.","title":"Home"},{"location":"#ouroboros","text":"or-uh-bore-us Extract ROIs from cloud-hosted medical scans. Ouroboros is a desktop app (built with Electron) and a Python package (with a CLI). The desktop app uses Docker to build and run its Python server. For this reason, Docker is required to run Ouroboros. If you are interested in using the Python package for its CLI or for a custom usecase, check out the python folder in the main repository. Ouroboros also has a Plugin System . Plugin servers are also run in Docker.","title":"Ouroboros"},{"location":"#usage-guide","text":"It is recommended that you read these pages in order. Download and Install Ouroboros Slicing Backprojection Plugins","title":"Usage Guide"},{"location":"#ouroboros-explanation","text":"A user of Ouroboros may have a multi-terabyte volumetric scan, hosted with the Neuroglancer family of tools (i.e. cloud-volume ). Perhaps there is a long, relatively sparse structure (ROI), like a nerve or a blood vessel that crosses the entire scan. Even with a well-equipped computer, it would be difficult to segment the entire stucture in one pass due to RAM limitations. Ouroboros provides a solution. A user first traces the structure in Neuroglancer with sequential annotation points, and then saves the JSON configuration to a file. Ouroboros opens this configuration file and cuts rectangular slices along the annotation path, producing a straightened volume with the ROI at the center of each slice (usually much smaller than the original scan). Every tenth slice in a circular annotation path, rendered in Ouroboros's Slicing Page. From there, the user segments the much smaller straightened volume with their choice of segmentation system. Then, Ouroboros backprojects the segmented slices into the original volume space (unstraightens it), producing a full segmentation.","title":"Ouroboros Explanation"},{"location":"guide/backproject/","text":"Backprojection After straightened volume produced by the slicing step is segmented, Ouroboros's Backproject Page can be used to project the segmentation back into the coordinate space of the original volume. Using the Backproject Page Basic Usage Demo Reusing Options from a Previous Run See the same section under Slice Page . Compression Options One of the options on the Backproject page allows the user to configure the output compression format. Common options zlib zstd none (no compression, not recommended) For more information, see Tifffile , the Python package responsible for the compression. Output Position Offset By default, the slicing output tiff image is backprojected into the space of its minimum bounding box, rather than the space of the entire source scan. The offset of the minimum bounding box is stored in the output tiff's description metadata. It is also stored in the configuration file (which is modified by the backproject step). Slicing Options \ud83d\udcc1 - Drag and drop files from File Explorer panel into this option. \ud83d\udcc1 Straightened Volume File - Path to the volume of slices to backproject (e.g. the output tif of the slicing step). \ud83d\udcc1 Slice Configuration File - Path to the -configuration.json file which includes information generated during slicing needed for backprojection. \ud83d\udcc1 Output File Folder - The folder to save all the resulting files into. Output File Name - Base name for all output files. Output MIP Level - The mip level to output the backprojection in (essentially an upsample option). Use this if you downsampled in the slicing step. Upsample Order - The interpolation order Ouroboros uses to interpolate values from a lower MIP level. If you check the binary option, feel free to set this to 0. Backprojection Compression - The compression option to use for the backprojected tiff(s). Recommended options: none , zlib , zstd . Output Single File - Whether to output one tiff stack file or a folder of files. Output Min Bounding Box - Save only the minimum volume needed to contain the backprojected slices. The offset will be stored in the -configuration.json file under backprojection_offset . This value is the (x_min, y_min, z_min). Binary Backprojection - Whether or not to binarize all the values of the backprojection. Enable this to backproject a segmentation. Max RAM (GB) - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM. How Does Backprojection Work? A large amount of helpful data is saved in *-configuration.json file after the slicing process. This data contains all of the rectangle corners from slicing, and the bounding boxes the slices are associated with. With this data, Ouroboros recalculates the 2D coordinate grids of 3D points for each slice. Trilinear Interpolation The straightened volume slices are loaded in as a memmap (an in-memory reference to the tiff image on the hard-drive or SSD). Then, an empty volume is created with the same dimensions as the bounding box. A custom trilinear interpolation implementation is used to copy the slice data into the empty volume. These volumes are saved to local tiff images. After all volumes have been calculated, Ouroboros creates chunks of an empty volume (same size as the original volume) and copies the data from the smaller volumes into the chunk, and then saves that chunk as a tiff with compression. Finally, all chunks are combined to produce either a minimum bounding box in the space of the original volume with all of the backprojected data, or a full-size volume with the backprojected data. Why Is Interpolation Needed? The slices in the straightened volume were originally produced through interpolation. Each slice has a 2D grid of 3D points, and the values at these points were approximated through interpolation. In order to put the data back, we have to interpolate in the opposite direction. Each point contributes to the value of its neighbors based on how close it is to them.","title":"Backprojection"},{"location":"guide/backproject/#backprojection","text":"After straightened volume produced by the slicing step is segmented, Ouroboros's Backproject Page can be used to project the segmentation back into the coordinate space of the original volume.","title":"Backprojection"},{"location":"guide/backproject/#using-the-backproject-page","text":"Basic Usage Demo Reusing Options from a Previous Run See the same section under Slice Page . Compression Options One of the options on the Backproject page allows the user to configure the output compression format. Common options zlib zstd none (no compression, not recommended) For more information, see Tifffile , the Python package responsible for the compression. Output Position Offset By default, the slicing output tiff image is backprojected into the space of its minimum bounding box, rather than the space of the entire source scan. The offset of the minimum bounding box is stored in the output tiff's description metadata. It is also stored in the configuration file (which is modified by the backproject step).","title":"Using the Backproject Page"},{"location":"guide/backproject/#slicing-options","text":"\ud83d\udcc1 - Drag and drop files from File Explorer panel into this option. \ud83d\udcc1 Straightened Volume File - Path to the volume of slices to backproject (e.g. the output tif of the slicing step). \ud83d\udcc1 Slice Configuration File - Path to the -configuration.json file which includes information generated during slicing needed for backprojection. \ud83d\udcc1 Output File Folder - The folder to save all the resulting files into. Output File Name - Base name for all output files. Output MIP Level - The mip level to output the backprojection in (essentially an upsample option). Use this if you downsampled in the slicing step. Upsample Order - The interpolation order Ouroboros uses to interpolate values from a lower MIP level. If you check the binary option, feel free to set this to 0. Backprojection Compression - The compression option to use for the backprojected tiff(s). Recommended options: none , zlib , zstd . Output Single File - Whether to output one tiff stack file or a folder of files. Output Min Bounding Box - Save only the minimum volume needed to contain the backprojected slices. The offset will be stored in the -configuration.json file under backprojection_offset . This value is the (x_min, y_min, z_min). Binary Backprojection - Whether or not to binarize all the values of the backprojection. Enable this to backproject a segmentation. Max RAM (GB) - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM.","title":"Slicing Options"},{"location":"guide/backproject/#how-does-backprojection-work","text":"A large amount of helpful data is saved in *-configuration.json file after the slicing process. This data contains all of the rectangle corners from slicing, and the bounding boxes the slices are associated with. With this data, Ouroboros recalculates the 2D coordinate grids of 3D points for each slice. Trilinear Interpolation The straightened volume slices are loaded in as a memmap (an in-memory reference to the tiff image on the hard-drive or SSD). Then, an empty volume is created with the same dimensions as the bounding box. A custom trilinear interpolation implementation is used to copy the slice data into the empty volume. These volumes are saved to local tiff images. After all volumes have been calculated, Ouroboros creates chunks of an empty volume (same size as the original volume) and copies the data from the smaller volumes into the chunk, and then saves that chunk as a tiff with compression. Finally, all chunks are combined to produce either a minimum bounding box in the space of the original volume with all of the backprojected data, or a full-size volume with the backprojected data. Why Is Interpolation Needed? The slices in the straightened volume were originally produced through interpolation. Each slice has a 2D grid of 3D points, and the values at these points were approximated through interpolation. In order to put the data back, we have to interpolate in the opposite direction. Each point contributes to the value of its neighbors based on how close it is to them.","title":"How Does Backprojection Work?"},{"location":"guide/downloading/","text":"Download Ouroboros Docker is required to run Ouroboros. Make sure to install and run it before running Ouroboros. Prebuilt applications are available in Releases . Windows: *-setup.exe Mac: *.dmg Linux: Multiple options available When you open the app, the GUI will open immediately, but the local server that runs the processing could take up a minute to start the first time it is run. There is an indicator in the GUI that shows if the server is connected. Currently, none of the apps are notarized. For Mac, if an error occurs when you try to run the app, find the app installation (should be called Ouroboros.app ) and run xattr -d com.apple.quarantine Ouroboros.app .","title":"Download Ouroboros"},{"location":"guide/downloading/#download-ouroboros","text":"Docker is required to run Ouroboros. Make sure to install and run it before running Ouroboros. Prebuilt applications are available in Releases . Windows: *-setup.exe Mac: *.dmg Linux: Multiple options available When you open the app, the GUI will open immediately, but the local server that runs the processing could take up a minute to start the first time it is run. There is an indicator in the GUI that shows if the server is connected. Currently, none of the apps are notarized. For Mac, if an error occurs when you try to run the app, find the app installation (should be called Ouroboros.app ) and run xattr -d com.apple.quarantine Ouroboros.app .","title":"Download Ouroboros"},{"location":"guide/plugins/","text":"Ouroboros Plugins Recommended Plugins Neuroglancer Plugin Embeds Neuroglancer as a page in the app. Supports loading from and saving to JSON configuration files in Ouroboros's File Explorer. Has additional features like fullscreen mode and screenshots. Assisted Automatic Segmentation Plugin Coming Soon! Based on Segment Anything, it attempts to automatically segment the ROI. Benefits from the assumption that the desired structure is centered in each slice. Supports human input via bounding boxes and positive or negative annotations. Installing a Plugin Open the Plugin Manager: File > Manage Plugins . Press the Plus Icon Paste the GitHub URL of the plugin. Press Download (Ouroboros downloads and installs the plugin for you) Where are plugins installed? In the appData /ouroboros folder. This folder is different on each OS. Creating a Plugin See the template README for more information.","title":"Plugins"},{"location":"guide/plugins/#ouroboros-plugins","text":"","title":"Ouroboros Plugins"},{"location":"guide/plugins/#recommended-plugins","text":"Neuroglancer Plugin Embeds Neuroglancer as a page in the app. Supports loading from and saving to JSON configuration files in Ouroboros's File Explorer. Has additional features like fullscreen mode and screenshots. Assisted Automatic Segmentation Plugin Coming Soon! Based on Segment Anything, it attempts to automatically segment the ROI. Benefits from the assumption that the desired structure is centered in each slice. Supports human input via bounding boxes and positive or negative annotations.","title":"Recommended Plugins"},{"location":"guide/plugins/#installing-a-plugin","text":"Open the Plugin Manager: File > Manage Plugins . Press the Plus Icon Paste the GitHub URL of the plugin. Press Download (Ouroboros downloads and installs the plugin for you) Where are plugins installed? In the appData /ouroboros folder. This folder is different on each OS.","title":"Installing a Plugin"},{"location":"guide/plugins/#creating-a-plugin","text":"See the template README for more information.","title":"Creating a Plugin"},{"location":"guide/slicing/","text":"Slicing Slicing is one of the primary features of Ouroboros, available in the CLI and the desktop app. Using the Slice Page Basic Usage Demo Reusing Options from a Previous Run Slicing Options \ud83d\udcc1 - Drag and drop files from File Explorer panel into this option. \ud83d\udcc1 Neuroglancer JSON - Path to the Neuroglancer configuration JSON file (exported from Neuroglancer with {} icon, or through the Neuroglancer Plugin) Neuroglancer Image Layer - Select Neuroglancer image layer to slice from. Neuroglancer Annotation Layer - Select Neuroglancer annotation layer to slice from. Slice Width - The output width of each slice image. Slice Height - The output height of each slice image. \ud83d\udcc1 Output File Folder - The folder to save all the resulting files into. Output File Name - Base name for all output files. Annotation MIP Level - The annotation layer's MIP level. Output MIP Level - The mip level to output slices in (essentially a downsample option). Distance Between Slices - The distance between each slice along the annotation path. Output Single File - Whether to output one tiff stack file or a folder of files. Connect Endpoints - Connect the first point in the path to the last point. This is not recommended. Bounding Box Parameters Max Depth - The maximum depth for binary space partitioning. It is not recommended to change this option unless you encounter RAM issues. Target Slices Per Box - If you are running on a low-RAM system, or you are taking very large slices, you may want to decrease this. Max RAM (GB) - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM. How Does Slicing Work? Spline Fitting Ouroboros fits a spline curve to the annotation path from the Neuroglancer JSON file. This produces a smooth, differentiable curve along the length of the annotations. If the line segments between annotation points were used, then there would could be highly discontinuous slice transitions around sharp corners. Slice Coordinate Frames Ouroboros calculates equidistant points along the spline curve. Each point is \"1\" apart from the previous to match the appearance of isotropic slices taken from one of the axes of the coordinate space of the full volume (the coordinate space of the annotation points). To follow any possible path, each point must have its own coordinate frame normal to the spline. For easier segmentation, it is also important that the axes of the point coordinate frames don't flip between points. To achieve this, Ouroboros calculates rotation-minimizing frames based on the change in orientation of the tangent vectors of adjacent points. Rectangles and Grids Ouroboros calculates the corners of the slice rectangle at using each point and its associated coordinate axes (as vectors). Pseudocode width_vector # 'u' unit vector scaled to slice width / 2 height_vector # 'v' unit vector scaled to slice height / 2 top_left = point - width_vector + height_vector top_right = point + width_vector + height_vector bottom_right = point + width_vector - height_vector bottom_left = point - width_vector - height_vector Then, for each point, a 2D grid is generated with given dimensions (slice width and height). Each point in the 2D grid is a 3D point which is calculated by interpolating between the four corner points. Volumes and Trilinear Interpolation At this point, Ouroboros has a full grid of 3D points associated with each slice, but has yet to download any data from the cloud-hosted volume. To avoid downloading unnecessary data, Ouroboros employs binary space partitioning to divide the minimum bounding box of the ROI recursively until each volume contains few enough slices to fit into available RAM. Ouroboros then downloads the data for each of these bounding boxes from the cloud-hosted volume. As each download completes, a new process is spawned to handle calculations. For each volume, scipy.ndimage.map_coordinates is used to extract the values at the coordinates of the slice grids from the 3D volume using trilinear interpolation. Each of these slices are saved as local tiff images and are later combined into a single output tiff.","title":"Slicing"},{"location":"guide/slicing/#slicing","text":"Slicing is one of the primary features of Ouroboros, available in the CLI and the desktop app.","title":"Slicing"},{"location":"guide/slicing/#using-the-slice-page","text":"Basic Usage Demo Reusing Options from a Previous Run","title":"Using the Slice Page"},{"location":"guide/slicing/#slicing-options","text":"\ud83d\udcc1 - Drag and drop files from File Explorer panel into this option. \ud83d\udcc1 Neuroglancer JSON - Path to the Neuroglancer configuration JSON file (exported from Neuroglancer with {} icon, or through the Neuroglancer Plugin) Neuroglancer Image Layer - Select Neuroglancer image layer to slice from. Neuroglancer Annotation Layer - Select Neuroglancer annotation layer to slice from. Slice Width - The output width of each slice image. Slice Height - The output height of each slice image. \ud83d\udcc1 Output File Folder - The folder to save all the resulting files into. Output File Name - Base name for all output files. Annotation MIP Level - The annotation layer's MIP level. Output MIP Level - The mip level to output slices in (essentially a downsample option). Distance Between Slices - The distance between each slice along the annotation path. Output Single File - Whether to output one tiff stack file or a folder of files. Connect Endpoints - Connect the first point in the path to the last point. This is not recommended. Bounding Box Parameters Max Depth - The maximum depth for binary space partitioning. It is not recommended to change this option unless you encounter RAM issues. Target Slices Per Box - If you are running on a low-RAM system, or you are taking very large slices, you may want to decrease this. Max RAM (GB) - 0 indicates no RAM limit. Setting a RAM limit allows Ouroboros to optimize performance and avoid overusing RAM.","title":"Slicing Options"},{"location":"guide/slicing/#how-does-slicing-work","text":"Spline Fitting Ouroboros fits a spline curve to the annotation path from the Neuroglancer JSON file. This produces a smooth, differentiable curve along the length of the annotations. If the line segments between annotation points were used, then there would could be highly discontinuous slice transitions around sharp corners. Slice Coordinate Frames Ouroboros calculates equidistant points along the spline curve. Each point is \"1\" apart from the previous to match the appearance of isotropic slices taken from one of the axes of the coordinate space of the full volume (the coordinate space of the annotation points). To follow any possible path, each point must have its own coordinate frame normal to the spline. For easier segmentation, it is also important that the axes of the point coordinate frames don't flip between points. To achieve this, Ouroboros calculates rotation-minimizing frames based on the change in orientation of the tangent vectors of adjacent points. Rectangles and Grids Ouroboros calculates the corners of the slice rectangle at using each point and its associated coordinate axes (as vectors). Pseudocode width_vector # 'u' unit vector scaled to slice width / 2 height_vector # 'v' unit vector scaled to slice height / 2 top_left = point - width_vector + height_vector top_right = point + width_vector + height_vector bottom_right = point + width_vector - height_vector bottom_left = point - width_vector - height_vector Then, for each point, a 2D grid is generated with given dimensions (slice width and height). Each point in the 2D grid is a 3D point which is calculated by interpolating between the four corner points. Volumes and Trilinear Interpolation At this point, Ouroboros has a full grid of 3D points associated with each slice, but has yet to download any data from the cloud-hosted volume. To avoid downloading unnecessary data, Ouroboros employs binary space partitioning to divide the minimum bounding box of the ROI recursively until each volume contains few enough slices to fit into available RAM. Ouroboros then downloads the data for each of these bounding boxes from the cloud-hosted volume. As each download completes, a new process is spawned to handle calculations. For each volume, scipy.ndimage.map_coordinates is used to extract the values at the coordinates of the slice grids from the 3D volume using trilinear interpolation. Each of these slices are saved as local tiff images and are later combined into a single output tiff.","title":"How Does Slicing Work?"}]}
\ No newline at end of file