geowatch 0.13.3

Purpose & Features

Geowatch can be used to train, predict, and evaluate segmentation models on multi-sensor image or video data. Polygons can be extracted or “tracked” across frames in a video to produce vectorized predictions.

Images can be in different resolutions, may be paired with geospatial metadata (but this is not required), and have any number of sensed or derived raster bands. Each raster band for an image need not be at the same resolution. The only requirement is that there is an affine transform that relates each underlying “asset space” into “image space”, which in turn must be similarly related to each “video space”. These transforms and all other details of the dataset are provided in a kwcoco file.

Dataloaders are setup to work with kwcoco files, and at train time details like mean/std computation, classes, frequency weights are handled automatically as opposed to common practice of hardcoding those values somewhere in a config file or in the code. In this way geowatch seeks to run on the input data the user provides, rather than make assumptions about it. The only restriction is that the data must be registered in a kwcoco file, which is easy to do, can co-exist with arbitrary other on-disk structures, and has many benefits. Images can be arbitrarily large or small, and can be used in-situ (i.e. the raw images need not be pre-processed in any way), although some formats (e.g. COGs) will be more efficient than others.

Use Case: Heavy Construction

The motivating use-case for this software is detection of heavy construction events and the classification of their phases.

The first image illustrates the broad area search (BAS) component of the pipeline that uses low spatio-temporal resolution data to detect candidate “salient” regions for further processing.

The next main component of the system is activity characterization (AC) where higher resolution data is used to refine predicted information. In this case we classify each polygon as a different phase of construction. In the above example there are 3 detected candidates. We now zoom in on the one in the middle.

This shows the system detecting the construction of the KHQ building and classifying its phases. This demo was run on public data, and can be reproduced with Tutorial 6. The system was not trained on this region.

Getting Started

To quickly get started locally, assuming you have Python installed, you can install geowatch with pip.

pip install geowatch[headless]

# OR for a more fully featured install use:
pip install geowatch[headless,optional,development,tests]

This gives you access to the GEOWATCH CLI.

geowatch --help

One library that we cannot get via the standard pip mechanism is GDAL. We have to install this manually from the Kitware hosted GDAL large image wheels.

pip install --prefer-binary GDAL>=3.4.1 --find-links https://girder.github.io/large_image_wheels

# NEW in 0.8.0. Instead of using the above command you can run:
geowatch finish_install

If you use the fully featured install command (which you can run after the fact), you can test that your install is functioning correctly by running the doctests:

xdoctest watch

For more details see the installing GEOWATCH for development guide.

We also have limited windows support, see installing GEOWATCH on Windows.

Tutorials

We have a set of tutorials related to training models and predicting with the system.

• Tutorial 1: Toy RGB Fusion Model Example

• Tutorial 2: Toy MSI Fusion Model Example

• Tutorial 3: Feature Fusion Tutorial

• Tutorial 4: Misc Training Tutorial

• Tutorial 5: KR2 BAS SMART Demo

• Tutorial 6: KHQ SMART Demo

Documentation

For quick reference, a list of current documentation files is:

• Onboarding Docs

• Internal Resources

• The GEOWATCH CLI

• Contribution:

  • Contribution Instructions

  • Rebasing Procedure

  • Testing Practices

  • Supporting Projects

  • Coding Conventions

• Installing:

  • Installing GEOWATCH

  • Installing GEOWATCH on Windows

  • Installing Python via Conda

  • Installing Python via PyEnv

• Fusion Related Docs:

  • TA2 Fusion Overview

  • TA2 Deep Dive Info

  • TA2 Feature Integration

• Older Design Docs:

  • Structure Proposal

Development

For new collaborators, please refer to the onboarding docs

For internal collaborators, please refer to the internal docs

For more details about the GEOWATCH CLI and other CLI tools included in this package see: the GEOWATCH CLI docs

Related Work

There are other GIS and segmentation focused torch packages out there:

• https://github.com/microsoft/torchgeo - Torch geo provides many custom dataloaders for standard datasets. In contrast, we provide a single data loader for kwcoco files.

• https://github.com/azavea/raster-vision - based on chips, whereas ours focuses on the ability to process data in-situ (using the help of delayed_image).

• https://github.com/open-mmlab/mmsegmentation - A very good package (and research group), we use some the mmlabs models, but their library doesn’t have the data flexibility (e.g. large image support) that kwcoco provides.

Acknowledgement

This research is based upon work supported in part by the Office of the Director of National Intelligence (ODNI), 6 Intelligence Advanced Research Projects Activity (IARPA), via 2021-2011000005. The views and conclusions contained herein are those of the authors and should not be interpreted as necessarily representing the official policies, either expressed or implied, of ODNI, IARPA, or the U.S. Government. The U.S. Government is authorized to reproduce and distribute reprints for governmental purposes notwithstanding any copyright annotation therein