Skip to main content

geococo logo

PyPI python-version-from-pep-621-toml Build passing Documentation Status

Easily transform your GIS annotations into Microsoft's Common Objects In Context (COCO) datasets with GeoCOCO. This tool allows users to leverage the advanced digitizing solutions of modern GIS software for the annotations of image objects in geographic imagery.

Built with Pydantic and pycocotools, it features a complete implementation of the COCO standard for object detection with out-of-the-box support for JSON-encoding and RLE compression. The resulting datasets are versioned, easily extendable with new annotations and fully compatible with other data applications that accept the COCO format.

Key features

  • User-friendly: GeoCOCO is designed for ease of use, requiring minimal configuration and domain knowledge
  • Version Control: Datasets created with GeoCOCO are versioned and designed for expansion with future annotations
  • Command-line Tool: Use GeoCOCO from your terminal to create, append and copy COCO datasets
  • Python Module: Integrate GeoCOCO in your own data applications with the geococo package
  • Representation: GeoCOCO maximizes label representation through an adaptive moving window approach
  • COCO Standard: Output datasets are fully compatible with other COCO-accepting applications
  • Compact File Size: JSON-encoding and RLE compression are employed to ensure compact file sizes

Installation

Installing from the Python Package Index (PyPI):

# Install from PYPI with Python's package installer (pip)
pip install geococo

Example of usage

After installing geococo, there are a number of ways you can interact with its API.

Command line interface

The easiest way to use geococo is to simply call it from your preferred terminal with one of three commands: new, add and copy.

$ geococo --help
Usage: geococo [OPTIONS] COMMAND [ARGS]...

 Transform your GIS annotations into COCO datasets.

Options:
 --help  Show this message and exit.

Commands:
 add   Transform and add GIS annotations to an existing CocoDataset
 copy  Copy and (optionally) update the metadata of an existing CocoDataset
 new   Initialize a new CocoDataset with user-prompted metadata

Starting a new CocoDataset (will prompt user for metadata like Description and Contributor)

$ geococo new dataset.json

Adding new annotations to existing CocoDataset (will increment version based on input data and update any new categories/images)

$ geococo add image.tif labels.shp dataset.json images/ 512 512 --id-attribute ids

For more information on the different commands, call geococo COMMAND with --help.

$ geococo add --help
Usage: geococo add [OPTIONS] IMAGE_PATH LABELS_PATH JSON_PATH OUTPUT_DIR WIDTH
                  HEIGHT

  Transform and add GIS annotations to an existing COCO dataset.

  This method generates a COCO dataset by moving across the given image
  (image_path) with a moving window (width, height), constantly checking for
  intersecting annotations (labels_path) that represent image objects in said
  image (e.g. buildings in satellite imagery; denoted by (super)category name
  and/or id). Each valid intersection will add n Annotations entries to the
  dataset (json_path) and save a subset of the input image that contained
  these entries (output_dir).

  The output data size depends on your input labels, as the moving window
  adjusts its step size to accommodate the average annotation size, optimizing
  dataset representation and minimizing tool configuration. Each addition will
  also increment the dataset version: patch if using the same image_path,
  minor if using a new image_path, and major if using a new output_dir.

Arguments:
  IMAGE_PATH   Path to geospatial image containing image objects  [required]
  LABELS_PATH  Path to vector file containing annotated image objects
               [required]
  JSON_PATH    Path to json file containing the COCO dataset  [required]
  OUTPUT_DIR   Path to output directory for image subsets  [required]
  WIDTH        Width of image subsets  [required]
  HEIGHT       Height of image subsets  [required]

Options:
  --id-attribute TEXT     Name of column containing category_id values
                          (optional if --name_attribute is given)
  --name-attribute TEXT   Name of column containing category_name values
                          (optional if --id_attribute is given)
  --super-attribute TEXT  Name of column containing supercategory values
  --help                  Show this message and exit.

Python module

This is recommended for most developers as it gives you more granular control over the various steps. It does assume a basic familiarity with the geopandas and rasterio packages (i.e. GIS modules that help you manage vector and raster data respectively).

import pathlib
import geopandas as gpd
import rasterio
from geococo import create_dataset, load_dataset, save_dataset, append_dataset

# Replace this with your preferred output paths
data_path = pathlib.Path("path/to/your/coco/output/images")
json_path = pathlib.Path("path/to/your/coco/json/file")

# Dimensions of the moving window and output images
width, height = 512, 512

# Starting a new CocoDataset
description = "My First Dataset"
contributor = "User"

# version and date_created are automatically set
dataset = create_dataset(description=description, contributor=contributor)
# You can also load existing COCO datasets
# dataset = load_dataset(json_path=json_path)

# Loading GIS data with rasterio and geopandas
labels = gpd.read_file(some_labels_path)
raster_source = rasterio.open(some_image_path)

# (Optional) Apply any spatial or attribute queries here
# labels = labels.loc[labels["ids"].isin([1, 2, 3])]
# labels = labels.loc[labels.within(some_polygon)]

# Find and save all Annotation instances
dataset = append_dataset(
    dataset=dataset,
    images_dir=data_path,
    src=raster_source,
    labels=labels,
    window_bounds=[(width, height)],
    id_attribute=None,  # column with category_id values
    name_attribute="ids",  # column with category_name values
    super_attribute=None,  # optional column with super_category values
)

# Encode CocoDataset instance as JSON and save to json_path
save_dataset(dataset=dataset, json_path=json_path)

Visualization with FiftyOne

Like the official COCO project, the open source tool FiftyOne can be used to visualize and evaluate your datasets. Note that geococo does not include fiftyone by default but it can be installed by running pip install geococo[fiftyone]. Once installed, the following commands can be used to inspect your COCO dataset in your web browser.

# requires pycocotools and fiftyone
import fiftyone as fo
import fiftyone.zoo as foz
import pathlib

data_path = pathlib.Path("path/to/your/coco/output/images")
json_path = pathlib.Path("path/to/your/coco/json/file")

# Load COCO formatted dataset
coco_dataset = fo.Dataset.from_dir(
    dataset_type=fo.types.COCODetectionDataset,
    data_path=data_path,
    labels_path=json_path,
    include_id=True,
)

# Launch the app
session = fo.launch_app(coco_dataset, port=5151)

Metadata

Release files for geococo 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geococo 0.7.0
File Size Uploaded Provenance Actions
geococo-0.7.0.tar.gz 251.1 kB Without provenance Details for geococo-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for geococo 0.7.0
File Interpreter ABI Platform Actions
geococo-0.7.0-py3-none-any.whl Python 3 none any Details for geococo-0.7.0-py3-none-any.whl

Total release size: 281.0 kB

Release files / geococo-0.7.0.tar.gz

Download URL geococo-0.7.0.tar.gz
Size 251.1 kB
Tags Source
SHA-256 checksum
How to use checksums
dacc34867c22a6f4f64bf23361402d63fd0cec8eea285db1ffbe96856426aace
BLAKE2b-256 checksum
How to use checksums
9e3b7d927abd5c5eff75c0ff45cca5ae69e2ed2d9315018f7daad123b3e3d602
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.5

Release files / geococo-0.7.0-py3-none-any.whl

Download URL geococo-0.7.0-py3-none-any.whl
Size 30.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc9881bf241a75f31177466fa95f3e8fdf2918f49d8119ab3841d4a81f57249b
BLAKE2b-256 checksum
How to use checksums
9dbf3beee64d580cc45af9d9816800cec4644aeb17baa9315291867deb46abbe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.5

Security for geococo 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page