Package: geolabel-maker
geolabel-makerThis tool is provided to help you in yourdata preparation for geospatial artificial intelligence.Withgeolabel-maker, you will be able to combine satellite or aerial imagery with
vector spatial data to create your own ground-truth dataset. This Python package can
generate your final dataset in theCOCO formatfor deep-learning models.It is designed to link up these 4 needed steps :create labels from geometries and raster files;make virtual raster files to combine images and labels;split image and label virtual files creating tiles;create an annotation JSON file in the COCO format for a specific zoom level.InstallationRequirementsPython 3.6GDALGDALAs a particular case, GDAL is not included into thesetup.pyfile.ForUbuntudistributions, the following operations are needed to install this program:sudo apt-get install libgdal-dev
sudo apt-get install python3-gdalThe GDAL version can be verified by:gdal-config --versionAfter that, a simplepip install gdal(orconda install gdal) may be sufficient, however considering our own experience it is not the case on Ubuntu. One has to retrieve a GDAL for Python that corresponds to the GDAL of system:pip install --global-option=build_ext --global-option="-I/usr/include/gdal" GDAL==`gdal-config --version`
python3 -c "import osgeo;print(osgeo.__version__)"For other OS, please visit theGDALinstallation documentation.Installation with pippip install geolabel-makerUsageInputsAn sample dataset is available in thedata/folder. See theExamplesparagraph to more information.To create your labels and annotations in the COCO format, you need:IMG: path to the folder containing the images to be labeledCATEGORIES: a JSON file with an unique id for each, the description of expected categories
with path to vector label file, and color as RGB triplet.TILES: a folder where the tiles (256x256 pixels images) will be recordedExample of the categories file:{"category_1":{"id":1,"file":"path to your category_1 vector file","color":[150,0,0]},"category_2":{"id":2,"file":"path to your category_2 vector file","color":[255,255,255]}}Supported formats:We use packages based on GDAL drivers.for images, seeraster formats:GeoTIFF,JPEG2000,ASCII Grid,etcfor geometries, seesupported driversof thefionapackage :ESRI Shapefile,GeoJSON,GPKG,etcUsing the command-line interfaceA command-line interface is proposed with 5 available
actions (make_labels,make_rasters,make_tiles,make_annotationsandmake_all).Step-by-step commands1. Create labels from geometries and raster filesgeolabels make_labels IMG CATEGORIES2. Make virtual raster files to combine images and labelsgeolabels make_rasters IMG3. Split image and label virtual files creating tilesgeolabels make_tiles IMG_VRT LABEL_VRT TILES4. Create an annotation JSON file in the COCO format for a specific zoom levelgeolabels make_annotations TILES CATEGORIESOption:--zoom, the zoom levelGlobal commandTo run the full process to get a ground truth in the COCO format, use the command:geolabels make_all IMG TILES CATEGORIESOption:--zoom, the zoom levelImporting the package in Python codefromgeolabel_makerimportgeolabels# Create labels from geometries and raster filesgeolabels.make_labels(img,categories)# Make virtual raster files to combine images and labelsimages_vrt,labels_vrt=geolabels.make_rasters(img)# Split image and label virtual files creating tilesgeolabels.make_tiles(images_vrt,labels_vrt,tiles)# Create an annotation JSON file in the COCO formatgeolabels.make_annotations(tiles,categories)# OR# Run the full processgeolabels.make_all(img,tiles,categories)ExamplesThedata/folder contains geometries (vectors/) from Lyon, published as open data in the websitehttps://data.grandlyon.com.
It contains also an example of a JSON file describing categories used to create labels.This folder doesn't contain images because this type of file is too big to be supported in Github.
To follow our example, just download these two files and put them in the folderdata/rasters/:1843_5173_08_CC46.tif1844_5173_08_CC46.tifNotebooksSome Jupyter notebooks (in French) are available :Use_geolabel_maker.ipynbexplains the process to build your ground truth.Check_coco_annotations.ipynballows to explore your final annotations file.For developersInstall from sourcegit clone URL
cd geolabel-maker
pip install -e .Pre-commit and lintingInstall pre-commitand runpre-commit installto check linting before committing.When you want, you can force a pre-commit on all the files :pre-commit run --all-filesAcknowledgementsWe gratefully acknowledge the contributions of the people who
helped get this project off of the ground, including people who
beta tested the software, gave feedback, improved dependencies of
code in service of this release, or otherwise supported the project.Particularly thank youLucie Camanezto have initiate this project in its internship.We also acknowledgeAdam Kellywhose work has helped us in the development of this tool.