Skip to content

feat(engine): map.convertPosition gives a place in every form RustGIS writes (#1042) - #2312

Merged
deniial00 merged 4 commits into
opengeos:mainfrom
flight1973:feat/1042-convert-position
Nov 17, 2026
Merged

deniial00 merged 4 commits into
opengeos:mainfrom
flight1973:feat/1042-convert-position

Conversation

@flight1973

@flight1973 flight1973 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Piece 6 of #1042: map.convertPosition, a command that gives a place in every form RustGIS writes one, for scripts, Python and the AI Assistant. It doesn't move the map.

  • It reads the place the way map.goToXY does: lon and lat (numbers, or degrees, minutes and seconds), or a position in any form the search box reads (decimal or DMS, UTM, UPS, MGRS).

  • It answers with:

    • lon and lat, plus decimal and dms as the status bar writes them;
    • grid (utm, or ups from 84° N and south of 80° S), and the reference in utm or ups;
    • the UTM zone and band, hemisphere, easting and northing in meters;
    • mgrs (spaced, as the readout writes it) and mgrsCompact.

    digits (0 to 5) sets the MGRS precision. Every key is always present, null where it has no value.

  • What the reading assumed is said, as goToXY says it: two bare numbers read latitude first, or an MGRS square taken at its center.

  • On another body's map the Earth's grids are null, and note says why.

  • map.goToXY and map.convertPosition now share one reader of the place, so they can't drift apart.

  • It's in the Assistant's list of common commands, and the Coordinate readouts section of docs/user-guide/maps.md documents it with a CLI and a Python example.

rustgis-cli run --cmd 'map.convertPosition={"position":"18TWL8395907350"}'

returns, among the rest, "grid": "utm", "zone": 18, "band": "T", "easting": 583959.5, "northing": 4507350.5 (the center of that 1 m square), and "mgrs": "18T WL 83959 07350".

No new dependency; nothing changes in map.goToXY's behavior.

Surfaces

  • Command line, Python, MCP and the Assistant: it's a command, so rustgis-cli run --cmd, Session.run, run_command and the Assistant all reach it. Its parameters come from the registry, and it's in the Assistant's common commands, so the Assistant sees it without a search.
  • Browser: it's in the engine, with no file or network access, so the web app runs it the same way.
  • Plugins: they can run it like any other command. It has no effects (Effects::NONE), so it needs no permission.
  • Desktop and phone: there's no button or dialog, on purpose. The status-bar readout already shows each form for the pointer, and the right-click menu copies it. Command search lists it as needing parameters, like map.zoomToExtent.
  • The way back: it's read-only, with nothing to undo or reopen.

Testing

  • cargo xtask ci passes.
  • convert_position_gives_every_form covers:
    • New York written five ways, checked against GeographicLib's GeoConvert values that goToXY's test already uses;
    • UPS at 85° N 30° E and the Svalbard zone 33 at 83.9° N 10° E, checked against PROJ 9 (EPSG:32661 and EPSG:32633);
    • MGRS truncation to fewer digits (including 2.0), the two notices and their absence, refusals, the map not moving, and a map of Mars;
    • the equator: a tiny negative latitude comes back as 0 with every form in the north, and a northing just south of it stays short of 10,000,000 m.
  • go_to_xy_reads_a_position_as_the_search_box_does passes unchanged.

UI evidence

No visible UI change.

Related issue

Part of #1042 (piece 6).

… writes (opengeos#1042)

A read-only command for scripts, Python and the AI Assistant (opengeos#1042, piece 6). It reads the place as map.goToXY does (lon and lat, or a position in any form the search box reads) and answers with longitude and latitude, decimal degrees and DMS as the status bar writes them, UTM (UPS in the polar areas) with its zone, band, hemisphere, easting and northing, and MGRS spaced and in one word, to 0 to 5 digits. What the reading assumed is said as goToXY says it; the map doesn't move; on another body's map the grids are null and a note says why.

map.goToXY and map.convertPosition share one reader of the place.
…on every body, and says a missing MGRS

UPS goes in its own ups key (grid says which), note is always present, a missing MGRS reference is said in note, and degrees read from degrees, minutes and seconds come back without float noise.
…ers -0, and is among the Assistant's common commands
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The change adds map.convertPosition to convert position inputs into coordinate and grid representations without moving the map. Navigation shares position parsing with the conversion command. The assistant command list, tests, and user guide include the new command.

Changes: Position Conversion

Layer / File(s) Summary
Shared position parsing
crates/engine/src/cmd/navigate.rs
go_to_xy and map.convertPosition use typed_place to parse position inputs and produce operation-specific interpretation notices. Navigation retains its camera movement and optional scale, bearing, and pitch handling.
Conversion command and validation
crates/engine/src/cmd/navigate.rs, crates/assistant/src/agent.rs, crates/engine/src/tests.rs, docs/user-guide/maps.md
The registered command returns coordinate and grid representations, with configurable MGRS precision and null for unavailable fields. The assistant command list, tests, and user guide cover the command.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller as Command caller
  participant Convert as convert_position
  participant Parse as typed_place
  Caller->>Convert: position input and digits
  Convert->>Parse: parse and interpret position
  Parse-->>Convert: coordinate and optional notice
  Convert-->>Caller: coordinate and grid representations
Loading

Possibly related issues

  • Issue 1042 requests position conversion among longitude/latitude, UTM, and MGRS for CLI, Python, and the AI Assistant. This change adds the conversion command and assistant availability.

Possibly related PRs

  • opengeos/RustGIS#1429: That PR adds UTM and MGRS parsing to search and readouts. This command accepts search-box-style position inputs and returns UTM and MGRS representations.

Suggested reviewers: giswqs

Merge Risk: Minimal · up to 97847

This adds a read-only conversion command that does not move the map, shares place parsing with go-to, and includes tests and documentation. No concrete defect was found, so merge risk is minimal.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: a new map.convertPosition command in the engine that gives a place in every form RustGIS writes. It follows the feat(engine) convention and names the command and the s…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description follows the repository template closely. It covers the Summary (what the command does, its outputs, the surfaces it reaches, and its undo path), the Testing section (cargo xtask ci, a …
Full details: Title check

Explanation

The title names the main change: a new map.convertPosition command in the engine that gives a place in every form RustGIS writes. It follows the feat(engine) convention and names the command and the scope. The title is specific and matches the changeset, which adds this command in the engine, the Assistant command list, tests, and docs.

Full details: Description check

Explanation

The description follows the repository template closely. It covers the Summary (what the command does, its outputs, the surfaces it reaches, and its undo path), the Testing section (cargo xtask ci, a new test and an existing test that passes unchanged), and a Related issue section that links Part of #1042 (piece 6). The UI evidence section states 'No visible UI change.', which matches the template's allowed option for changes without visible UI. The only minor gap is that the Related issue line uses 'Part of #1042' without a direct link to a separate issue, which the template allows. The description is detailed, specific, and matches the raw summary and objectives.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

A rabbit maps the morning light
From longitude to grids so neat
No camera shifts, no travels start
The numbers gather, clear and bright
Then carrots mark the journey’s end

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: fa303c80-e971-4361-8fb6-e4bed0cc1929
Commits

Reviewing files that changed from the base of the PR and between 0fe4615 and 9784702.

Files selected for processing: 3

  • crates/engine/src/cmd/navigate.rs
  • crates/engine/src/tests.rs
  • docs/user-guide/maps.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.

C::new("map.goToXY", "By Coordinates…", "Home › Navigate › Locate", go_to_xy).roles(&[]).effects(crate::policy::Effects::NONE)
.view()
.params(r#"{"lon" | "x": degrees (-74.006, or text such as 74°0′22″W), "lat" | "y": degrees (40.7128, or text such as 40°42′46″N), "position"?: text in place of lon and lat, as the search box reads it, latitude first (40.7128, -74.006; 18north 583959 4507351; 18TWL8395907350), "scale"?: number, "bearing"?: degrees clockwise from north, "pitch"?: degrees of tilt (0 to 85)}"#),
C::new("map.convertPosition", "Convert Position", "Home › Navigate › Locate", convert_position).roles(&[]).effects(crate::policy::Effects::NONE)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reach (AGENTS.md "Reach every surface"). map.goToXY has a dialog on the desktop (chrome.rs search_action, "map.goToXY" => Dialog("goToXY")). map.convertPosition has no entry there, so the desktop has no form to take its input and no place that shows its answer, since the returned JSON is only visible to scripts, Python and the Assistant. The PR description covers those surfaces but says nothing about the desktop ribbon and command search, the browser, the phone (ui-touch), MCP or plugins, or why each doesn't apply. Please either state that in the PR or show how the desktop reaches the result. Confidence: medium (about 55%). I did not verify how command search treats a command with required parameters that has no dialog route.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a Surfaces section to the description. Short version: CLI, Python, MCP, the Assistant, the web app and plugins all reach it as a command. On the desktop and phone there's no dialog on purpose, since the status-bar readout and the right-click menu already show and copy each form. It's read-only, so there's nothing to undo.

} else {
if let Some(u) = rustgis_geom::to_utm(c) {
out["grid"] = json!("utm");
out["utm"] = json!(u.to_string());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Possible inconsistency within one answer. The utm string comes from Utm's Display, which rounds easting and northing to whole meters (utm.rs:265, .round()). The mgrs field comes from to_mgrs, which floors them (utm.rs:404, .floor()). A point with easting 583959.7 therefore returns easting: 583959.7, utm: "18north 583960 …" and mgrs: "18T WL 83959 …" in the same object. The existing test point (New York) has a fractional part under 0.5, so it hides this. Confidence: low to medium (about 40%). The Display rounding predates this PR, but this command now puts both forms side by side. Either format utm from the floored values, or say in the doc that the two can differ by one meter. I did not check whether the coordinate readout relies on the rounded form.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, that's how the readouts behave too: the UTM text rounds to the meter as GeoConvert writes it, and MGRS truncates by definition. I kept both and said so in the user guide in 9784702, with easting and northing there for the exact place. That commit also makes every field come from the same rounded place, so they agree on the hemisphere right at the equator.

@github-actions

Copy link
Copy Markdown
Contributor

Code review

Bugs

  • The UTM string and the MGRS fields can disagree by one meter within the same answer. utm rounds easting and northing (utm.rs:265), while mgrs floors them (utm.rs:404). For example, easting 583959.7 gives utm: "18north 583960 …" and mgrs: "18T WL 83959 …". The existing test point hides this. Confidence: low to medium (~40%). Posted inline at navigate.rs:630.

Security

  • None found. The new command is read-only (Effects::NONE), its input goes through the existing bounds checks, and digits is range-checked and rejects non-integers, strings and out-of-range values.

Performance

  • None found. The work per call is constant.

Quality

  • The moving: bool flag in typed_place selects notice wording for the caller. Passing the wording in, or an enum, would be cleaner. Left for the release quality pass.
  • The comment at navigate.rs test lines 201–202 is a stray duplicate and reads oddly. Left for the release quality pass.
  • The doc comment on typed_place ("With it, what the reading assumed, for a notice") is hard to parse. Left for the release quality pass.

AGENTS.md

  • Reach every surface (medium, ~55%). The new command has no entry in chrome.rs search_action, unlike map.goToXY, which opens a dialog. The desktop therefore has no form for its input and no place that shows its result. The PR description covers scripts, Python and the Assistant, but does not say why the desktop ribbon and search, the browser, the phone (ui-touch), MCP and plugins don't apply. Posted inline at navigate.rs:46. I did not verify how command search treats required parameters on a command with no dialog route.
  • The COMMON list and the registry param string cover the Assistant's tool description. The cancel_* lists don't apply, since the command is instantaneous and read-only.
  • Layering, wasm and the unwrap/expect rule look clean in the changed code.

Already raised in earlier threads: none. prior-reviews.json has no threads, so none were skipped.

Checked: digits parsing and the ?-then-as u8 precedence; the -0.0 normalisation through + 0.0; nano rounding against the test's exact-equality assertions; to_utm/to_ups boundaries (UTM through 84° N, UPS north of that and south of 80° S, so grid is never null for a valid point on Earth); go_to_xy ordering after the refactor, which matches the old behaviour; the notify_text, notice_mark, notices_since, body() and is_earth() helpers; the Python run wrapper, which parses JSON, so the docs example ["utm"] is valid. I did not compile or run the tests.

Change size

Compared: the whole PR against main (merge base e65ee78 to PR head 0fe4615).

Measure Value
Files changed 4 (0 added, 4 modified, 0 removed, 0 renamed)
Size before 3.18 MB
Size after 3.19 MB
Total size change +11.3 KB
Path Before After Change
crates/engine/src/tests.rs 3.01 MB 3.02 MB +5.8 KB
crates/engine/src/cmd/navigate.rs 57.1 KB 61.8 KB +4.7 KB
docs/user-guide/maps.md 58.3 KB 60.4 KB +1.1 KB
crates/assistant/src/agent.rs 54.6 KB 54.6 KB +27 B

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

📖 Docs preview

Item Value
Preview https://preview.rustgis.app/pr-2312/
Web app https://preview.rustgis.app/pr-2312/app/
Commit 9784702

GitHub Pages takes a minute or two to publish a new commit.

…they agree at the equator

Every field is made from the rounded place, so a tiny negative latitude no longer gives lat 0 with a southern hemisphere, and easting and northing are truncated to the millimeter as MGRS truncates, so a northing just south of the equator stays short of 10,000,000 m. The note on another body names UPS too, and the user guide says the UTM text rounds to the meter while MGRS truncates.
@github-actions

Copy link
Copy Markdown
Contributor

Code review

No confirmed defects. I read the diff against the surrounding code, the UTM/UPS/MGRS helpers, and the existing goToXY tests. I could not compile or run the tests here (no shell), so the new test expectations are checked by reading only. The GeographicLib and PROJ reference values in the tests were not independently verified.

Bugs

  • Low confidence (about 30%): the utm string still rounds with Utm's Display, so a point just south of the equator reads 31south 500000 10000000. The new mm truncation covers only the easting/northing fields, although the comment at navigate.rs:608 says the equator-named northing is what it guards against. This is the same root cause as the existing unanswered thread on navigate.rs:633, so I did not post it again. The impact is cosmetic, about 0.3 mm.

Security

  • None. The command is read-only (Effects::NONE), touches no files, and validates its inputs: digits must be a whole number from 0 to 5, position must be text, and lon/lat go through the existing range checks. Non-finite values are rejected before the conversions.

Performance

  • None. It does one place conversion per call.

Quality

  • Nit (for the release quality pass): typed_place takes a moving: bool only to choose between two notice templates. A template argument or a small enum would read more clearly than a flag.

AGENTS.md

  • The "Reach every surface" concern about desktop, ribbon, command search, browser, phone, MCP and plugins is still unanswered, and the PR body does not address it. This is the existing thread on navigate.rs:46, so I did not post it again.
  • The notice rules are met: one notice per kind, and tests cover both the lossy and the clean case.
  • The new command adds no platform code, and it has no unwrap/expect in non-test code.
  • Background and Cancel rules do not apply, since the work is constant-time.
  • The schema and expression vocabulary are not touched.

Earlier concerns: 2 existing threads reviewed and left alone (desktop reach, still unanswered; utm/MGRS rounding, which the new maps.md text now discloses). I posted no inline comments, because nothing new met the bar for a line comment.

Change size

Compared with the base branch: the whole PR, merge base e65ee78 to head 9784702.

Measure Value
Files changed 4 (0 added, 4 modified, 0 removed, 0 renamed)
Size before 3.18 MB
Size after 3.19 MB
Total size change +13.1 KB
Path Before After Change
crates/engine/src/tests.rs 3.01 MB 3.02 MB +6.9 KB
crates/engine/src/cmd/navigate.rs 57.2 KB 62.1 KB +4.9 KB
docs/user-guide/maps.md 58.3 KB 59.6 KB +1.3 KB
crates/assistant/src/agent.rs 54.6 KB 54.6 KB +27 B

@deniial00
deniial00 added this pull request to the merge queue Nov 17, 2026
Merged via the queue into opengeos:main with commit c7e0575 Nov 17, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants