Merge pull request #521 from WilhelmusLab/update_documentation

Setting up documentation pages

docs/src/index.md

@@ -3,6 +3,9 @@
 ## Overview
 IceFloeTracker.jl is a collection of routines and tools for processing remote sensing imagery, identifying sea ice floes, and tracking the displacement and rotation of ice floes across multiple images. It can be used either standalone to create custom processing pathways or with the [Ice Floe Tracker Pipeline](https://github.com/WilhelmusLab/ice-floe-tracker-pipeline).
 
+```@contents
+```
+
 ## Algorithm components
 The Ice Floe Tracker (IFT) package includes the core functions for the three main steps of the algorithm. These functions can be used independently and can be customized for specific use cases. 
 
@@ -15,17 +18,7 @@ The IFT segmentation functions include functions for semantic segmentation (pixe
 ### Tracking
 Ice floe tracking is carried out by comparing the shapes produced in the segmentation step. Shapes with similar area are rotated until the difference in surface area is minimized, and then the edge shapes are compared using a Ѱ-s curve. If thresholds for correlation and area differences are met, then the floe with the best correlation and smallest area differences are considered matches and the objects are assigned the same label. In the end, trajectories for individual floes are recorded in a dataframe.
 
-```@contents
-```
-## Functions
-```@autodocs
-Modules = [IceFloeTracker]
-Order   = [:function, :macro, :type]
-```
 
-## Index
-```@index
-```
 
 ## Developers
 IceFloeTracker.jl is a product of the [Wilhelmus Lab](https://www.wilhelmuslab.me) at Brown University, led by Monica M. Wilhelmus. The original algorithm was developed by Rosalinda Lopez-Acosta during her PhD work at University of California Riverside, advised by Dr. Wilhelmus. The translation of the original Matlab code into the current modular, open source Julia package has been carried out in conjunction with the Center for Computing and Visualization at Brown University. Contributors include Daniel Watkins, Maria Isabel Restrepo, Carlos Paniagua, Tim DiVoll, John Holland, and Bradford Roarr.
@@ -40,4 +33,14 @@ Lopez-Acosta et al., (2019). Ice Floe Tracker: An algorithm to automatically ret
 1. Manucharyan, Lopez-Acosta, and Wilhelmus (2022)\*. Spinning ice floes reveal intensification of mesoscale eddies in the western Arctic Ocean. _Scientific Reports_, **12(7070)**, doi:[10.1038/s41598-022-10712-z](https://doi.org/10.1038/s41598-022-10712-z)
 2. Watkins, Bliss, Hutchings, and Wilhelmus (2023)\*. Evidence of Abrupt Transitions Between Sea Ice Dynamical Regimes in the East Greenland Marginal Ice Zone. _Geophysical Research Letters_, **50(e2023GL103558)**, pp. 1-10, doi:[10.1029/2023GL103558](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2023GL103558)
 
-\* Papers using data from the Matlab implementation of Ice Floe Tracker.
+\*Papers using data from the Matlab implementation of Ice Floe Tracker.
+
+## Functions
+```@autodocs
+Modules = [IceFloeTracker]
+Order   = [:function, :macro, :type]
+```
+
+## Index
+```@index
+```

docs/src/preprocessing.md

@@ -0,0 +1,24 @@
+# Preprocessing
+IFT operates on optical satellite imagery. The main functions are designed with "true color" and "false color" imagery in mind, and have thus far primarily been tested on imagery from the Moderate Resolution Imaging Spectroradiometer (MODIS) from the NASA _Aqua_ and _Terra_ satellites. The preprocessing routines mask land and cloud features, and aim to adjust and sharpen the remainder of the images to amplify the contrast along the edges of sea ice floes. The functions use three different images: a land mask, a true color image, and a false color image. Examples are based on the NASA MODIS dataset.
+
+## Land masks
+Landmask generation and dilation is handled by the function `create_landmask`. Landmask images from file are loaded as RGB matrices. This example uses an image from NASA EarthData landmask for Beaufort Sea.
+
+```
+using IceFloeTracker
+
+rgb_landmask = IceFloeTracker.load(<landmask_path>);
+landmask_imgs = IceFloeTracker.create_landmask(rgb_landmask);
+```
+The landmask_imgs object includes a binary version of the original landmask and a dilated version, which helps to cover the complicated near-coastal regions.
+
+```@raw html
+<img align="right" src="assets/landmask_example.png" width="300">
+```
+
+At the top, we have the original landmask TIFF, which has black and gray values. The middle image is the binary image, with land set to 0. At the bottom, we can see the dilated image using the default value of the structuring element. The default has radius 50, which results in a coastal mask of 12.5 km based on the 250 m pixel size of default MODIS imagery.
+
+## Cloud masks
+Setting thresholds for cloud mask
+
+## Image regularization

docs/src/segmentation.md

@@ -0,0 +1,6 @@
+# Segmentation
+The segmentation functions are intended for use on the preprocessed imagery.
+
+## Ice/Water Discrimination
+
+## Feature Identification

docs/src/tracking.md

@@ -0,0 +1,2 @@
+# Tracking
+Ice floe tracking links objects in images pairwise.

src/landmask.jl

@@ -1,7 +1,7 @@
 """
     create_landmask(landmask_image, struct_elem, fill_value_lower, fill_value_upper)
 
-Convert a 3-channel RGB land mask image to a 1-channel binary matrix, including a buffer to extend the land over any soft ice regions; land = 0, water/ice = 1. Returns a named tuple with the dilated and non-dilated landmask.
+Convert a 3-channel RGB land mask image to a 1-channel binary matrix, and use a structuring element to extend a buffer to mask complex coastal features. In the resulting mask, land = 0 and ocean = 1. Returns a named tuple with the dilated and non-dilated landmask.
 
 # Arguments
 - `landmask_image`: RGB land mask image from `fetchdata`
@@ -31,7 +31,7 @@ end
 """
     binarize_landmask(landmask_image)
 
-Convert a 3-channel RGB land mask image to a 1-channel binary matrix; land = 0, water/ice = 1.
+Convert a 3-channel RGB land mask image to a 1-channel binary matrix; land = 0, ocean = 1.
 
 # Arguments
 - `landmask_image`: RGB land mask image from `fetchdata`
@@ -47,7 +47,7 @@ end
 """
     apply_landmask(input_image, landmask_binary)
 
-Zero out pixels in land and soft ice regions on truecolor image, return RGB image with zero for all three channels on land/soft ice.
+Zero out pixels in all channels of the input image using the binary landmask.
 
 
 # Arguments
@@ -69,14 +69,16 @@ end
 """
     remove_landmask(landmask, ice_mask)
 
-Find the pixel indexes that are floating ice rather than soft or land ice. Returns an array of pixel indexes. 
+Apply the landmask to the ice mask to remove labeled ice pixels that overlap with the landmask. Returns
+a list of indices of pixels that are likely containing sea ice.
 
 # Arguments
 - `landmask`: bitmatrix landmask for region of interest
 - `ice_mask`: bitmatrix with ones equal to ice, zeros otherwise
 
 """
 ## NOTE(tjd): This function is called in `find_ice_labels.jl`
+## NOTE(dmw): For consistency, it would make sense to reverse the order of inputs to match landmask
 function remove_landmask(landmask::BitMatrix, ice_mask::BitMatrix)::Array{Int64}
     land = IceFloeTracker.apply_landmask(ice_mask, landmask)
     return [i for i in 1:length(land) if land[i]]