Skip to content

Commit

Permalink
docs: remaining videos and text for the quickstart section and better…
Browse files Browse the repository at this point in the history
… description of the gallery page components.
  • Loading branch information
brnovasco committed May 28, 2024
1 parent b42a8d5 commit d426266
Show file tree
Hide file tree
Showing 8 changed files with 211 additions and 59 deletions.
91 changes: 58 additions & 33 deletions apps/docs/content/docs/concepts/workspace.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ description: Workspace

import { File, Folder, Files } from "fumadocs-ui/components/files";
import { ImageZoom } from "fumadocs-ui/components/image-zoom";
import { Callout } from "fumadocs-ui/components/callout";

import Node from "@/app/_components/node";

Expand Down Expand Up @@ -136,12 +137,12 @@ explorer window where the user can navigate through the remote storage file
system and select the desired base path for the workspace files. The user can
only view and explore the files in the remote storage server that are allowed by
the user's credential permissions. By selecting a base path, the user will be
prompted back to the workspace creation form with the selected path filled in the
Workspace path input field and needs to fill in the Workspace name input field
which will be the name of the new directory that will be created in the selected
base path. Before submitting the form, the user must choose the Slurm partition
where the workspace creation job will be submitted. By now the user must know
which partitions are available and scheduled for the user's group.
prompted back to the workspace creation form with the selected path filled in
the Workspace path input field and needs to fill in the Workspace name input
field which will be the name of the new directory that will be created in the
selected base path. Before submitting the form, the user must choose the Slurm
partition where the workspace creation job will be submitted. By now the user
must know which partitions are available and scheduled for the user's group.

<ImageZoom
alt="Remote fs navigation"
Expand Down Expand Up @@ -227,22 +228,22 @@ three main independent concepts that can be subdivided in 5 independent steps:
by the `run_inference` function in the ssc-deepsirius package cli.

Any combination of these steps that starts from 1 and ends in 3 mean a complete
processing workflow of the ssc-deepsirius package, with specific input and output
parameters that results in the creation or transformation of data between them
on the remote storage server. So the results of a step can be used as input for
another processing step as an independent job without the user occupying the
processing workflow of the ssc-deepsirius package, with specific input and
output parameters that results in the creation or transformation of data between
them on the remote storage server. So the results of a step can be used as input
for another processing step as an independent job without the user occupying the
slurm queue and the cluster resources when preparing the data for the next step.

As the results of the steps are saved in the remote storage server, the user can
check the results of the steps or use it as it sees fit, even if the interface is
not running - or start another variation of the analysis at any time during the
life cycle of the files.

These characteristics of the ssc-deepsirius package are explored by the interface
by describing the steps as nodes in a graph and the relations between them as
edges. By saving the state of the nodes and the edges in the database, the user
can load the workspace with the appropriate metadata telling a story of the
analysis and the state of the files in the remote storage server, thus being
check the results of the steps or use it as it sees fit, even if the interface
is not running - or start another variation of the analysis at any time during
the life cycle of the files.

These characteristics of the ssc-deepsirius package are explored by the
interface by describing the steps as nodes in a graph and the relations between
them as edges. By saving the state of the nodes and the edges in the database,
the user can load the workspace with the appropriate metadata telling a story of
the analysis and the state of the files in the remote storage server, thus being
able to continue the analysis and compare with other possible steps or
variations of the analysis at any time.

Expand Down Expand Up @@ -335,10 +336,10 @@ shown below:
it was checked for the last time and the cancel button and a link for the
gallery view with more details.

## Gallery View
## Gallery Page

<ImageZoom
alt="Gallery View"
alt="Gallery Page"
src={GalleryView}
className="!my-0 rounded-sm"
priority
Expand All @@ -347,22 +348,46 @@ _Gallery view of an augmentation node showing the preview images option. As some
of the options are intervals with max and min values, two images are generated for
these cases and identified as `Option_name_max` and `Option_name_min`._


The gallery view is another page where the user can see more details related to
the job and remote files and processes. The gallery view is a page that can be
accessed by clicking on the link on the side panel of the node and has the
following possible visualizations:

### Slurm Job Logs

There are two options for visualization of the redirected ouput related to the
slurm jobs. Slurm gives the option to redirect the stdout and stderr of the jobs
to files that are saved in the remote storage in the logs directory of the
workspace. The user can visualize the contents of these files by clicking on the
respective buttons:

- **Output Logs**: Renders the contents of the output log file associated with
the job.
the job stdout output.
- **Error Logs**: Renders the contents of the error log file associated with the
job.
- **Preview images**: _(Only available for the augmented dataset creation
nodes)_. Renders the preview images generated by the `augmented_dataset`
function in the ssc-deepsirius package cli. The preview images are generated
to help the user to check if the transformations applied to the images have
the expected results.
- **Tensorboard**: _(Only available for the network and finetune nodes)_. Calls
a secondary process that starts a tensorboard view of the logs of the training
process. The tensorboard view is a tool that helps the user monitor the
training process of the deep learning model. The tensorboard view is available
for the training and finetuning nodes.
job stderr output.

### Preview images

<Callout type="info">
This feature is only available for the dataset augmentation nodes.
</Callout>

The preview images are generated by the `augmented_dataset` function in the
ssc-deepsirius package cli. These images don't represent the dataset, since its
made many smaller patches of different images, but serve as a method to verify
if the chosen operations and parameters are producing the intended outcome.

### Tensorboard

<Callout type="info">
This feature is only available for the network and finetune nodes.
</Callout>

This feature triggers a secondary service that starts a tensorboard view of the
logs of the training process of the deep learning model. The tensorboard view is
a tool that helps the user monitor the training process of the deep learning
model. While the tensorboard view is active, the user can see the training
evolution of the selected network. If the user leaves the page, the service will
be stopped and the user will need to start it again to see the training
evolution.
4 changes: 3 additions & 1 deletion apps/docs/content/docs/controls.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ Its main components are:

## Gallery Page

The [gallery page](/docs/concepts/workspace#gallery-view) can only be accessed
The [gallery page](/docs/concepts/workspace#gallery-page) can only be accessed
by clicking on the link on the side panel of a node and it displays more
detailed information about the job and remote files and processes depending on
the node type and the options available to that node.
Expand All @@ -149,3 +149,5 @@ of the options are intervals with max and min values, two images are generated f
these cases and identified as `Option_name_max` and `Option_name_min`. Since the
augmentation node does not perform training, the option for the tensorboard view
is not available for this node._

Read more about the [gallery page components](/docs/concepts/workspace#gallery-page).
175 changes: 150 additions & 25 deletions apps/docs/content/docs/from-zero-to-label.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ description: From Zero to Label
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

This tutorial will guide you through the process of creating a new workspace and a
basic deep learning workflow using the DeepSirius UI app. By the end, you should
be able to create a dataset, augment it, train a network, fine-tune it and run an
inference. Start with nothing, and end with a fresh set of labels.
This tutorial will guide you through the process of creating a new workspace and
a basic deep learning workflow using the DeepSirius UI app. By the end, you
should be able to create a dataset, augment it, train a network, fine-tune it
and run an inference. Start with nothing, and end with a fresh set of labels.

Have fun!

Expand All @@ -21,56 +21,181 @@ Have fun!
You will need a CNPEM account to access the DeepSirius Web App and know the
SLURM queues you are allowed to use.

With that settled you can log into the [DeepSirius](https://deepsirius.lnls.br)
with your CNPEM email address and password.
With that settled you can log into the [DeepSirius](https://deepsirius.lnls.br)
with your CNPEM email address and password.

<video controls>
<source src="/dive/assets/signin.webm" type="video/webm" />
Sign in
</video>
<video controls>
<source src="/dive/assets/signin.webm" type="video/webm" />
Sign in
</video>

</Step>

<Step>
## Create a new workspace
Access your workspaces by clicking on the `Workspaces` button on the center of
the homepage. This will redirect you to your workspaces page, where you can see
all the workspaces you have already created or create a new one.

Click on the `New` button to create a new workspace. You'll be redirected to a
new page where you can fill a form with the path in the storage to where the
workspace will be created, the name of the workspace and a slurm partition to
run this creation job.
Click on the `New` button to create a new workspace. You'll be redirected to a
new page where you can fill a form with the path in the storage to where the
workspace will be created, the name of the workspace and a slurm partition to
run this creation job.

On job completion, you will be redirected to the workspace workboard, where you
can create and connect the components of your workflow. Each component represents
a job that will be run in the cluster and corresponds to a step in the deep
learning workflow.
On job completion, you will be redirected to the workspace workboard, where you
can create and connect the components of your workflow. Each component
represents a job that will be run in the cluster and corresponds to a step in
the deep learning workflow.

<video controls>
<source src="/dive/assets/create-workspace.webm" type="video/webm" />
Create a new workspace
</video>
</Step>

<Step>
## Create a new dataset
<Callout title="Get in the workspace!" type="warn" >

## Create a new dataset

<Callout title="Get in the workspace!" type="warn">
The next steps will be done in the workspace you just created. If, for some
reason, you are not there, please go back to the workspaces page and click on
the workspace you just created to open it.
</Callout>
</Callout>

On the workspace page, click on the button with the `+` sign to create on the
top left corner of the page to open a menu containing the names of the nodes you
can create. Click on the `Dataset` button to create a new dataset.

This will create a new dataset node in the the middle of the workboard. Click on
the node to open the dataset creation form on a panel that will appear on the
right side of the page. Fill the form with the name of the new dataset, and
click on the `Add Data` button to start selecting a group of image, label and
(optinally) weight map files to construct your dataset. You can click on the
`+ More!` button to add as many more groups of files to the dataset as you need.
Any row of this part of the form needs at least one image and one label file to
be valid. By clicking on each button of this row, a remote file navigator opens
to help you search and select the path on the storage server where the files are
located. The deepsirius app only works with files that are located in the
storage server, so make sure to upload your files to the storage server before
creating the dataset.

<video controls>
<source src="/dive/assets/first-dataset.webm" type="video/webm" />
Create a new dataset
</video>

</Step>

<Step>
## Make the dataset bigger

## Make the dataset bigger

After creating the dataset, you can augment it by clicking on the bottom
`handle` of the dataset node or by clicking on the `+` button on the top right
corner of the workspace workboard and selecting the `Augmentation` node. This
will create a new augmentation node in the workboard. Click on the new node to
open the side panel with the augmentation form. Fill the form with the name of
the new augmented dataset, and select the augmentation techniques you want to
apply to the dataset.

After the job is completed, you can click on the `Details` link at the bottom of
the side panel to go to the
[gallery page](/docs/concepts/workspace#gallery-view) and see a list of preview
images demonstrating the selected augmentation operations with the selected
parameters applied to a slice of an image from the dataset. These images don't
represent the dataset, since its made of patches, but serve as a method to
verify if the chosen operations and parameters are producing the intended
outcome.

<video controls>
<source src="/dive/assets/first-augmentation.webm" type="video/webm" />
Augment the dataset
</video>

</Step>

<Step>
## Train a network

## Train a network

After augmenting the dataset, you can train a network by clicking on the right
`handle` of a dataset or augmentation node or by clicking on the `+` button on
the top right corner of the workspace workboard and selecting the `Network`
node. This will create a new network node in the workboard. Click on the new
node to open the side panel with the network form. Fill the form with the name
of the new network, and select the network architecture, and other parameters
related to the training process.

After the job is submitted, you can click on the `Details` link at the bottom of
the side panel to go the [gallery page](/docs/concepts/workspace#gallery-view)
and see the training evolution by clicking on the `Tensorboard` button. This
will trigger a tensorboard instance that will show the training evolution of the
selected network.

<video controls>
<source src="/dive/assets/first-network.webm" type="video/webm" />
Train the network
</video>

</Step>

<Step>
## Not enough? Fine-tune it!

## Not enough? Fine-tune it!

After training a network, you can fine-tune it by clicking on the bottom
`handle` of a network node or by clicking on the `+` button on the top left
corner of the workspace workboard and selecting the `Fine-tune` node. This will
create a new fine-tune node in the workboard.

The fine-tune node needs to be connected to a network and a dataset node to
work. You can connect the fine-tune node to a dataset or a augmentation node by
dragging its left `handle` to the right `handle` of the dataset or augmentation
node. The same goes for the network node.

The fine-tune node has a form similar to the network node, but you can't select
the network architecture and have the option to
[drop the classifier](/docs/concepts/network#drop-classifier) of the network.

You can add as many finetune nodes as you want to a network node by connecting a
new fine-tune node to the bottom handle of a network node or a fine-tune
connected to a network node. This is simply to register the fine-tune jobs
separately, since the fine-tune job is a continuation of the training job and
only changes the files related to the same network on the storage server so you
can't delete a fine-tune, but you can delete the network node to delete all the
fine-tune nodes connected to it.

<video controls>
<source src="/dive/assets/first-finetune.webm" type="video/webm" />
Fine-tune a network
</video>

</Step>

<Step>
## Time to label

## Time to label

Finally, with a trained network, you can run an inference on new data by
clicking on the right `handle` of a network or by clicking on the `+` button on
the top left corner of the workspace workboard and selecting the `Inference`
node. This will create a new inference node in the workboard.

The inference node needs to be connected to a network and a new set of images to
make inference on. You need also set a remote path to where the inference
results will be saved.

After the job is completed, you need a volumetric image visualization tool to
properly see the results, like the Annotat3D or Index plataforms provided
internally by CNPEM or any other tool that can visualize volumetric labeled
images.

<video controls>
<source src="/dive/assets/first-inference.webm" type="video/webm" />
Run an inference on new data
</video>

</Step>

</Steps>
Binary file added apps/docs/public/assets/first-augmentation.webm
Binary file not shown.
Binary file added apps/docs/public/assets/first-dataset.webm
Binary file not shown.
Binary file added apps/docs/public/assets/first-finetune.webm
Binary file not shown.
Binary file added apps/docs/public/assets/first-inference.webm
Binary file not shown.
Binary file added apps/docs/public/assets/first-network.webm
Binary file not shown.

0 comments on commit d426266

Please sign in to comment.