Localization module lacks coordinate reference system (CRS) / projection support

[martinguthrie93]

Summary

The localization module operates purely on Cartesian coordinates in meters and has
no concept of a coordinate reference system (CRS). There is no support for EPSG codes,
geographic coordinates (latitude/longitude, WGS84), or automatic WGS84 ↔ UTM
conversion. Users must manually project their GPS coordinates to a metric system
(e.g., UTM) before using SynchronizedRecorderArray, and the estimated source
locations come back as bare meters with no georeferencing.

Current behavior

• SynchronizedRecorderArray(file_coords=...) expects receiver positions as
  (x, y) or (x, y, z) in meters
  (opensoundscape/localization/synchronized_recorder_array.py:78).
• Docstrings only recommend using "the UTM coordinate system"
  (opensoundscape/localization/localization_algorithms.py:82, :178), but no
  conversion is performed by the library.
• PositionEstimate.location_estimate is returned as (x, y, z) in meters with no
  CRS metadata (opensoundscape/localization/position_estimate.py:42).
• No geospatial dependency is present (geopandas, shapely, pyproj, etc. are
  absent from pyproject.toml).

Problem / impact

Field recorders (e.g. AudioMoth with GPS) typically record positions as
latitude/longitude. To use localization, users must:

1. Manually pick the correct UTM zone / EPSG code,
2. Convert every recorder's lat/lon to metric coordinates by hand,
3. Convert the estimated source location back to lat/lon to plot it on a map or
   export to a GIS tool (QGIS/ArcGIS).

This manual step is error-prone (wrong zone, hemisphere sign, mixed CRS) and blocks a
straightforward path from field GPS data → localization → mapped results.

Proposed enhancement

• Allow file_coords to optionally be supplied as lat/lon with an associated CRS/EPSG
  (auto-select UTM zone when not given).
• Attach the CRS to PositionEstimate and provide a helper to convert
  location_estimate back to lat/lon (e.g. via pyproj).
• Optionally add a lightweight export helper (e.g. GeoJSON) for the estimated
  positions.
• Keep pyproj an optional/extra dependency so the core install stays lean.

Alternatives considered

Users can pre/post-process with pyproj/geopandas themselves, but building minimal
CRS awareness into the localization API would remove a common, error-prone manual step.

Environment

• OpenSoundscape version:
• OS / Python:

[sammlapp]

Thanks for the suggestion. We'd be happy to review a pull request if you're interested in implementing this capability, but I don't think we have the bandwidth to add it ourselves at the moment.

[martinguthrie93]

Thanks, that sounds good — I'd be glad to take a shot at implementing this. Before I start writing code, would it help if I outlined the approach I have in mind here first, so you can flag anything that wouldn't fit the library's design or conventions? I'd rather check the direction with you before spending time on the implementation, and keep the PR focused and easy to review. A couple of things that would help me scope it well: - whether there's a preferred place in the codebase / existing pattern this should follow - anything you'd want covered (or explicitly kept out of scope) for a first PR - your expectations around tests and docs for a change like this Once the approach looks right to you, I'll put together a focused PR following your contributing guidelines. Thanks again for being open to it. martin

…

On Wed, Jul 1, 2026 at 9:34 PM Sam Lapp ***@***.***> wrote: *sammlapp* left a comment (kitzeslab/opensoundscape#1262) <#1262 (comment)> Thanks for the suggestion. We'd be happy to review a pull request if you're interested in implementing this capability, but I don't think we have the bandwidth to add it ourselves at the moment. — Reply to this email directly, view it on GitHub <#1262?email_source=notifications&email_token=CHBCBSGGWIC4FSFN6NYERDT5CVRUBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBVHEZTSOJQG4Z2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4859399073>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CHBCBSBMCCGIUXACGDI6WYD5CVRUBAVCNFSNUABFKJSXA33TNF2G64TZHMYTIOJRHAZDGNZTHNEXG43VMU5TINZYGYYDSNRVG43KC5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/CHBCBSD4LUD73LEL3SAHKR35CVRUBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBVHEZTSOJQG4Z2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/CHBCBSCKOW7DAKKJFRPAPTT5CVRUBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBVHEZTSOJQG4Z2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[sammlapp]

Great! Thanks for asking. I'd see it as:

• implement a separate module within the opensoundscape/localization/ folder, eg crs_utilities.py, if needed
• implement the proposed methods for PositionEstimate and SynchronizedRecorderArray leveraging these utilities
• ensure added dependencies are optional by importing on as-needed basis or wrapping import in try/except. Raise helpful error when the dependency is needed but not available.
• add the optional dependency to the pyproject.toml optional dependencies list
• add tests for each new functionality to the pytest suite
• match opso Docstring conventions for specifying arguments and returns
• add a short example at the end of the localization tutorial demonstrating the use of these added functionalities

Happy to review a proposed plan!

[martinguthrie93]

Perfect, thanks for laying it out so clearly — that gives me a solid target. Here's the plan I'll follow, mapped to your points: 1. New module `opensoundscape/localization/crs_utilities.py` holding the CRS/coordinate helpers. 2. Add the proposed methods to `PositionEstimate` and `SynchronizedRecorderArray`, delegating the coordinate work to those utilities. 3. Keep the new geospatial dependency optional: import it lazily (or wrap in try/except), and raise a clear, actionable error when a method needs it but it's missing. 4. Register the dependency under an optional-dependencies extra in `pyproject.toml`. 5. Add pytest coverage for each new method (including the "dependency missing" error path). 6. Follow the opso docstring conventions for args/returns. 7. Add a short worked example at the end of the localization tutorial. A couple of small checks before I build: - Naming: is `crs_utilities.py` your preferred name, or would you rather it sit under an existing utils module? - For the optional dependency, do you have a preferred library for the CRS/transform work, or is that my call as long as it stays optional? On the PR: I actually pushed an early draft ahead of this conversation — please ignore its current shape. Once you're happy with the plan above I'll rework it to match these conventions exactly and keep it focused for review. Thanks again for the clear guidance.

…

On Thu, Jul 2, 2026 at 5:54 PM Sam Lapp ***@***.***> wrote: *sammlapp* left a comment (kitzeslab/opensoundscape#1262) <#1262 (comment)> Great! Thanks for asking. I'd see it as: - implement a separate module within the opensoundscape/localization/ folder, eg crs_utilities.py, if needed - implement the proposed methods for PositionEstimate and SynchronizedRecorderArray leveraging these utilities - ensure added dependencies are optional by importing on as-needed basis or wrapping import in try/except. Raise helpful error when the dependency is needed but not available. - add the optional dependency to the pyproject.toml optional dependencies list - add tests for each new functionality to the pytest suite - match opso Docstring conventions for specifying arguments and returns - add a short example at the end of the localization tutorial demonstrating the use of these added functionalities Happy to review a proposed plan! — Reply to this email directly, view it on GitHub <#1262?email_source=notifications&email_token=CHBCBSAFM5AUJNEM26HHLED5C2ARRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBWG43DMOBTGI42M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4867668329>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CHBCBSBRU5DBVLDNE2ZI7C35C2ARRAVCNFSNUABFKJSXA33TNF2G64TZHMYTIOJRHAZDGNZTHNEXG43VMU5TINZYGYYDSNRVG43KC5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/CHBCBSFPBVKKNGZ2MDHZARL5C2ARRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBWG43DMOBTGI42M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/CHBCBSF32EZKC4HF4PA2O635C2ARRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBWG43DMOBTGI42M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>