Welcome to CameraLib’s documentation!

CameraLib is a library for performing forward and backward projection of 2D coordinates in camera space to geographic coordinates on ODM datasets. It’s an official WebODM project.

Installation:

pip install -U https://github.com/WebODM/CameraLib/archive/main.zip

Quickstart:

Make sure that your ODM project has an elevation model available (pass the --dsm option when processing a dataset), then:

>>> from cameralib import Projector
>>> p = Projector("/dataset/brighton")
>>> p.world2cams(46.8423725961765, -91.99395518749954)
[{'filename': 'DJI_0028.JPG', 'x': 3576.5223779005346, 'y': 898.9714056819935}, {'filename': 'DJI_0027.JPG', 'x': 3640.8434954842614, 'y': 1670.683552000412}, {'filename': 'DJI_0031.JPG', 'x': 2066.0067963232805, 'y': 1252.4355627370903}, {'filename': 'DJI_0030.JPG', 'x': 2065.2268758465634, 'y': 255.93742225443987}, {'filename': 'DJI_0032.JPG', 'x': 1979.1241736591578, 'y': 2153.9211152055022}]
>>> p.cam2world("DJI_0028.JPG", [(3576.52, 898.97)])
[(46.84237264716458, -91.9939552609622, 165.27200317382812)]

Examples:

Getting Help / Reporting Issues:

If you find an issue please report it. We welcome contributions, see the GitHub page for more information.

For all development questions, please reach out on the `Community Forum`_.

License: AGPLv3, see LICENSE for more details.

API

class cameralib.Projector(project_path, z_sample_window=1, z_sample_strategy='median', z_sample_target='dsm', z_fill_nodata=True, raycast_resolution_multiplier=0.7071, dem_path=None)

A projector to perform camera coordinates operations on ODM datasets

Parameters:

  • project_path (str) – Path to ODM project

  • z_sample_window (int) – Size of the window to use when sampling elevation values

  • z_sample_strategy (str) – Strategy to use when sampling elevation values. Can be one of: [‘minimum’, ‘maximum’, ‘average’, ‘median’]

  • z_sample_target (str) – Elevation raster to use for sampling elevation. One of: [‘dsm’, ‘dtm’]

  • z_fill_nodata – Whether to fill nodata cells with nearest neighbor cell values. This gives a wider coverage for queries, but increases the initialization time.

  • raycast_resolution_multiplier (float) – Value that affects the ray sampling resolution. Lower values can lead to slightly more precise results, but increase processing time.

  • dem_path (str) – Manually set a path to a valid GeoTIFF DEM for sampling Z values instead of using the default.

cam2geoJSON(image, coordinates, properties={}, normalized=False)

Project 2D pixel coordinates in camera space to geographic coordinates and output the result as GeoJSON. A single coordinate results in a Point, two coordinates into a LineString and more than two into a Polygon.

Parameters:

  • image (str) – image filename

  • coordinates (list of tuples) – x,y pixel coordinates

  • normalized (bool) – whether the input coordinates are normalized to [0..1]

Returns:

GeoJSON

Return type:

dict

cam2world(image, coordinates, normalized=False)

Project 2D pixel coordinates in camera space to geographic coordinates

Parameters:

  • image (str) – image filename

  • coordinates (list of tuples) – x,y pixel coordinates

  • normalized (bool) – whether the input coordinates are normalized to [0..1]

Returns:

longitude,latitude,elevation for each coordinate pair

Return type:

list of tuples

world2cams(longitude, latitude, normalized=False)

Find which cameras in the reconstruction see a particular location.

Parameters:

  • longitude (float) – Longitude

  • latitude (float) – Latitude

  • normalized (bool) – Whether to normalize pixel coordinates by the image dimension. By default pixel coordinates are in range [0..image width], [0..image height])

Returns:

A list of dictionaries where each dictionary represents a camera with the following information: [

{

‘filename’: str # The filename of the image associated with the camera

’x’: float # The x-coordinate in camera space

’y’: float # The y-coordinate in camera space

}

]

Return type:

list of dict

cameralib.utils.read_xanylabeling_annotations(labels_dir)

Read an annotation file generated with X-AnyLabeling (https://github.com/CVHub520/X-AnyLabeling)

Parameters:

labels_dir (str) – Path to a directory containing X-AnyLabeling labels

Returns:

a list containing dictionaries with the following information [

{

‘image’: str # Image filename

’coordinates’: list # Coordinates of annotation

’properties’: dict # Properties of the annotation

’normalized’: bool # False

}

]

Return type:

list of dict

cameralib.utils.read_yolov7_annotations(labels_dir, image_suffix='.JPG')

Read an annotation directory in Yolov7 format

Parameters:

  • dir (str) – Path to a directory containing Yolov7 labels

  • image_suffix (str) – Extension of the target images

Returns:

a list containing dictionaries with the following information [

{

‘image’: str # Image filename

’coordinates’: list # Coordinates of annotation

’properties’: dict # Label of the annotation

’normalized’: bool # True

}

]

Return type:

list of dict

Indices and tables