feat(gridfinder): VUCC 网格寻线实地导航 + LoTW 上传台址预填联动 + 移除地图入口

- GridGeometry 网格线/点几何 + QthConverter grid4/grid8;golden vectors 单测
- 独立定位流 ILocationRepo/LocationRepo(stop 时 removeUpdates),不自动写台址
- feature/gridfinder 模块:罗盘表盘、极坐标近距图、线上/点上精度门控(连续 3 次 ≤6.1m)
- 「设为 LoTW 上传台址」:跳证书配置页并预填当前网格(1/2/4 格),只改台站 grid 字段
- 地图页入口移除,设置页单入口;顶部间距改 ScreenColumn 结构(与设置页同构)
- 术语统一「最近网格点」(中英)
This commit is contained in:
atsunatsu committed 2026-09-29 12:12:47 +08:00
1 parent 33a7f23d7a
commit 4c3fdeaa9c
25 files changed
+2156 -9

No files matched your search

@@ -0,0 +1,65 @@
/*
* Look4Sat. Amateur radio satellite tracker and pass predictor.
* Copyright (C) 2019-2026 Arty Bishop and contributors.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
package com.rtbishop.look4sat.core.domain.repository
import kotlinx.coroutines.flow.StateFlow
/**
* A single position fix from the device's location provider, with the
* horizontal accuracy reported by the platform.
*/
data class LocationFix(
val latitude: Double,
val longitude: Double,
val altitudeMeters: Double = 0.0,
val accuracyMeters: Float,
val epochMs: Long
) {
/** ARRL VUCC work needs a fix good to the 20 ft (6.1 m) rule. */
fun isPreciseEnough(limitMeters: Float): Boolean = accuracyMeters in 0f..limitMeters
}
/** What the live-location source is currently able to give. */
sealed interface LocationState {
/** No fix yet - either permission is missing or the provider is warming up. */
data class Waiting(val permissionGranted: Boolean, val providerEnabled: Boolean) : LocationState
data class Fix(val location: LocationFix) : LocationState
}
/**
* Live device position for field tools (currently the Grid Finder). Kept
* separate from [ISettingsRepo.stationPosition] on purpose: collecting fixes
* here must never move the user's station, which is what drives every pass
* prediction in the app.
*
* Callers register with [startUpdates] while their screen is alive and MUST
* call [stopUpdates] when it goes away.
*/
interface ILocationRepo {
val state: StateFlow<LocationState>
/** Whether the app currently holds the fine-location permission. */
fun hasPermission(): Boolean
/** Begins delivering fixes; no-op when permission is missing. */
fun startUpdates()
/** Stops delivering fixes and releases the platform listener. */
fun stopUpdates()
}
@@ -38,8 +38,12 @@ interface IMainContainer {
val qsoRepository: IQsoRepository
val lotwUploadRepository: ILoTWUploadRepository
val radioTrackingService: IRadioTrackingService
val locationRepo: ILocationRepo
val mutualPassData: StateFlow<MutualPassData>
/** Grid Finder → LoTW station page prefill, consumed once by that page. */
val pendingLoTWStationGrid: StateFlow<String?>
fun setMutualPassData(data: MutualPassData)
fun setPendingLoTWStationGrid(grid: String?)
fun provideAddToCalendar(): IAddToCalendar
fun provideShowToast(): IShowToast
fun provideBluetoothReporter(): IReporter
@@ -0,0 +1,189 @@
/*
* Look4Sat. Amateur radio satellite tracker and pass predictor.
* Copyright (C) 2019-2026 Arty Bishop and contributors.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
package com.rtbishop.look4sat.core.domain.utility
import kotlin.math.abs
import kotlin.math.atan2
import kotlin.math.cos
import kotlin.math.hypot
import kotlin.math.round
/**
* Grid-line / grid-corner geometry for the 4-character Maidenhead squares that
* VUCC credits, used by the Grid Finder field tool.
*
* A 4-character square is 1 degree tall (boundaries at integer latitudes) and
* 2 degrees wide (boundaries at even offsets from the -180 degree antimeridian),
* so a station's distance to the nearest VUCC line and corner is a matter of
* simple planar geometry at the station's latitude.
*
* Geometry ported from OrbitDeck for iOS (MIT License, (c) 2026 Paul Stoetzer,
* N8HM) - `GridGeometry` in `Views/HomeView.swift` and `vuccGrids` in
* `Engine/FeatureEngine.swift`. Golden values are pinned by GridGeometryTest.
*/
/** ARRL VUCC "20 ft rule": a fix within this distance of a boundary counts as on it. */
const val VUCC_BOUNDARY_TOLERANCE_METERS = 20.0 * 0.3048
/** One degree of latitude in metres; 4-character squares are 1 degree tall. */
private const val METERS_PER_DEGREE_LATITUDE = 111_320.0
/** Nudge used to name the square on the far side of a boundary (display only). */
private const val NEIGHBOUR_NUDGE_DEGREES = 0.0005
/** Nudge used by [vuccClaimableGrids] so the neighbour lands squarely across. */
private const val CLAIM_NEIGHBOUR_NUDGE_DEGREES = 0.001
private const val DEG_TO_RAD = 0.017453292519943295
private const val RAD_TO_DEG = 57.29577951308232
/** Where the nearest 4-character boundary lies relative to the fix. */
enum class GridBoundaryDirection { NORTH, SOUTH, EAST, WEST }
/** ARRL VUCC standing of a fix, derived from how many squares it may claim. */
enum class GridFixStatus { INSIDE_GRID, ON_GRID_LINE, ON_GRID_CORNER }
/**
* Distance and bearing to the nearest 4-character grid corner and grid line,
* plus the locators of the squares that meet there. All distances are metres
* computed on a flat approximation local to the fix (the same approximation
* the source implementation uses; over the <=100 km distances involved the
* error is far below a GPS fix's own accuracy).
*/
data class GridGeometry(
val grid4: String,
val grid6: String,
val grid8: String,
val latLineMeters: Double,
val latLineDirection: GridBoundaryDirection,
val lonLineMeters: Double,
val lonLineDirection: GridBoundaryDirection,
val cornerMeters: Double,
val cornerBearingDegrees: Double,
val cornerGrids: List<String>,
val nearestLineMeters: Double,
val nearestLineBearingDegrees: Double,
val nearestLineIsLatitude: Boolean,
val nearestLineGrids: List<String>
)
/**
* The geometry of the VUCC (4-character) grid around a position, or null when
* the position is out of range.
*/
fun gridGeometry(latitude: Double, longitude: Double): GridGeometry? {
val grid4 = positionToGrid4(latitude, longitude) ?: return null
val grid6 = positionToQth(latitude, longitude) ?: return null
val grid8 = positionToGrid8(latitude, longitude) ?: return null
// 4-character boundaries: integer latitudes, even-degree longitudes.
val latBoundary = round(latitude)
val lonBoundary = round((longitude + 180.0) / 2.0) * 2.0 - 180.0
val metersPerDegreeLon = METERS_PER_DEGREE_LATITUDE * cos(latitude * DEG_TO_RAD)
val dNorth = (latBoundary - latitude) * METERS_PER_DEGREE_LATITUDE
val dEast = (lonBoundary - longitude) * metersPerDegreeLon
val otherLat = latBoundary - if (latitude >= latBoundary) NEIGHBOUR_NUDGE_DEGREES else -NEIGHBOUR_NUDGE_DEGREES
val otherLon = lonBoundary - if (longitude >= lonBoundary) NEIGHBOUR_NUDGE_DEGREES else -NEIGHBOUR_NUDGE_DEGREES
val cornerGrids = setOfNotNull(
positionToGrid4(latitude, longitude),
positionToGrid4(otherLat, longitude),
positionToGrid4(latitude, otherLon),
positionToGrid4(otherLat, otherLon)
).sorted()
val onLatitude = abs(dNorth) <= abs(dEast)
val nearestLineGrids = if (onLatitude) {
setOfNotNull(grid4, positionToGrid4(otherLat, longitude)).sorted()
} else {
setOfNotNull(grid4, positionToGrid4(latitude, otherLon)).sorted()
}
return GridGeometry(
grid4 = grid4,
grid6 = grid6,
grid8 = grid8,
latLineMeters = abs(dNorth),
latLineDirection = if (dNorth >= 0) GridBoundaryDirection.NORTH else GridBoundaryDirection.SOUTH,
lonLineMeters = abs(dEast),
lonLineDirection = if (dEast >= 0) GridBoundaryDirection.EAST else GridBoundaryDirection.WEST,
cornerMeters = hypot(dNorth, dEast),
cornerBearingDegrees = bearingDegrees(dNorth, dEast),
cornerGrids = cornerGrids,
nearestLineMeters = if (onLatitude) abs(dNorth) else abs(dEast),
nearestLineBearingDegrees = if (onLatitude) {
if (dNorth >= 0) 0.0 else 180.0
} else {
if (dEast >= 0) 90.0 else 270.0
},
nearestLineIsLatitude = onLatitude,
nearestLineGrids = nearestLineGrids
)
}
/**
* The 4-character squares a station at this position may claim under ARRL VUCC
* rules: normally one, but two when the fix is on the line between two squares
* and four when it is on the corner where four squares meet. A fix within
* [toleranceMeters] of a boundary is considered to be on it (the 20 ft rule).
*/
fun vuccClaimableGrids(
latitude: Double,
longitude: Double,
toleranceMeters: Double = VUCC_BOUNDARY_TOLERANCE_METERS
): List<String> {
val own = positionToGrid4(latitude, longitude) ?: return emptyList()
val grids = mutableSetOf(own)
val latBoundary = round(latitude)
val lonBoundary = round((longitude + 180.0) / 2.0) * 2.0 - 180.0
val metersPerDegreeLon = METERS_PER_DEGREE_LATITUDE * cos(latitude * DEG_TO_RAD)
val onLatitude = abs(latitude - latBoundary) * METERS_PER_DEGREE_LATITUDE <= toleranceMeters
val onLongitude = abs(longitude - lonBoundary) * metersPerDegreeLon <= toleranceMeters
if (!onLatitude && !onLongitude) return grids.sorted()
// Step just past the boundary so the neighbour's locator is unambiguous.
val otherLat = latBoundary - if (latitude >= latBoundary) CLAIM_NEIGHBOUR_NUDGE_DEGREES else -CLAIM_NEIGHBOUR_NUDGE_DEGREES
val otherLon = lonBoundary - if (longitude >= lonBoundary) CLAIM_NEIGHBOUR_NUDGE_DEGREES else -CLAIM_NEIGHBOUR_NUDGE_DEGREES
if (onLatitude) {
positionToGrid4(otherLat, longitude)?.let(grids::add)
}
if (onLongitude) {
positionToGrid4(latitude, otherLon)?.let(grids::add)
}
if (onLatitude && onLongitude) {
positionToGrid4(otherLat, otherLon)?.let(grids::add)
}
return grids.sorted()
}
/** VUCC standing implied by the number of squares a fix may claim. */
fun gridFixStatus(claimableGrids: List<String>): GridFixStatus = when {
claimableGrids.size >= 4 -> GridFixStatus.ON_GRID_CORNER
claimableGrids.size >= 2 -> GridFixStatus.ON_GRID_LINE
else -> GridFixStatus.INSIDE_GRID
}
private fun bearingDegrees(dNorth: Double, dEast: Double): Double {
val bearing = atan2(dEast, dNorth) * RAD_TO_DEG
return if (bearing < 0.0) bearing + 360.0 else bearing
}
@@ -69,6 +69,45 @@ fun positionToQth(latitude: Double, longitude: Double): String? {
return "$lonFirst$latFirst$lonSecond$latSecond$lonThird$latThird"
}
/**
* Convert a position to its 4-char Maidenhead locator (field + square), the
* square VUCC credits, upper-cased. Returns null outside the Maidenhead grid
* (lat >= 90 is out of range: the top row is 80..90 N). The longitude is
* wrapped into [-180, 180) first, so fixes either side of the antimeridian
* resolve to the square they are actually in.
*/
fun positionToGrid4(latitude: Double, longitude: Double): String? {
if (latitude < -90.0 || latitude >= 90.0) return null
val normalizedLon = normalizeLongitude(longitude)
val fieldLat = ((latitude + 90.0) / 10.0).toInt().coerceIn(0, 17)
val fieldLon = ((normalizedLon + 180.0) / 20.0).toInt().coerceIn(0, 17)
val subLat = ((latitude + 90.0) % 10.0).toInt()
val subLon = ((normalizedLon + 180.0) % 20.0 / 2.0).toInt()
return "${'A' + fieldLon}${'A' + fieldLat}$subLon$subLat"
}
/**
* Convert a position to its 8-char Maidenhead locator: the 6-char locator plus
* the numeric extended-square pair (the Maidenhead maximum). Returns null for
* out-of-range positions.
*/
fun positionToGrid8(latitude: Double, longitude: Double): String? {
val normalizedLon = normalizeLongitude(longitude)
val base = positionToQth(latitude, normalizedLon) ?: return null
val latitudeOffset = latitude.coerceIn(-90.0, 89.999999) + 90.0
val longitudeOffset = normalizedLon.coerceIn(-180.0, 179.999999) + 180.0
val subLon = 2.0 / 24.0
val subLat = 1.0 / 24.0
val lonDigit = minOf(9, ((longitudeOffset % subLon) / subLon * 10).toInt())
val latDigit = minOf(9, ((latitudeOffset % subLat) / subLat * 10).toInt())
return "$base$lonDigit$latDigit"
}
/** Wrap any longitude into [-180, 180). */
private fun normalizeLongitude(longitude: Double): Double {
return ((longitude + 180.0) % 360.0 + 360.0) % 360.0 - 180.0
}
private fun isValidPosition(lat: Double, lon: Double): Boolean {
return (lat >= -90.0 && lat <= 90.0) && (lon >= -180.0 && lon <= 360.0)
}
@@ -0,0 +1,171 @@
/*
* Look4Sat. Amateur radio satellite tracker and pass predictor.
* Copyright (C) 2019-2026 Arty Bishop and contributors.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
package com.rtbishop.look4sat.core.domain.utility
import org.junit.Assert.assertEquals
import org.junit.Assert.assertNull
import org.junit.Assert.assertTrue
import org.junit.Test
/**
* Golden values were produced by a line-by-line port of the reference
* implementation (OrbitDeck for iOS, MIT) covering four hemispheres/quadrant
* cases plus the two awkward longitudes: the Greenwich meridian and the
* antimeridian.
*/
class GridGeometryTest {
private val meterDelta = 0.5
private val bearingDelta = 0.05
@Test
fun `station at home square reports both boundaries and the corner`() {
val geometry = requireNotNull(gridGeometry(22.3542, 113.6250))
assertEquals("OL62", geometry.grid4)
assertEquals("OL62TI", geometry.grid6)
assertEquals("OL62TI55", geometry.grid8)
assertEquals(39429.5, geometry.latLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.SOUTH, geometry.latLineDirection)
assertEquals(38607.9, geometry.lonLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
assertEquals(55183.8, geometry.cornerMeters, meterDelta)
assertEquals(135.60, geometry.cornerBearingDegrees, bearingDelta)
assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), geometry.cornerGrids)
assertEquals(38607.9, geometry.nearestLineMeters, meterDelta)
assertEquals(90.0, geometry.nearestLineBearingDegrees, bearingDelta)
assertEquals(false, geometry.nearestLineIsLatitude)
assertEquals(listOf("OL62", "OL72"), geometry.nearestLineGrids)
}
@Test
fun `fix on the 114 east line sits on the boundary itself`() {
val geometry = requireNotNull(gridGeometry(22.3542, 114.0000))
assertEquals("OL72", geometry.grid4)
assertEquals("OL72AI", geometry.grid6)
assertEquals("OL72AI05", geometry.grid8)
assertEquals(39429.5, geometry.latLineMeters, meterDelta)
assertEquals(0.0, geometry.lonLineMeters, meterDelta)
assertEquals(39429.5, geometry.cornerMeters, meterDelta)
assertEquals(180.00, geometry.cornerBearingDegrees, bearingDelta)
assertEquals(listOf("OL62", "OL72"), geometry.nearestLineGrids)
}
@Test
fun `fix on the 22 north 114 east corner names all four squares`() {
val geometry = requireNotNull(gridGeometry(22.00002, 114.00003))
assertEquals("OL72", geometry.grid4)
assertEquals(2.2, geometry.latLineMeters, meterDelta)
assertEquals(3.1, geometry.lonLineMeters, meterDelta)
assertEquals(3.8, geometry.cornerMeters, meterDelta)
assertEquals(234.28, geometry.cornerBearingDegrees, bearingDelta)
assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), geometry.cornerGrids)
assertEquals("OL71", geometry.nearestLineGrids.first())
}
@Test
fun `greenwich meridian fix reports a zero distance latitude line to the north`() {
val geometry = requireNotNull(gridGeometry(45.0000, -0.0004))
assertEquals("IN95", geometry.grid4)
assertEquals("IN95XA", geometry.grid6)
assertEquals("IN95XA90", geometry.grid8)
assertEquals(0.0, geometry.latLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.NORTH, geometry.latLineDirection)
assertEquals(31.5, geometry.lonLineMeters, meterDelta)
assertEquals(listOf("IN94", "IN95", "JN04", "JN05"), geometry.cornerGrids)
assertEquals(true, geometry.nearestLineIsLatitude)
assertEquals(listOf("IN94", "IN95"), geometry.nearestLineGrids)
}
@Test
fun `antimeridian fix wraps into the eastern square`() {
val geometry = requireNotNull(gridGeometry(0.05, 179.9998))
assertEquals("RJ90", geometry.grid4)
assertEquals("RJ90XB", geometry.grid6)
assertEquals("RJ90XB92", geometry.grid8)
assertEquals(22.3, geometry.lonLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
assertEquals(179.77, geometry.cornerBearingDegrees, bearingDelta)
// The corner's four squares straddle the antimeridian, so the western
// pair rolls over to the A-series fields.
assertEquals(listOf("AI09", "AJ00", "RI99", "RJ90"), geometry.cornerGrids)
assertEquals(listOf("AJ00", "RJ90"), geometry.nearestLineGrids)
}
@Test
fun `southern hemisphere fix keeps its bearings right way round`() {
val geometry = requireNotNull(gridGeometry(-33.86, 151.21))
assertEquals("QF56", geometry.grid4)
assertEquals("QF56OD", geometry.grid6)
assertEquals(15584.8, geometry.latLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.SOUTH, geometry.latLineDirection)
assertEquals(73027.8, geometry.lonLineMeters, meterDelta)
assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
assertEquals(102.05, geometry.cornerBearingDegrees, bearingDelta)
assertEquals(180.0, geometry.nearestLineBearingDegrees, bearingDelta)
}
@Test
fun `out of range positions yield no geometry`() {
assertNull(gridGeometry(90.0, 0.0))
assertNull(gridGeometry(-91.0, 0.0))
}
@Test
fun `vucc claims one square when the fix is inside`() {
assertEquals(listOf("OL62"), vuccClaimableGrids(22.3542, 113.6250))
assertEquals(GridFixStatus.INSIDE_GRID, gridFixStatus(vuccClaimableGrids(22.3542, 113.6250)))
}
@Test
fun `vucc claims both squares on a line`() {
val claimed = vuccClaimableGrids(22.3542, 114.0000)
assertEquals(listOf("OL62", "OL72"), claimed)
assertEquals(GridFixStatus.ON_GRID_LINE, gridFixStatus(claimed))
}
@Test
fun `vucc claims all four squares on a corner`() {
val claimed = vuccClaimableGrids(22.00002, 114.00003)
assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), claimed)
assertEquals(GridFixStatus.ON_GRID_CORNER, gridFixStatus(claimed))
}
@Test
fun `vucc claims nothing extra just outside the 20 foot tolerance`() {
// Same corner, but ~38 m away: outside the 20 ft (6.096 m) rule.
val claimed = vuccClaimableGrids(22.0002, 114.0003)
assertEquals(listOf("OL72"), claimed)
assertEquals(GridFixStatus.INSIDE_GRID, gridFixStatus(claimed))
}
@Test
fun `vucc tolerance boundary is 20 feet`() {
assertEquals(6.096, VUCC_BOUNDARY_TOLERANCE_METERS, 0.0001)
// 5 m north of the 22 N line: inside the tolerance for a custom, tighter
// call, outside it when the caller demands sub-metre precision.
assertTrue(vuccClaimableGrids(22.00005, 113.62).size >= 2)
assertEquals(1, vuccClaimableGrids(22.00005, 113.62, toleranceMeters = 1.0).size)
}
@Test
fun `grid4 ignores longitudes beyond the antimeridian`() {
assertNull(positionToGrid4(91.0, 0.0))
// A longitude of 200 degrees is the same meridian as -160 degrees.
assertEquals(positionToGrid4(30.0, -160.0), positionToGrid4(30.0, 200.0))
}
}