add documentation folder

Author: zsylvester

docs/source/api_reference.rst

@@ -0,0 +1,32 @@
+API Reference
+=============
+.. toctree::
+   :caption: API Reference
+
+.. autofunction:: segmenteverygrain.predict_image
+.. autofunction:: segmenteverygrain.predict_large_image
+.. autofunction:: segmenteverygrain.predict_image_tile
+.. autofunction:: segmenteverygrain.label_grains
+.. autofunction:: segmenteverygrain.one_point_prompt
+.. autofunction:: segmenteverygrain.two_point_prompt
+.. autofunction:: segmenteverygrain.find_overlapping_polygons
+.. autofunction:: segmenteverygrain.weighted_crossentropy
+.. autofunction:: segmenteverygrain.plot_images_and_labels
+.. autofunction:: segmenteverygrain.calculate_iou
+.. autofunction:: segmenteverygrain.pick_most_similar_polygon
+.. autofunction:: segmenteverygrain.sam_segmentation
+.. autofunction:: segmenteverygrain.find_connected_components
+.. autofunction:: segmenteverygrain.merge_overlapping_polygons
+.. autofunction:: segmenteverygrain.rasterize_grains
+.. autofunction:: segmenteverygrain.create_labeled_image
+.. autofunction:: segmenteverygrain.load_and_preprocess
+.. autofunction:: segmenteverygrain.onclick
+.. autofunction:: segmenteverygrain.onpress
+.. autofunction:: segmenteverygrain.onclick2
+.. autofunction:: segmenteverygrain.onpress2
+.. autofunction:: segmenteverygrain.click_for_scale
+.. autofunction:: segmenteverygrain.get_grains_from_patches
+.. autofunction:: segmenteverygrain.plot_image_w_colorful_grains
+.. autofunction:: segmenteverygrain.plot_grain_axes_and_centroids
+.. autofunction:: segmenteverygrain.classify_points
+.. autofunction:: segmenteverygrain.compute_curvature

docs/source/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'segmenteverygrain'
+copyright = '2024, Zoltan Sylvester'
+author = 'Zoltan Sylvester'
+release = '0.1.8'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+import os
+import sys
+sys.path.insert(0, '/Users/zoltan/Dropbox/Segmentation/segmenteverygrain/segmenteverygrain/__init__.py')

docs/source/getting_started.rst

@@ -0,0 +1,65 @@
+Getting started
+---------------
+
+.. toctree::
+   :caption: Getting started
+
+To load the Unet model:
+
+.. code-block:: python
+
+   import segmenteverygrain as seg
+   model = seg.Unet()
+   model.compile(optimizer=Adam(), loss=seg.weighted_crossentropy, metrics=["accuracy"])
+   model.load_weights('./checkpoints/seg_model')
+
+To run the Unet segmentation on an image and label the grains in the Unet output:
+
+.. code-block:: python
+
+   image_pred = seg.predict_image(image, model, I=256)
+   labels, coords = seg.label_grains(image, image_pred, dbs_max_dist=20.0)
+    
+The input image should not be much larger than ~2000x3000 pixels, in part to avoid long running times; it is supposed to be a numpy array with 3 channels (RGB).
+Grains should be well defined in the image and not too small (e.g., only a few pixels in size).
+The Unet prediction should be QC-d before running the SAM segmentation:
+
+.. code-block:: python
+
+   plt.figure(figsize=(15,10))
+   plt.imshow(big_im_pred)
+   plt.scatter(np.array(coords)[:,0], np.array(coords)[:,1], c='k')
+   plt.xticks([])
+   plt.yticks([]);
+
+If the Unet segmentation is of low quality, the base model can be (and should be) fine tuned using the ``Train_seg_unet_model.ipynb`` notebook.
+
+To run the SAM segmentation on an image, using the outputs from the Unet model:
+
+.. code-block:: python
+
+   all_grains, labels, mask_all, grain_data, fig, ax = seg.sam_segmentation(sam, image, image_pred, coords, labels, min_area=400.0, plot_image=True, remove_edge_grains=False, remove_large_objects=False)
+
+The ``all_grains`` list contains shapely polygons of the grains detected in the image. ``labels`` is an image that contains the labels of the grains. 
+``grain_data`` is a pandas dataframe with a number of grain parameters.
+
+If you want to detect grains in large images, you should use the ``predict_large_image`` function, which will split the image into patches and run the Unet and SAM segmentations on each patch:
+
+.. code-block:: python
+
+   all_grains = seg.predict_large_image(fname, model, sam, min_area=400.0, patch_size=2000, overlap=200)
+
+Just like before, the ``all_grains`` list contains shapely polygons of the grains detected in the image. The image containing the grain labels can be generated like this:
+
+.. code-block:: python
+
+   labels = seg.rasterize_grains(all_grains, large_image)
+
+See the `Segment_every_grain.ipynb <https://github.com/zsylvester/segmenteverygrain/blob/main/segmenteverygrain/Segment_every_grain.ipynb>`_ notebook for an example 
+of how the models can be loaded and used for segmenting an image and QC-ing the result. The notebook goes through the steps of loading the models, running the 
+segmentation, interactively updating the result, and saving the grain data and the mask.
+
+The `Train_seg_unet_model.ipynb <https://github.com/zsylvester/segmenteverygrain/blob/main/segmenteverygrain/Train_seg_unet_model.ipynb>`_ notebook goes through the 
+steps needed to create, train, and test the Unet model. If the base Unet model does not work well on a specific type of image, it is a good idea to generate some 
+new training data (a few small images are usually enough) and to fine tune the base model so that it works better on the new image type. The workflow in the 
+'Train_seg_unet_model' notebook can be used to do this finetuning -- you just need to load the weights of the base model before starting the training.

docs/source/index.rst

@@ -0,0 +1,51 @@
+.. figure:: ../../gravel_example_mask.png
+   :alt: grains detected in an image
+   :align: left
+
+segmenteverygrain
+=================
+`GitHub Repository <https://github.com/zsylvester/segmenteverygrain>`_
+
+``segmenteverygrain`` is a Python package that aims to detect grains (or grain-like objects) in images. 
+The goal is to develop a machine learning model that does a reasonably good job at detecting most of the grains in a photo, so that it is 
+useful for determining grain size and grain shape, a common task in geomorphology and sedimentary geology. ``segmenteverygrain`` 
+relies on the `Segment Anything Model (SAM) <https://github.com/facebookresearch/segment-anything>`_, developed by Meta, 
+for getting high-quality outlines of the grains. However, SAM requires prompts for every object detected and, when used in 
+'everything' mode, it tends to be slow and results in many overlapping masks and non-grain (background) objects. 
+To deal with these issues, 'segmenteverygrain' relies on a Unet-style, patch-based convolutional neural network to create a 
+first-pass segmentation which is then used to generate prompts for the SAM-based segmentation. Some of the grains will be missed 
+with this approach, but the segmentations that are created tend to be of high quality.
+
+``segmenteverygrain`` also includes a set of functions that make it possible to clean up the segmentation results: delete and 
+merge objects by clicking on them, and adding grains that were not segmented automatically. The QC-d masks can be saved and 
+added to a dataset of grain images. These images then can be used to improve the Unet model.
+
+Installation
+------------
+.. toctree::
+   :caption: Installation
+
+To install ``segmenteverygrain`` you can use ``pip``:
+
+.. code-block:: shell
+
+   pip install segmenteverygrain
+
+Or you can install it from the source code:
+
+.. code-block:: shell
+
+   git clone https://github.com/zsylvester/segmenteverygrain.git
+   cd segmenteverygrain
+   pip install .
+
+The easiest way of creating a Python environment in which 'segmenteverygrain' works well is to use 
+the `environment.yml <https://github.com/zsylvester/segmenteverygrain/blob/main/environment.yml>`_ file with conda (or mamba).
+
+Contents
+--------
+.. toctree::
+   :maxdepth: 2
+
+   getting_started
+   api_reference