DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

TYEclipse /

TYEclipse/dsh-geodesy

Verified

Geodesic math toolbox for DeepSeek Harness (dsh): great-circle distance, bearings, destination points, DMS parsing, rhumb lines, path intersections, spherical polygon areas, off-track distances, point-in-polygon, route totals, spherical caps and sphere-correct bounding boxes — zero runtime dependencies

★ 1 Stars0 Forks11 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@31e5ef49

dsh-geodesy

Geodesic math toolbox for DeepSeek Harness (dsh): great-circle distances, bearings, destination points, DMS parsing, rhumb lines, path intersections, spherical polygon areas, off-track (cross-track) distances, point-in-polygon tests, multi-leg route totals, spherical caps (coverage areas) and sphere-correct bounding boxes — all as local, deterministic tools with zero runtime dependencies.

中文简介:dsh 插件「大地测量工具箱」——大圆距离、方位角、目的地推算、DMS 坐标解析、恒向线(罗盘等角航线)距离、两条大圆路径交点、球面多边形面积、点到路径的偏航距离(cross-track)、点是否在球面多边形内、多段航线总里程与偏航/绕行量、球面圆(覆盖范围)、球面安全的包围盒,共十二个纯计算工具,零运行时依赖。专治大模型手算球面几何的常见错误(弧度与角度混用、经纬度顺序颠倒、忘记地球半径、把球面多边形当平面算、反算偏航距离时把「最近点」与「垂足」混为一谈、把球面覆盖范围当平面圆算、用航点最大最小值当航线包围盒等)。

Why

LLMs reliably fumble geodesic math: they mix up latitude/longitude order, use the wrong Earth radius, forget degrees→radians, botch DMS conversions, and treat spherical polygons as planar. This plugin moves that math out of the model's head and into exact spherical trigonometry:

  • geo_distance — great-circle distance (haversine) between two points, with initial/final bearings and the 16-wind compass direction; results in km, m, mi, or nmi
  • geo_bearing — initial & final great-circle bearings plus the great-circle midpoint of two points
  • geo_destination — the direct geodesic problem: given a start point, bearing and distance, compute the destination (with a round-trip distance check)
  • coord_parse — parse and validate coordinate strings (decimal, DMS, suffixes, pairs) and convert them to decimal degrees + formatted DMS
  • geo_rhumb — rhumb-line (constant-heading / loxodrome) distance and bearing between two points, with the great-circle distance for comparison
  • geo_intersection — where two great-circle paths (start point + initial bearing each) cross; reports the nearest crossing, the antipodal crossing, and distances from both starts
  • geo_area — area and perimeter of a spherical polygon via spherical excess (Girard's theorem), with the complementary region's area always included
  • geo_cross_track — how far a point is off a great-circle path: signed cross-track distance, along-track distance to the perpendicular foot, the foot's coordinates, whether the foot is between the path endpoints, and the distance to the nearest point of the segment
  • geo_point_in_polygon — is a coordinate inside a spherical polygon? Reports both sides of the boundary (the enclosed region and the region left of the directed edges), boundary hits, and the area of the region the point falls in
  • geo_path — totals a multi-leg route: each leg's length, heading (bearing + compass point) and running total, plus the route total, the straight-line distance between the endpoints, the detour and the distance back to the start
  • geo_circle — a spherical cap ("everything within r of a point"): its area and share of the sphere, its boundary circle's length, whether that boundary is a great circle, the latitude/longitude box it occupies (pole and antimeridian cases included), and whether a given point is inside it
  • geo_bbox — bounding box of coordinates or of a route: the box around the waypoints, or the box around the great-circle arcs between them (which reach latitudes no waypoint has), with a pole inside reported as all longitudes and a box that wraps the antimeridian returned as two boxes instead of a reversed min/max pair

All math uses the IUGG mean Earth radius 6371.0088 km (configurable via the plugin radiusKm option, e.g. for lunar or planetary calculations).

Install

dsh plugin --profile web add github:TYEclipse/dsh-geodesy

Requires pnpm on your PATH. Then restart the profile's services (or dsh restart web).

Usage

Ask the agent questions that involve Earth-surface math; it will call the tools automatically:

  • "What is the great-circle distance from Beijing to Shanghai?"
  • "Which direction is New York from London, and where is the midpoint?"
  • "I'm 200 km due east of Paris — where am I?"
  • "Parse 37°46′30″N, 122°25′8.4″W into decimal degrees."
  • "How far do I sail from (45°N, 0°) to (45°N, 90°) at a constant heading, and how much longer is that than the great circle?"
  • "Where does the flight corridor starting at (0, 0) heading due east cross the one starting at (0, 90) heading due north?"
  • "What is the area of the triangle (0,0), (0,90), (90,0) on the sphere?"
  • "I'm steaming from (0,0) to (0,10) — how far off track am I at (1,5), and where do I rejoin?"
  • "Is (45, 45) inside the spherical triangle (0,0), (0,90), (90,0)?"
  • "This 0.2° box sits at the antimeridian — is (0, 0) inside it?" (the antipode trap: a naive angle-sum test says yes, it is not)
  • "How long is the route London → Paris → Rome, and how much longer is it than flying straight there?"
  • "Everything within 300 km of Beijing — what area is that, and where does its edge run?"
  • "What bounding box should I query for the route Beijing → Shanghai → Hong Kong?" (and: "does that route ever go above 45°N?" — the arcs answer differently from the waypoints)
  • "This Pacific route runs from 170°E to 170°W — give me the boxes a map query needs."

Examples

geo_rhumb — (45°N, 0°) → (45°N, 90°) at constant heading:

{
  "valid": true,
  "unit": "km",
  "distance": 7076.411574,
  "kilometers": 7076.411574,
  "miles": 4397.078297,
  "nauticalMiles": 3820.956573,
  "bearing": 90,
  "compass": "E",
  "greatCircleKm": 6671.704814
}

geo_intersection — equator (east from (0,0)) × meridian (north from (0,90)):

{
  "valid": true,
  "lat": 0,
  "lon": 90,
  "distanceFromStart1Km": 10007.557221,
  "distanceFromStart2Km": 0,
  "antipodeLat": 0,
  "antipodeLon": -90,
  "antipodeDistanceFromStart1Km": 10007.557221,
  "antipodeDistanceFromStart2Km": 20015.114442
}

geo_area — the octant triangle (0,0), (0,90), (90,0): exactly one eighth of the sphere:

{
  "valid": true,
  "vertices": 3,
  "areaKm2": 63758235.121609,
  "perimeterKm": 30022.671663,
  "excessRadians": 1.5707963268,
  "complementKm2": 446307645.851263
}

geo_cross_track — the query point (1, 5) against the equator path (0,0) → (0,10):

{
  "valid": true,
  "side": "left",
  "crossTrackKm": 111.19508,
  "distanceToPathKm": 111.19508,
  "alongTrackKm": 555.975401,
  "footLat": 0,
  "footLon": 5,
  "withinSegment": true,
  "distanceToSegmentKm": 111.19508,
  "pathLengthKm": 1111.950802,
  "trackBearing": 90,
  "bearingToFoot": 180
}

geo_point_in_polygon — (45, 45) against the octant triangle (0,0), (0,90), (90,0):

{
  "valid": true,
  "insideEnclosed": true,
  "insideLeftRegion": true,
  "onBoundary": false,
  "vertices": 3,
  "areaKm2": 63758235.121609,
  "complementKm2": 446307645.851263,
  "regionAreaKm2": 63758235.121609
}

geo_path — London (51.5074, -0.1278) → Paris (48.8566, 2.3522) → Rome (41.9028, 12.4964): the route is 15 km longer than the direct line, a detour of about 1%:

{
  "valid": true,
  "points": 3,
  "legs": [
    { "leg": 1, "fromIndex": 0, "toIndex": 1, "distanceKm": 343.556535, "cumulativeKm": 343.556535, "initialBearing": 148.115617, "compass": "SSE" },
    { "leg": 2, "fromIndex": 1, "toIndex": 2, "distanceKm": 1105.281675, "cumulativeKm": 1448.83821, "initialBearing": 130.58791, "compass": "SE" }
  ],
  "totalKm": 1448.83821,
  "straightKm": 1433.783288,
  "detourKm": 15.054922,
  "detourPercent": 1.05,
  "closureKm": 1433.783288,
  "closesLoop": false,
  "maxLegKm": 1105.281675,
  "minLegKm": 343.556535,
  "zeroLengthLegs": []
}

geo_circle — everything within 300 km of Beijing (39.9042, 116.4074), asking whether (40.5, 117) is inside. The cap is 0.055% of the Earth's surface, its boundary circle is 1884 km long, and the box it occupies spans 5.4° of latitude and 7.0° of longitude:

{
  "valid": true,
  "angularRadiusDeg": 2.697961,
  "areaKm2": 282691.098586,
  "surfaceFraction": 0.0005542247,
  "boundaryKm": 1884.259081,
  "boundaryIsGreatCircle": false,
  "minLat": 37.206239,
  "maxLat": 42.602161,
  "minLon": 112.889481,
  "maxLon": 119.925319,
  "lonSpanDeg": 7.035838,
  "crossesAntimeridian": false,
  "coversAllLongitudes": false,
  "includesNorthPole": false,
  "includesSouthPole": false,
  "coversWholeSphere": false,
  "pointDistanceKm": 83.198018,
  "containsPoint": true,
  "pointOnBoundary": false
}

geo_bbox — the same two coordinates read as a route (40°N at 0° and 40°N at 120°). The waypoints never leave 40°N, but the great-circle arc between them climbs to 59.2°N, so the route box is 19.2° taller than the waypoints and the arcs reach 2136 km beyond them:

{
  "valid": true,
  "shape": "path",
  "boxes": [
    {
      "minLat": 40,
      "maxLat": 59.210267,
      "minLon": 0,
      "maxLon": 120
    }
  ],
  "minLat": 40,
  "maxLat": 59.210267,
  "lonSpanDeg": 120,
  "crossesAntimeridian": false,
  "coversAllLongitudes": false,
  "includesNorthPole": false,
  "includesSouthPole": false,
  "vertices": 2,
  "legs": 1,
  "bulgeKm": 2136.087177
}

Pass the same coordinates as points instead of path and the box is 40°–40°: the two answers are different on purpose, because "the box of these coordinates" and "the box a map needs for this route" are different questions.

geo_distance — Beijing (39.9042, 116.4074) → Shanghai (31.2304, 121.4737):

{
  "valid": true,
  "unit": "km",
  "distance": 1067.311645,
  "kilometers": 1067.311645,
  "miles": 663.196709,
  "nauticalMiles": 576.302184,
  "initialBearing": 153.072675,
  "finalBearing": 156.029266,
  "compass": "SSE"
}

Semantics notes

  • geo_area winding: the reported area is the region to the LEFT of the directed edges. Counter-clockwise vertex order (seen from outside the sphere) yields the polygon itself; clockwise order yields its complement. complementKm2 is always included, so either region is one field away. The polygon must be simple (non-self-intersecting); at most 100 vertices.
  • geo_point_in_polygon reports both sides of the boundary, because a boundary on a sphere always has two:
    • insideEnclosed — the ordinary "is the point inside the polygon". The enclosed region is taken to be the smaller of the two regions the boundary splits the sphere into, so a clockwise-wound square still means its interior.
    • insideLeftRegion — the region to the LEFT of the directed edges, i.e. exactly the region geo_area calls areaKm2. With counter-clockwise vertex order the two answers agree; with clockwise order they are opposites (a note says so).
    • Points within ~6 mm of an edge (floating-point tolerance) are onBoundary: true and in neither region. The method is a signed great-circle ray-crossing winding, which — unlike the popular "sum the angles at the query point" shortcut — does not report points near a polygon's antipode as inside.
  • geo_cross_track sign conventions: crossTrackKm is positive when the query point is to the LEFT of the direction of travel (right-hand rule, seen from outside the sphere); alongTrackKm is positive when the perpendicular foot lies ahead of the path start and negative when it lies behind. When the foot falls outside the segment, withinSegment: false and distanceToSegmentKm is the distance to the nearer endpoint — not the perpendicular distance (a note says so). A point exactly 90° off the path has no unique foot and is reported as an error.
  • geo_path: the legs are great-circle arcs, so the route total is the sum of the leg lengths and the detour (detourKm = total − straight line) is never negative — it is zero only when every waypoint lies on the single great circle through the endpoints. detourKm is the difference of the two reported totals (each rounded to 6 decimals), so it can be checked by hand against them. A leg joining two identical waypoints is reported as 0 km with no initialBearing/compass (a zero-length great circle has no heading — inventing 0° would be a silent wrong answer) and its leg number is listed in zeroLengthLegs. When the last waypoint equals the first, closesLoop is true, the straight-line distance is 0 and no detourPercent is reported.
  • geo_circle describes a spherical cap, not a flat disc:
    • areaKm2 is the exact cap area 2πR²(1 − cos d) and surfaceFraction its share of the whole sphere; the planar approximation πr² only holds for tiny caps (at r = 1000 km it overshoots the true area by 0.21%).
    • The latitude box is centre ± d; boundaryIsGreatCircle is true only when the radius is exactly a quarter of the circumference (d = 90°), where the cap is a hemisphere.
    • A cap that reaches a pole contains it: includesNorthPole/includesSouthPole are set, coversAllLongitudes is true, and minLon/maxLon are reported as the full range (the cap is not a rectangle). A cap that straddles the antimeridian has a box that wraps: crossesAntimeridian is true and minLon is east of maxLon (join them through ±180°); lonSpanDeg always holds the true angular width.
    • A radius of half the circumference or more covers the whole sphere (coversWholeSphere, area = 4πR², boundaryKm = 0).
    • containsPoint/pointOnBoundary are decided by great-circle distance, never by the box — a box test would misjudge points near the box corners. "On the boundary" means within ~6 mm of the circle; a point placed there counts as neither inside nor outside. Note that tool coordinates are rounded to 1e-6 degrees (~11 cm of arc), which is coarser than that tolerance, so do not expect a rounded coordinate to be recognized as exactly on the edge.
  • geo_bbox is a box on a sphere, which is where naive code goes wrong in three ways:
    • A route box is not a waypoint box. shape: "path" includes the great-circle arcs, so the latitude range can exceed every waypoint's: 40°N at 0° → 40°N at 120° peaks at 59.2°N, and bulgeKm is how far the arcs reach beyond the waypoint extremes (0 when the waypoints already are the extremes). Pass points (vertices only) only when that is really the question — the note says so.
    • A pole inside the box means every longitude. coversAllLongitudes is then true and boxes[0] is the full range; a route that runs over a pole (80°N 0° → 80°N 180°) is the standard example, and its maxLat is exactly 90.
    • A box that wraps ±180° needs two boxes. boxes holds two entries (crossesAntimeridian: true), each with minLon < maxLon, so 170°E → 170°W is [170, 180] plus [-180, -170] — 20° wide, not a reversed pair that reads as 340° or as a broken range. lonSpanDeg is always the true angular width.
    • The minimal longitude interval is the one you get by cutting the longitude circle at its largest gap, so a scattered point set does not get a 300°-wide box just because two points happen to be near ±180°.
    • A point set is a set: order does not matter. A route's legs are the arcs between consecutive waypoints, so order does. A zero-length leg is ignored; an antipodal leg is an error (its great circle is not unique), not a guess.
  • geo_intersection reports the crossing nearest to the first path's start; when that crossing lies on the reverse side of path 1 (bearing from start 1 differs by ~180°), a note says so and the antipodal crossing is the one ahead.
  • geo_rhumb returns bearing 0 for zero-length lines (no unique heading exists).

Coordinate input formats

coord_parse accepts, deterministically:

Input Meaning
39.9042, 116.4074 decimal pair, lat, lon order
116.4074E, 39.9042N pair with suffixes — order is irrelevant, axes come from suffixes
39°54′15″N 116°23′27″E DMS pair (comma optional when suffixed)
37°46′30″N / 37d46m30sN / 37:46:30N / 37 46 30 N single DMS coordinate
37.775N / -122.419 single decimal (negative = S/W)
37.775, kind: "lat" unsuffixed single value with an explicit axis hint

Invalid input returns valid: false with a reason — never a silent guess.

Tools

Tool Purpose
geo_distance haversine distance, km/m/mi/nmi, initial & final bearing, compass point
geo_bearing initial/final bearings + great-circle midpoint
geo_destination destination point from start + bearing + distance, with round-trip check
coord_parse parse/validate decimal & DMS coordinate strings → decimal degrees + DMS
geo_rhumb constant-heading distance + bearing (loxodrome), great-circle comparison
geo_intersection crossing of two great-circle paths (+ antipodal crossing, distances from starts)
geo_area spherical polygon area + perimeter (spherical excess), complement area
geo_cross_track off-track distance to a great-circle path: signed cross-track + along-track, foot, segment distance
geo_point_in_polygon inside/outside test for a spherical polygon (both sides, boundary hits, region area)
geo_path multi-leg route totals: per-leg distance/heading/running total, detour vs the straight line
geo_circle spherical cap: area, boundary circle length, lat/lon box (poles & antimeridian), containment
geo_bbox bounding box of points or of a route (arcs included), pole and antimeridian cases as two boxes

Configuration

plugins:
  dsh-geodesy:
    radiusKm: 6371.0088   # sphere radius; use 1737.4 for the Moon, 3389.5 for Mars

Development

pnpm install
pnpm build
pnpm test     # 243 tests, anchored to independently computed closed-form values (test/oracle/anchors.py)
pnpm lint

License

MIT © TYEclipse

—/ 5

No ratings yet

Verified DSH bundle

Commit 31e5ef49c6bf

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout