locateobject 0.1.0__tar.gz

locateobject-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+
+
+Copyright 2026 Joost Postma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

locateobject-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: locateobject
+Version: 0.1.0
+Summary: Locate real-world objects by triangulating bounding boxes from multiple geotagged images
+Author: Joost Postma
+License-Expression: MIT
+Keywords: triangulation,locateobject,geospatial,photogrammetry,panoramax,gis
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4
+Requires-Dist: pandas>=3.0
+Requires-Dist: shapely>=2.1
+Requires-Dist: geopandas>=1.1
+Requires-Dist: pyproj>=3.7
+Requires-Dist: scipy>=1.17
+Requires-Dist: scikit-learn>=1.8
+Requires-Dist: geopy>=2.4
+Requires-Dist: haversine>=2.9
+Dynamic: license-file
+
+# locateobject
+
+Locate real-world objects by triangulating bounding boxes from multiple geotagged images.
+
+You give `locateobject` a set of annotations (one bounding box of one object in one image, plus the camera position and orientation). It works out where the objects are, groups annotations that belong to the same object, and returns the results as GeoDataFrames you can save straight to GeoPackage.
+
+The package exposes a single function: `locate_object()`.
+
+## Installation
+
+```bash
+pip install locateobject
+```
+
+Requires Python 3.11 or newer.
+
+## How it works
+
+1. **Bearing line per annotation.** The horizontal centre of the bounding box gives a compass bearing from the camera (using the image width, field of view and camera azimuth). The vertical size of the bounding box gives the angular size of the object. Combined with the minimum and maximum real-world size of the object, this gives a *line segment* along that bearing where the object can be.
+2. **Intersections.** Segments from different annotations that cross are candidate object locations.
+3. **Filtering.** An intersection is kept only if the angle between the two bearings is within the allowed range (a very small angle gives poor location precision) and the two annotations estimate a similar object size.
+4. **Clustering.** Intersections are grouped with a recursive DBSCAN clustering until every cluster is tighter than `cluster_radius_m_max`. Each annotation line can belong to at most one cluster.
+5. **Centroids.** Each cluster becomes a centroid (the object location). Annotation lines close to a centroid are assigned to the best-scoring centroid, and centroids supported by fewer than two annotations are dropped.
+
+## Quick start
+
+```python
+from shapely.geometry import Point
+from locateobject import locate_object
+
+# A 360 degree panorama, 8192 px wide. The object is a 1 m tall sign
+# about 10 m north of camera 1.
+records = [
+    {
+        "origin": Point(5.0000, 52.0000),          # (longitude, latitude)
+        "picture_field_of_view": 360,
+        "picture_azimuth": 0,
+        "picture_size_horizontal_px": 8192,
+        "picture_size_vertical_px": 4096,
+        "bbox": [[4046, 1000], [4146, 1000], [4146, 1130], [4046, 1130], [4046, 1000]],
+        "object_minimum_size_meters": 0.5,
+        "object_maximum_size_meters": 1.5,
+    },
+    {
+        "origin": Point(5.000146, 52.0000),        # about 10 m east of camera 1
+        "picture_field_of_view": 360,
+        "picture_azimuth": 0,
+        "picture_size_horizontal_px": 8192,
+        "picture_size_vertical_px": 4096,
+        "bbox": [[3026, 1000], [3118, 1000], [3118, 1092], [3026, 1092], [3026, 1000]],
+        "object_minimum_size_meters": 0.5,
+        "object_maximum_size_meters": 1.5,
+    },
+]
+
+labels, centroids, clusters, inter_reliable, inter_all, annotations = locate_object(records)
+
+print(labels)       # centroid id for each input record, -1 if unassigned
+print(centroids)    # one row per located object
+```
+
+Save the results for use in QGIS or other GIS software:
+
+```python
+centroids.to_file("result.gpkg", layer="centroids", driver="GPKG")
+annotations.to_file("result.gpkg", layer="annotations", driver="GPKG")
+```
+
+## Input
+
+`records_input` is a list of dictionaries (`ObjectAnnotationInput`), one per object in one image:
+
+| Key | Type | Description |
+|---|---|---|
+| `origin` | `shapely.geometry.Point` | Camera position. `x` = longitude, `y` = latitude (EPSG:4326). |
+| `picture_field_of_view` | `float` or `int` | Horizontal field of view of the image in degrees (360 for a full panorama). |
+| `picture_azimuth` | `float` or `int` | Compass direction of the image centre in degrees (0 = north, clockwise). |
+| `picture_size_horizontal_px` | `int` | Image width in pixels. |
+| `picture_size_vertical_px` | `int` | Image height in pixels. |
+| `bbox` | `list[list[int]]` | Polygon of the object in pixel coordinates, `[[x1, y1], [x2, y2], ...]`, at least 3 points, integers only. If the first and last point differ, the polygon is closed automatically. |
+| `object_minimum_size_meters` | `float` or `int` | Smallest plausible real-world height of the object, in metres. |
+| `object_maximum_size_meters` | `float` or `int` | Largest plausible real-world height of the object, in metres. |
+
+The size of the object is taken from the **vertical** extent of the bounding box, so the minimum and maximum sizes refer to the object's height. The wider the range between minimum and maximum, the longer the line along which the object can be located.
+
+Annotations with an invalid bounding box or a line that cannot be calculated are skipped with a warning.
+
+## Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `intersection_angle_deg_min` | `15` | Minimum angle in degrees between two bearings. Small angles give imprecise locations. |
+| `intersection_angle_deg_max` | `None` (360) | Maximum angle between two bearings. Use it to exclude cameras that cannot plausibly see the same object. |
+| `object_size_score` | `0.8` | Minimum size agreement (0 to 1) between the two annotations of an intersection. A score of 1 means identical size estimates. |
+| `cluster_radius_m_max` | `1` | Maximum distance in metres between a cluster centre and its intersections. Also the maximum distance from a centroid to an annotation line for it to be assigned. |
+| `cluster_min_size` | `1` | Minimum number of intersections for a cluster (DBSCAN `min_samples`). |
+| `cluster_max_depth` | `None` | Maximum recursion depth of the clustering. By default it is derived from `cluster_epsilon_decrease`. |
+| `cluster_epsilon_start` | `None` | Starting DBSCAN radius in metres. Defaults to `cluster_radius_m_max`. |
+| `cluster_epsilon_decrease` | `0.8` | Factor by which the DBSCAN radius shrinks at each recursion level. |
+
+## Output
+
+`locate_object()` returns a tuple of six items:
+
+```python
+labels, centroids, clusters, intersections_reliable, intersections, annotations = locate_object(records)
+```
+
+1. **`labels`**: list of integers, one per input record, in the same order. The `id` of the centroid the record belongs to, or `-1` if it was not assigned.
+2. **`centroids`**: GeoDataFrame (points) with the final object locations.
+3. **`clusters`**: GeoDataFrame (points) with the cluster centres before the final assignment.
+4. **`intersections_reliable`**: GeoDataFrame (points) with the intersections that passed the angle and size filters.
+5. **`intersections`**: GeoDataFrame (points) with all intersections found.
+6. **`annotations`**: GeoDataFrame (lines) with the location line of every valid annotation.
+
+All GeoDataFrames use `EPSG:4326`. If there is no result, empty GeoDataFrames are returned and `labels` contains only `-1`.
+
+### Columns
+
+**`centroids`**
+
+| Column | Description |
+|---|---|
+| `id` | Centroid id, matches `labels` and `annotations.centroid_id`. |
+| `object_size_meter` | Mean estimated object size in metres. |
+| `object_size_meter_sd` | Standard deviation of the size estimates. |
+| `object_azimuth` | Direction in degrees from which the object is seen head-on (the average viewing direction plus 180). |
+
+**`clusters`**: `object_size_meter`, `object_size_meter_sd`, `object_azimuth` (as above).
+
+**`intersections_reliable`** and **`intersections`**
+
+| Column | Description |
+|---|---|
+| `angle` | Angle in degrees between the two bearings. |
+| `object_size_average_meter` | Average of the two size estimates at the intersection. |
+| `object_size_score` | Size agreement between the two annotations (0 to 1). |
+| `line1`, `line2` | Index in `records_input` of the two annotations. |
+
+**`annotations`**
+
+| Column | Description |
+|---|---|
+| `id` | Index of the record in `records_input`. |
+| `centroid_id` | Assigned centroid, or missing if the annotation was not assigned. |
+| `origin_longitude`, `origin_latitude` | Camera position. |
+| `line_azimuth` | Compass bearing of the line in degrees. |
+| `object_distance_meter` | Distance from camera to the centroid (only if assigned). |
+| `object_size_meter` | Object size estimated from this annotation at the centroid (only if assigned). |
+
+## Notes and limitations
+
+- The distance estimate assumes the field of view and pixel size describe an undistorted horizontal view (as in equirectangular panoramas). Strongly distorted images give less accurate results.
+- Pixel coordinates have `x` increasing to the right, and `x` wraps around the image seam for panoramas.
+- The intersection search works in a local metric projection and is meant for areas of limited size (around 100 km by 100 km).
+- At least two annotations from different positions are needed to locate an object.
+
+## Logging
+
+The package uses the standard `logging` module and attaches a `NullHandler`, so it is silent by default. To see progress and warnings:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+## License
+
+MIT, see the `LICENSE` file.

locateobject-0.1.0/README.md

@@ -0,0 +1,169 @@
+# locateobject
+
+Locate real-world objects by triangulating bounding boxes from multiple geotagged images.
+
+You give `locateobject` a set of annotations (one bounding box of one object in one image, plus the camera position and orientation). It works out where the objects are, groups annotations that belong to the same object, and returns the results as GeoDataFrames you can save straight to GeoPackage.
+
+The package exposes a single function: `locate_object()`.
+
+## Installation
+
+```bash
+pip install locateobject
+```
+
+Requires Python 3.11 or newer.
+
+## How it works
+
+1. **Bearing line per annotation.** The horizontal centre of the bounding box gives a compass bearing from the camera (using the image width, field of view and camera azimuth). The vertical size of the bounding box gives the angular size of the object. Combined with the minimum and maximum real-world size of the object, this gives a *line segment* along that bearing where the object can be.
+2. **Intersections.** Segments from different annotations that cross are candidate object locations.
+3. **Filtering.** An intersection is kept only if the angle between the two bearings is within the allowed range (a very small angle gives poor location precision) and the two annotations estimate a similar object size.
+4. **Clustering.** Intersections are grouped with a recursive DBSCAN clustering until every cluster is tighter than `cluster_radius_m_max`. Each annotation line can belong to at most one cluster.
+5. **Centroids.** Each cluster becomes a centroid (the object location). Annotation lines close to a centroid are assigned to the best-scoring centroid, and centroids supported by fewer than two annotations are dropped.
+
+## Quick start
+
+```python
+from shapely.geometry import Point
+from locateobject import locate_object
+
+# A 360 degree panorama, 8192 px wide. The object is a 1 m tall sign
+# about 10 m north of camera 1.
+records = [
+    {
+        "origin": Point(5.0000, 52.0000),          # (longitude, latitude)
+        "picture_field_of_view": 360,
+        "picture_azimuth": 0,
+        "picture_size_horizontal_px": 8192,
+        "picture_size_vertical_px": 4096,
+        "bbox": [[4046, 1000], [4146, 1000], [4146, 1130], [4046, 1130], [4046, 1000]],
+        "object_minimum_size_meters": 0.5,
+        "object_maximum_size_meters": 1.5,
+    },
+    {
+        "origin": Point(5.000146, 52.0000),        # about 10 m east of camera 1
+        "picture_field_of_view": 360,
+        "picture_azimuth": 0,
+        "picture_size_horizontal_px": 8192,
+        "picture_size_vertical_px": 4096,
+        "bbox": [[3026, 1000], [3118, 1000], [3118, 1092], [3026, 1092], [3026, 1000]],
+        "object_minimum_size_meters": 0.5,
+        "object_maximum_size_meters": 1.5,
+    },
+]
+
+labels, centroids, clusters, inter_reliable, inter_all, annotations = locate_object(records)
+
+print(labels)       # centroid id for each input record, -1 if unassigned
+print(centroids)    # one row per located object
+```
+
+Save the results for use in QGIS or other GIS software:
+
+```python
+centroids.to_file("result.gpkg", layer="centroids", driver="GPKG")
+annotations.to_file("result.gpkg", layer="annotations", driver="GPKG")
+```
+
+## Input
+
+`records_input` is a list of dictionaries (`ObjectAnnotationInput`), one per object in one image:
+
+| Key | Type | Description |
+|---|---|---|
+| `origin` | `shapely.geometry.Point` | Camera position. `x` = longitude, `y` = latitude (EPSG:4326). |
+| `picture_field_of_view` | `float` or `int` | Horizontal field of view of the image in degrees (360 for a full panorama). |
+| `picture_azimuth` | `float` or `int` | Compass direction of the image centre in degrees (0 = north, clockwise). |
+| `picture_size_horizontal_px` | `int` | Image width in pixels. |
+| `picture_size_vertical_px` | `int` | Image height in pixels. |
+| `bbox` | `list[list[int]]` | Polygon of the object in pixel coordinates, `[[x1, y1], [x2, y2], ...]`, at least 3 points, integers only. If the first and last point differ, the polygon is closed automatically. |
+| `object_minimum_size_meters` | `float` or `int` | Smallest plausible real-world height of the object, in metres. |
+| `object_maximum_size_meters` | `float` or `int` | Largest plausible real-world height of the object, in metres. |
+
+The size of the object is taken from the **vertical** extent of the bounding box, so the minimum and maximum sizes refer to the object's height. The wider the range between minimum and maximum, the longer the line along which the object can be located.
+
+Annotations with an invalid bounding box or a line that cannot be calculated are skipped with a warning.
+
+## Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `intersection_angle_deg_min` | `15` | Minimum angle in degrees between two bearings. Small angles give imprecise locations. |
+| `intersection_angle_deg_max` | `None` (360) | Maximum angle between two bearings. Use it to exclude cameras that cannot plausibly see the same object. |
+| `object_size_score` | `0.8` | Minimum size agreement (0 to 1) between the two annotations of an intersection. A score of 1 means identical size estimates. |
+| `cluster_radius_m_max` | `1` | Maximum distance in metres between a cluster centre and its intersections. Also the maximum distance from a centroid to an annotation line for it to be assigned. |
+| `cluster_min_size` | `1` | Minimum number of intersections for a cluster (DBSCAN `min_samples`). |
+| `cluster_max_depth` | `None` | Maximum recursion depth of the clustering. By default it is derived from `cluster_epsilon_decrease`. |
+| `cluster_epsilon_start` | `None` | Starting DBSCAN radius in metres. Defaults to `cluster_radius_m_max`. |
+| `cluster_epsilon_decrease` | `0.8` | Factor by which the DBSCAN radius shrinks at each recursion level. |
+
+## Output
+
+`locate_object()` returns a tuple of six items:
+
+```python
+labels, centroids, clusters, intersections_reliable, intersections, annotations = locate_object(records)
+```
+
+1. **`labels`**: list of integers, one per input record, in the same order. The `id` of the centroid the record belongs to, or `-1` if it was not assigned.
+2. **`centroids`**: GeoDataFrame (points) with the final object locations.
+3. **`clusters`**: GeoDataFrame (points) with the cluster centres before the final assignment.
+4. **`intersections_reliable`**: GeoDataFrame (points) with the intersections that passed the angle and size filters.
+5. **`intersections`**: GeoDataFrame (points) with all intersections found.
+6. **`annotations`**: GeoDataFrame (lines) with the location line of every valid annotation.
+
+All GeoDataFrames use `EPSG:4326`. If there is no result, empty GeoDataFrames are returned and `labels` contains only `-1`.
+
+### Columns
+
+**`centroids`**
+
+| Column | Description |
+|---|---|
+| `id` | Centroid id, matches `labels` and `annotations.centroid_id`. |
+| `object_size_meter` | Mean estimated object size in metres. |
+| `object_size_meter_sd` | Standard deviation of the size estimates. |
+| `object_azimuth` | Direction in degrees from which the object is seen head-on (the average viewing direction plus 180). |
+
+**`clusters`**: `object_size_meter`, `object_size_meter_sd`, `object_azimuth` (as above).
+
+**`intersections_reliable`** and **`intersections`**
+
+| Column | Description |
+|---|---|
+| `angle` | Angle in degrees between the two bearings. |
+| `object_size_average_meter` | Average of the two size estimates at the intersection. |
+| `object_size_score` | Size agreement between the two annotations (0 to 1). |
+| `line1`, `line2` | Index in `records_input` of the two annotations. |
+
+**`annotations`**
+
+| Column | Description |
+|---|---|
+| `id` | Index of the record in `records_input`. |
+| `centroid_id` | Assigned centroid, or missing if the annotation was not assigned. |
+| `origin_longitude`, `origin_latitude` | Camera position. |
+| `line_azimuth` | Compass bearing of the line in degrees. |
+| `object_distance_meter` | Distance from camera to the centroid (only if assigned). |
+| `object_size_meter` | Object size estimated from this annotation at the centroid (only if assigned). |
+
+## Notes and limitations
+
+- The distance estimate assumes the field of view and pixel size describe an undistorted horizontal view (as in equirectangular panoramas). Strongly distorted images give less accurate results.
+- Pixel coordinates have `x` increasing to the right, and `x` wraps around the image seam for panoramas.
+- The intersection search works in a local metric projection and is meant for areas of limited size (around 100 km by 100 km).
+- At least two annotations from different positions are needed to locate an object.
+
+## Logging
+
+The package uses the standard `logging` module and attaches a `NullHandler`, so it is silent by default. To see progress and warnings:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+## License
+
+MIT, see the `LICENSE` file.

locateobject-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "locateobject"
+dynamic = ["version"]             # read from __version__ in __init__.py
+description = "Locate real-world objects by triangulating bounding boxes from multiple geotagged images"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Joost Postma" }]
+keywords = ["triangulation", "locateobject", "geospatial", "photogrammetry", "panoramax", "gis"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=2.4",
+    "pandas>=3.0",
+    "shapely>=2.1",
+    "geopandas>=1.1",
+    "pyproj>=3.7",
+    "scipy>=1.17",
+    "scikit-learn>=1.8",
+    "geopy>=2.4",
+    "haversine>=2.9",
+]
+
+# [project.urls]
+# Source = "https://github.com/joost_72/objectlocation"
+
+[tool.setuptools.dynamic]
+version = { attr = "locateobject.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

locateobject-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

locateobject-0.1.0/src/locateobject/__init__.py

@@ -0,0 +1,22 @@
+import logging
+# from importlib import resources
+# import tomllib
+
+from .locate import locate_object
+
+
+# Version of the locateobject package
+__version__ = "0.1.0"
+
+# Library rule: attach a NullHandler to the package's top-level logger.
+# This silences "no handlers found" warnings if the caller configures nothing,
+# and leaves all real handler/level setup to the application.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["locate_object"]
+
+
+# Read URL of the Real Python feed from config file
+# _cfg = tomllib.loads(resources.read_text("triangulation", "config.toml"))
+# EARTH_RADIUS_M = _cfg["general"]["EARTH_RADIUS_M"]
+# print(f'EARTH_RADIUS_M: {EARTH_RADIUS_M}')