Skip to content

Commit

Permalink
Update Beginner Docs (#136)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tayden
tayden authored Feb 1, 2025
1 parent 5348e03 commit 8952d93
Show file tree
Hide file tree
Showing 8 changed files with 298 additions and 265 deletions.
149 changes: 78 additions & 71 deletions docs/beginner_guide/execution.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,106 +2,113 @@

Each time you want to run a classification on new imagery follow these steps.

***

## Open Anaconda Prompt

![Open Prompt](images/open_prompt1.png)

Open anaconda prompt by searching “Anaconda Prompt” in search tool bar.
1. Open your preferred terminal
1. See the [Terminal Crash Course](./terminal_crash_course.md) if you need to refresh your memory.
2. Activate your virtual environment
1. This is detailed under [Virtual Environment Setup and Installation](./install_env_setup.md).
3. Run the Kelp-O-Matic tool, as detailed in this document.

***

## Change Environments

![Change Environments 1](images/change_environments1.png)

The default environment is called `(base)` which will appear in brackets before each
line of text.

![Change Environments 2](images/change_environments2.png)
## The `kom` Command

To change to the new environment that you created in Part 1,
type: `conda activate KelpSegmentation` and press enter.
In this command, "KelpSegmentation" was the name that you chose for your new
environment.
Now you will see that the environment has changed from `(base)` to `(KelpSegmentation)`
as KelpSegmentation is now appearing in brackets.
The `kom` command is the entry point for the Kelp-O-Matic tool. It is used to run the image processing tools that are part of the Kelp-O-Matic package.

!!! note
`kom`, like many command line tools, has a number of subcommands that can be used to run different tools.

If you used a different name for your environment, be sure to replace
`conda activate KelpSegmentation` with `conda activate <your-environment-name-here>`
### Getting Help

You can see a list of all installed environments by typing and entering the
command: `conda env list`.
It is typical of many CLI tools to also have a `--help` option that can be used to get more information about the tool and its subcommands. This is also true for `kom`.

***
To get help documentation for the `kom` tool, you can type `kom --help` into your terminal.

## Run Segmentation Tool
??? tip "Shorthand flags"
You can also use the shorthand flags `-h` to get help, e.g. `kom -h`. This is common for many CLI tools.
Options will be shown in the help documentation with both the long form (`--help`) and the shorthand form (`-h`).

![Run Tool](images/run_tool.png)
```console
kom --help
```

Type `kom find-kelp` and copy and paste the location of the image in which you would
like to detect kelp. Add a space
and then type or paste the location you would like the output file to be saved on your
computer with the name of the
output file.
This will show you a list of the subcommands available to you, as well as a brief description of what each subcommand does.

In this example the orthomosaic to be classified is named
“Kelp_Bed_Orthomosaic_2022.tif” and its location is in the C
drive, documents folder, Drone_Images subfolder.
### Processing an Image

`C:\Users\sbs33.DESKTOP-K0SDD1B\Documents\Drone_Images\Kelp_Bed_Orthomosaic_2022.tif`
??? note "A note on mussel detection"
The Kelp-O-Matic tool is designed to detect both kelp and mussels. The following information was written for kelp
detection, but the same information applies for mussels. All you have to do to find mussels instead of kelp is use
the `kom find-mussels` subcommand instead of `kom find-kelp` in the following steps.

The output results will be sent to the same Drone_Images folder and will have the name
“Kelp_Bed_Orthomosiac_2022_output.tif”,
where .tif is the file type.
#### Subcommands and Options
To process an image, you will need to use the `kom find-kelp` subcommand. This subcommand is used to detect kelp in an
image. Like we did for `kom`, we can also get help for subcommands:

`C:\Users\sbs33.DESKTOP-K0SDD1B\Documents\Drone_Images\Kelp_Bed_Orthomosaic_2022_output.tif`
```console
kom find-kelp --help
```

So, the entire command in the Anaconda prompt is:
And it will print out something like this:

```console
kom find-kelp C:\Users\sbs33.DESKTOP-K0SDD1B\Documents\Drone_Images\Kelp_Bed_Orthomosaic_2022.tif C:\Users\sbs33.DESKTOP-K0SDD1B\Documents\Drone_Images\Kelp_Bed_Orthomosaic_2022_output.tif
Usage: kom find-kelp [OPTIONS] SOURCE DEST

Detect kelp in image at path SOURCE and output the resulting classification raster to file at path DEST.

Arguments
* source FILE Input image with Byte data type. [default: None] [required]
* dest FILE File path location to save output to. [default: None] [required]

Options
--species --presence Segment to species or presence/absence level. [default: presence]
--crop-size INTEGER The data window size to run through the segmentation model. [default: 1024]
--rgbi --rgb Use RGB and NIR bands for classification. Assumes RGBI ordering. [default: rgb]
-b INTEGER GDAL-style band re-ordering flag. Defaults to RGB or RGBI order. To e.g., reorder a BGRI image at runtime, pass flags `-b 3 -b 2 -b 1 -b 4`. [default: None]
--gpu --no-gpu Enable or disable GPU, if available. [default: gpu]
--tta --no-tta Use test time augmentation to improve accuracy at the cost of processing time. [default: no-tta]
--help -h Show this message and exit.
```

Press ++enter++ and wait for the segmentation to run; the time may vary depending on the
size of the image.

!!! note
This help documentation will show you the required arguments and options that are available to you when running the `find-kelp` subcommand.

You can always get help documentation for the `kom find-kelp` tool by typing into
the prompt `kom find-kelp --help`.
#### Constructing and Executing a Command

This help documentation is the same as what is shown under
the :doc:`Command Line Reference <./cli>`.
##### Arguments
We're going to use the above `--help` documentation to construct a command relevant to the image we want to process.
For the `SOURCE` and `DEST` arguments, you will need to provide the path to the image you want to process and the path where you want to save the output, respectively.
The same path options discussed in the [Terminal Crash Course](./terminal_crash_course.md) apply here.

!!! tip
##### Options
The various options available to you are detailed in the `--help` documentation. You can use these options to customize the processing of your image, or you can use the default values.
The options are flags that can be used to enable or disable certain features of the tool, or they can take arguments to customize the behavior of the tool.

If you manually type in the path to your file, use the `<tab>` key to have your
operating system autocomplete the paths for you.
!!! example "An Example Command"

=== "Windows"

*e.g.*, if you type `kom find-kelp C:\\Desk`, then press the `<tab>` key, your
operating system should complete the command for you so it
reads: `kom find-kelp C:\\Desktop`.
```console
kom find-kelp --species --crop-size 2048 .\some\image_with_kelp.tif .\some\output.tif
```

If the partial path is ambiguous, tapping `<tab>` multiple times will cycle through
the possible path options.
In this example, we are running the `find-kelp` subcommand with the `--species` option and a
`--crop-size` of 2048. The input image is located at `.\some\image_with_kelp.tif`.
The output will be saved to `.\some\output.tif`.

=== "MacOS/Linux"

You can continue doing this as you type in the location to autocomplete the text
for long path names. It is faster, and less error prone than typing the whole
path yourself.
```console
kom find-kelp --species --crop-size 2048 ./some/image_with_kelp.tif ./some/output.tif
```

![Complete Segmentation](images/complete_segmentation.png)
In this example, we are running the `find-kelp` subcommand with the `--species` option and a
`--crop-size` of 2048. The input image is located at `./some/image_with_kelp.tif`.
The output will be saved to `./some/output.tif`.

Once the processing bar is at 100%, you can open the results in an image processing or
spatial analysis software such as QGIS or ArcGIS. Review the results for errors and edit
as needed.
##### Executing the Command
Once you have constructed your command, execute it by pressing ++enter++.

**Part 2 Kelp Segmentation is now complete!**
Wait for the progress bar to reach 100%, then open the results in an image processing or spatial analysis software such as QGIS or ArcGIS.
Review the results for errors and edit as needed.

Continue to [Part 3](./post_processing.md) to learn how to post-process the results.
***
**Part 3 Kelp Segmentation is now complete!**

*Authors: Sarah Schroeder and Taylor Denouden*
Continue to [Part 4](./post_processing.md) to learn how to post-process the results.
13 changes: 4 additions & 9 deletions docs/beginner_guide/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,9 @@
# Beginner Guide

The `kelp-o-matic` tool is a program which will detect floating canopy kelp from high resolution RGB imagery such as RPAS
(remotely piloted aircraft systems).
This document outlines step-by-step how to execute the Kelp-O-Matic tool for those with little to no experience with
executing commands from the Terminal or Command Line.

This document outlines step-by-step how to execute the kelp-o-matic tool for those with little to no experience with programming.

1. [Set-up and Installation](./setup.md)
1. [Terminal Crash Course](./terminal_crash_course.md)
2. [Virtual Environment Setup and Installation](./install_env_setup.md)
2. [Running the Segmentation tool](./execution.md)
3. [Post-Processing Results](./post_processing.md)

----

*Authors: Sarah Schroeder and Taylor Denouden*
82 changes: 82 additions & 0 deletions docs/beginner_guide/install_env_setup.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Virtual Environment Setup and Installation

It is recommended to install Kelp-O-Matic in a virtual environment to avoid conflicts
with other Python packages present on your system. `uv` is our recommended environment manager, so we'll use it in this
guide.

??? question "Why UV"

`uv` is a Python environment manager that is easy to use and works on Windows, MacOS, and Linux.
It is a good choice for beginners and experienced users alike. It's extremely fast and lightweight, and provides a
simple way to manage Python environments and install packages.

## UV Virtual Environment Setup

1. Install `uv` using their [installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
1. This will make a new command available in your terminal called `uv`.
2. Check the official instructions for installation, but generally, you're going to copy and paste the installation
command they provide (e.g. `curl ...`) into your terminal and press ++enter++. Read and follow the instructions
and prompts that are printed.

2. Once UV is installed, create a new "virtual environment" in your preferred location with the following commands:
```bash
cd path/to/your/preferred/location
uv venv my_env_name # my_env_name is the name of your virtual environment. You can choose any name you like.
```

??? question "What's a Virtual Environment"

A virtual environment is a self-contained directory that contains a Python installation for a particular version
of Python, plus a number of additional packages. It allows you to work on a specific project without affecting
other projects or the system Python installation.

It's a good practice to create a new virtual environment for each project you work on. This way, you can install the
specific versions of the packages you need for that project without affecting other projects.
3. Activate the virtual environment
=== "Windows"
```powershell
.\my_env_name\Scripts\activate
```
=== "MacOS/Linux"
```bash
source ./my_env_name/bin/activate
```
Many terminal emulators will show the name of the active virtual environment in the prompt. For example, the prompt might
change from `C:\Users\McLovin>` to `(my_env_name) C:\Users\McLovin>`. This indicates that the virtual environment is
active.
??? note "Manual deactivation"
If you want to deactivate the virtual environment without closing your terminal, run:
```bash
deactivate
```
## Install Kelp-O-Matic
Now that you have your virtual environment set up, you can install Kelp-O-Matic and its dependencies very easily with
`uv`.
1. Install Kelp-O-Matic using the following command:
```bash
uv pip install kelp-o-matic
```
!!! important
The `kom` command will be available only when the virtual environment is activated. If you close your terminal,
be sure to navigate to the location where you created the virtual environment and activate it again before running
`kom`.
??? question "What's `uv pip`?"
`uv` has a built-in package manager called `pip` that you can use to install Python packages. When not using `uv`,
Python comes with a package manager called `pip`. `uv pip` is just a faster version of that default package manager.
## Next Steps
You're now ready to process some imagery, hooray! Head over to the next section,
[Running the Segmentation tool](./execution.md), to learn how to run the segmentation tool
4 changes: 0 additions & 4 deletions docs/beginner_guide/post_processing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,3 @@ Repeat steps 1 - 3 for bull kelp by using `"gridcode" = 3` and "Nereocystis luet
### Export Data

That's it! You can now export your data a shapefile and give it an appropriate name.

----

*Authors: Luba Reshitnyk and Taylor Denouden*
Loading

0 comments on commit 8952d93

Please sign in to comment.