Skip to content

Python Library Reference

The Python library provide two functions that run classification on an input image and write data to an output location.

API

kelp_o_matic.find_kelp(source, dest, species=False, crop_size=1024, use_nir=False, band_order=None, use_gpu=True, test_time_augmentation=False)

Detect kelp in image at path source and output the resulting classification raster to file at path dest.

Parameters:

Name Type Description Default
source Union[str, Path]

Input image with Byte data type.

 required
dest Union[str, Path]

File path location to save output to.

 required
species bool

Do species classification instead of presence/absence.

 False
crop_size int

The size of cropped image square run through the segmentation model.

 1024
use_nir bool

Use NIR band for classification. Assumes RGBI ordering.

 False
band_order Optional[list[int]]

GDAL-style band re-ordering. Defaults to RGB or RGBI order. e.g. to reorder a BGRI image at runtime, pass [3,2,1,4].

 None
use_gpu bool

Disable Cuda GPU usage and run on CPU only.

 True
test_time_augmentation bool

Use test time augmentation to improve model accuracy.

 False
Source code in kelp_o_matic/lib.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def find_kelp(
    source: Union[str, Path],
    dest: Union[str, Path],
    species: bool = False,
    crop_size: int = 1024,
    use_nir: bool = False,
    band_order: Optional[list[int]] = None,
    use_gpu: bool = True,
    test_time_augmentation: bool = False,
):
    """
    Detect kelp in image at path `source` and output the resulting classification raster
    to file at path `dest`.

    Args:
        source: Input image with Byte data type.
        dest: File path location to save output to.
        species: Do species classification instead of presence/absence.
        crop_size: The size of cropped image square run through the segmentation model.
        use_nir: Use NIR band for classification. Assumes RGBI ordering.
        band_order: GDAL-style band re-ordering. Defaults to RGB or RGBI order.
            e.g. to reorder a BGRI image at runtime, pass `[3,2,1,4]`.
        use_gpu: Disable Cuda GPU usage and run on CPU only.
        test_time_augmentation: Use test time augmentation to improve model accuracy.
    """
    if not band_order:
        band_order = [1, 2, 3]
        if use_nir:
            band_order.append(4)

    _validate_band_order(band_order, use_nir)
    _validate_paths(Path(source), Path(dest))

    if use_nir and species:
        model = KelpRGBISpeciesSegmentationModel(use_gpu=use_gpu)
    elif use_nir:
        model = KelpRGBIPresenceSegmentationModel(use_gpu=use_gpu)
    elif species:
        model = KelpRGBSpeciesSegmentationModel(use_gpu=use_gpu)
    else:
        model = KelpRGBPresenceSegmentationModel(use_gpu=use_gpu)
    RichSegmentationManager(
        model,
        Path(source),
        Path(dest),
        band_order=band_order,
        crop_size=crop_size,
        test_time_augmentation=test_time_augmentation,
    )()

Example

import kelp_o_matic
kelp_o_matic.find_kelp("./path/to/kelp_image.tif", "./path/to/output_file_to_write.tif", crop_size=3200)

kelp_o_matic.find_mussels(source, dest, crop_size=1024, band_order=None, use_gpu=True, test_time_augmentation=False)

Detect mussels in image at path source and output the resulting classification raster to file at path dest.

Parameters:

Name Type Description Default
source Union[str, Path]

Input image with Byte data type.

 required
dest Union[str, Path]

File path location to save output to.

 required
crop_size int

The size of cropped image square run through the segmentation model.

 1024
band_order Optional[list[int]]

GDAL-style band re-ordering flag. Defaults to RGB order. e.g. to reorder a BGR image at runtime, pass [3,2,1].

 None
use_gpu bool

Disable Cuda GPU usage and run on CPU only.

 True
test_time_augmentation bool

Use test time augmentation to improve model accuracy.

 False
Source code in kelp_o_matic/lib.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def find_mussels(
    source: Union[str, Path],
    dest: Union[str, Path],
    crop_size: int = 1024,
    band_order: Optional[list[int]] = None,
    use_gpu: bool = True,
    test_time_augmentation: bool = False,
):
    """
    Detect mussels in image at path `source` and output the resulting classification
    raster to file at path `dest`.

    Args:
        source: Input image with Byte data type.
        dest: File path location to save output to.
        crop_size: The size of cropped image square run through the segmentation model.
        band_order: GDAL-style band re-ordering flag. Defaults to RGB order.
            e.g. to reorder a BGR image at runtime, pass `[3,2,1]`.
        use_gpu: Disable Cuda GPU usage and run on CPU only.
        test_time_augmentation: Use test time augmentation to improve model accuracy.
    """
    if not band_order:
        band_order = [1, 2, 3]

    _validate_band_order(band_order)
    _validate_paths(Path(source), Path(dest))
    model = MusselRGBPresenceSegmentationModel(use_gpu=use_gpu)
    RichSegmentationManager(
        model,
        Path(source),
        Path(dest),
        band_order=band_order,
        crop_size=crop_size,
        test_time_augmentation=test_time_augmentation,
    )()

Example

import kelp_o_matic
kelp_o_matic.find_mussels("./path/to/mussel_image.tif", "./path/to/output_file_to_write.tif", crop_size=3200)