Package: cv2geojson
cv2geojsoncv2geojson is an open-source project to export annotation contours extracted usingOpenCV-pythonpackage toGeoJSONformat.ContentsIntroductionExample 1Example 2InstallationMain Methodsfind_geocontoursdraw_geocontoursexport_annotationsload_annotationsclass GeoContourAttributescontourstypeMethodsget_contoursexport_geometryexport_featureareamin_enclosing_circlecircularitysolidityaspect_ratioelongationholes_numfill_holescale_upscale_downcopyIntroductionContours can be defined as continuous curves that connect points of the same color or intensity along a boundary. They are commonly used for shape analysis, object detection, and recognition. For instance, in liver pathology, fat vacuoles can be identified as circular white blobs (check out thislinkfor an example). The traditional method to extract contours inOpenCVis by utilizingcv2.findContours. However, these extracted contours are not easily visualized in third-party software tools such asQuPath. To overcome this limitation, thecv2geojsonPython package provides a seamless bridge between the contours extracted usingOpenCVand the geometries represented asGeoJSONobjects. By converting the extracted contours to theGeoJSONformat, they can be easily visualized and utilized in various software tools.Example 1In digital pathology, images can be quite large. For example, download the whole slide image with tissue sample IDGTEX-12584-1526fromhistology page. This image has 45,815x38,091 pixels which requires about 5GB of storage uncompressed. Rather than storing a binary mask for the foreground segmentation, the mask can be converted to polygons and stored as a geojson file. The image below shows a snapshot from the QuPath software. The foreground contour is blue.Snapshot from QuPath software visualising foreground segmentationExample 2Here is a dummy example to demonstrate the utility of cv2geojson package.import cv2 as cv
from cv2geojson import find_geocontours, export_annotations

# read sample image
img = cv.imread('./example/img_01.png')
mask = cv.cvtColor(img, cv.COLOR_BGR2GRAY)

# Extract annotation contours
geocontours = find_geocontours(mask, mode='imagej')

# convert geocontours to geojson.Feature format
features = [contour.export_feature(color=(0, 255, 0), label='roi') for contour in geocontours]
export_annotations(features, './example/img_01.geojson')InstallationThe recommended way to install is via pip:pip install cv2geojsonMain Methodsfind_geocontours(mask, mode='opencv')This function, similar tocv2.findContours, retrieves contours from the binary mask and grouped them as geometries similar toGeoJSONobjects. The geometries are a useful tool for shape analysis or object detection.Parameters:mask: {numpy.ndarray}: binary mask of value 255 or 0mode: {str}: the contour represetnation method; either 'imagej' or 'opencv'Returns:geocontours: {cv2geojson.geocontours}: a list of detected  geomtries: Polgy, Point, or LineStringNote:OpenCVcontours are based on pixel centers whereasimagejcontours are based on pixel edges. Both methods are plausible options butimagejmethod is recommended for visualisation inQuPath. Here is a short script to demonstrate the differences between the two methods.import numpy as np
from cv2geojson import find_geocontours

# define a binary mask
mask = np.array([[0,   0, 0, 0, 0],
                 [0,   0, 0, 0, 0],
                 [0, 255, 0, 0, 0],
                 [0,   0, 0, 0, 0],
                 [0,   0, 0, 0, 0]], dtype=np.uint8)

# extract geocontours
geocontour_opencv = find_geocontours(mask, mode='opencv')[0]
geocontour_imagej = find_geocontours(mask, mode='imagej')[0]

print(f'Poplygon Coordinates using OpenCV method: {geocontour_opencv.export_geometry()}')
print(f'Poplygon Coordinates using ImageJ method: {geocontour_imagej.export_geometry()}')The following result is printed:Poplygon Coordinates using OpenCV method: {"coordinates": [1, 2], "type": "Point"}
Poplygon Coordinates using ImageJ method: {"coordinates": [[[1, 2], [1, 3], [2, 3], [2, 2], [1, 2]]], "type": "Polygon"}draw_geocontours(mask, geocontours, scale=1, offset=(0, 0), mode='opencv')This function, similar tocv2.drawContours, draw geocontours to the corresponding binary mask.Parameters:mask: {numpy.ndarray}: binary mask of value 255 or 0goecontours: {list: cv2geojson.GeoContour}scale: {int}: downsampling ratiooffset: {tuple: 2}: offset displacementmode: {str}: either 'imagej' or 'opencv'export_annotations(features, path_to_geojson)This function writeGeoJSON.Featureobjects to a file.Parameters:features: {list: geojson.feature.Feature}path_to_geojson: {str}Here is a short script to demonstrate its usage. Also seeexport_featureimport numpy as np
from cv2geojson import find_geocontours, export_annotations

# define a binary mask
mask = np.array([[0,   0,   0,   0, 0],
                 [0,   0,   0,   0, 0],
                 [0, 255, 255, 255, 0],
                 [0, 255, 255, 255, 0],
                 [0,   0,   0,   0, 0],
                 [0,   0,   0,   0, 0]], dtype=np.uint8)

# extract geocontours
geocontours = find_geocontours(mask, mode='imagej')

# export features
features = []
for geocontour in geocontours:
    features.append(geocontour.export_feature(color=(255, 0, 0),
                                              label='rectangle',
                                              name='ID1'))
export_annotations(features, 'test.geojson')load_annotations(path_to_geojson)This function readGeoJSONobjects from a file and convert them tocv2geojson.GeoContour.Parameters:path_to_geojson: {str}Returns: geocontours: {list: cv2geojson.GeoContour}class GeoContourThe library implements a new class,cv2geojson.GeoContour, which facilitates the seamless integration of contours extracted usingcv2.findContoursand geometries defined as GeoJSON objects. An instance of this class can be initialized by providing either contours or GeoJSON objects. Here is an example of how to initialize the class using both a GeoJSON object and NumPy contours:import numpy as np
from geojson import LineString
from cv2geojson import GeoContour

# initialise GeoContour class with a geojson LineString object
geometry = LineString([(1, 2), (5, 15)])
geocontour_1 = GeoContour(geometry=geometry)

# initialise GeoContour class with contours
geocontour_2 = GeoContour(contours=[np.array([[1, 2], [5, 15]])])Attributes:contourslist of numpy.ndarray: the coordinates of the geometrytypestr: Point, LineString, or PolygonMethods:get_contours(self, scale=1, offset=(0, 0))Parameters:scale: {int}: the down-scaling ratiooffset: {tuple: 2}Returns: contours: {list of numpy.ndarray}: (contours - offset)/scaleexport_geometry(self)Returns: {geojson.Point, geojson.LineString, geojson.Polgyon}export_feature(self, color=None, label=None, name=None)Parameters:color: {tuple: 3}: (r, g, b) in range 0 to 255label: {str}: the class name for the identified geometryname: {str}: the unique ID given to the identified geometryReturns: {geojson.Feature}: append provided properties to the geometryarea(self, resolution=1.0)Parameters:resolution: {float}: the pixel size in micro-meterReturns: {float}: the total area of polygon in micro-meter-squaredmin_enclosing_circle(self)Returns:center: {tuple: 2}: (x, y) coordinatesradius: {float}: radius in pixelscircularity(self)Returns: {float}: $4\pi \text{Area}/\text{Perimeter}^2$solidity(self)Returns: {float}: the polygon area divided by its convex hull areaaspect_ratio(self)Returns: {float}: the width of the enclosing rectangle divided by its heightelongation(self)Returns: {float}: the minor to major diameter of the enclosing ovalholes_num(self)Returns: {int}: the number of holes in the polygonfill_hole(self, resolution=1.0, hole_size=-1.0)Remove any holes in the polygon larger than hole_sizeParameters:resolution: {float}: the pixel size in micro-meterhole_size: {float}: the hole area in micro-meter-squared. If -1, all holes will be filled.scale_up(self, ratio=1, offset=(0, 0))Scale up the coodinates: x_new = (ratio * x_old) + offsetParameters:ratio: {int}offset: {tuple: 2}scale_down(self, ratio=1, offset=(0, 0))Scale down the coodinates: x_new = (x_old - offset) / ratioParameters:ratio: {int}offset: {tuple: 2}copy(self)Returns: {cv2geojson.GeoContour}