Added linear transponder Doppler calculator (#232)

Co-authored-by: atsunatsu <atsunatsu@users.noreply.github.com>

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/DopplerFrequencyCalculator.kt

@@ -0,0 +1,122 @@
+/*
+ * 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.
+ */
+package com.rtbishop.look4sat.core.domain.utility
+
+import com.rtbishop.look4sat.core.domain.model.SatRadio
+import com.rtbishop.look4sat.core.domain.predict.OrbitalPos
+import java.util.Locale
+
+/**
+ * Computes Doppler-corrected reciprocal frequencies for linear transponders.
+ *
+ * For a linear (passband) transponder, uplink and downlink frequencies are
+ * related by a fixed passband offset. When the satellite moves, both are
+ * Doppler-shifted. Given one, this computes the other:
+ *
+ *   downlink → uplink: mapDownlinkToUplink (passband) → getUplinkFreq (Doppler)
+ *   uplink → downlink: mapUplinkToDownlink (passband) → getDownlinkFreq (Doppler)
+ */
+object DopplerFrequencyCalculator {
+
+    /**
+     * Given a downlink frequency, compute the Doppler-corrected uplink frequency.
+     * Returns null if the transponder is not a linear passband type.
+     */
+    fun computeUplinkFromDownlink(
+        downlinkHz: Long,
+        transponder: SatRadio,
+        orbitalPos: OrbitalPos
+    ): Long? {
+        if (!isLinearTransponder(transponder)) return null
+        val baseUplink = TransponderMapper.mapDownlinkToUplink(downlinkHz, transponder) ?: return null
+        return orbitalPos.getUplinkFreq(baseUplink)
+    }
+
+    /**
+     * Given a downlink frequency, compute the Doppler-corrected uplink frequency
+     * with an offset applied to the downlink (in Hz).
+     * Returns null if the transponder is not a linear passband type.
+     *
+     * The user-entered downlink frequency already includes the offset, so subtract
+     * it before mapping the downlink passband position back to the uplink.
+     */
+    fun computeUplinkFromDownlinkWithOffset(
+        downlinkHz: Long,
+        transponder: SatRadio,
+        orbitalPos: OrbitalPos,
+        offsetHz: Long
+    ): Long? {
+        if (!isLinearTransponder(transponder)) return null
+        val baseUplink = TransponderMapper.mapDownlinkToUplink(downlinkHz - offsetHz, transponder) ?: return null
+        return orbitalPos.getUplinkFreq(baseUplink)
+    }
+
+    /**
+     * Given an uplink frequency, compute the Doppler-corrected downlink frequency.
+     * Returns null if the transponder is not a linear passband type.
+     */
+    fun computeDownlinkFromUplink(
+        uplinkHz: Long,
+        transponder: SatRadio,
+        orbitalPos: OrbitalPos
+    ): Long? {
+        if (!isLinearTransponder(transponder)) return null
+        val baseDownlink = TransponderMapper.mapUplinkToDownlink(uplinkHz, transponder) ?: return null
+        return orbitalPos.getDownlinkFreq(baseDownlink)
+    }
+
+    /**
+     * Given an uplink frequency, compute the Doppler-corrected downlink frequency
+     * with an offset applied to the downlink (in Hz).
+     * Returns null if the transponder is not a linear passband type.
+     */
+    fun computeDownlinkFromUplinkWithOffset(
+        uplinkHz: Long,
+        transponder: SatRadio,
+        orbitalPos: OrbitalPos,
+        offsetHz: Long
+    ): Long? {
+        if (!isLinearTransponder(transponder)) return null
+        val baseDownlink = TransponderMapper.mapUplinkToDownlink(uplinkHz, transponder) ?: return null
+        return orbitalPos.getDownlinkFreq(baseDownlink + offsetHz)
+    }
+
+    /** True if this transponder supports linear passband mapping. */
+    fun isLinearTransponder(transponder: SatRadio): Boolean {
+        val upLow = transponder.uplinkLow
+        val upHigh = transponder.uplinkHigh
+        val downLow = transponder.downlinkLow
+        val downHigh = transponder.downlinkHigh
+        return upLow != null && upHigh != null && downLow != null && downHigh != null
+                && upLow != upHigh && downLow != downHigh
+    }
+
+    /**
+     * True for the radio entry that should drive the standalone Calculator page.
+     *
+     * A frequency range alone is not enough: some non-user-facing or drifting data entries
+     * can also have low/high frequencies. The calculator is meant for named linear
+     * transponders, e.g. "Linear Transponder", "Linear Transp.", "SSB Transponder".
+     */
+    fun isNamedLinearTransponder(transponder: SatRadio): Boolean {
+        if (!isLinearTransponder(transponder)) return false
+
+        val info = transponder.info.lowercase(Locale.ENGLISH)
+        val modes = listOfNotNull(transponder.downlinkMode, transponder.uplinkMode)
+            .joinToString(separator = " ")
+            .lowercase(Locale.ENGLISH)
+        val hasLinearName = info.contains("linear")
+        val hasTransponderName = info.contains("transponder") || info.contains("transp") ||
+                info.contains("xponder") || info.contains("xpdr")
+        val hasLinearMode = listOf("ssb", "usb", "lsb", "cw").any { modes.contains(it) }
+
+        return (hasLinearName && hasTransponderName) || (hasTransponderName && hasLinearMode)
+    }
+}

core/domain/src/test/java/com/rtbishop/look4sat/core/domain/DopplerFrequencyCalculatorTest.kt

@@ -0,0 +1,190 @@
+package com.rtbishop.look4sat.core.domain
+
+import com.rtbishop.look4sat.core.domain.model.SatRadio
+import com.rtbishop.look4sat.core.domain.predict.OrbitalPos
+import com.rtbishop.look4sat.core.domain.utility.DopplerFrequencyCalculator
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class DopplerFrequencyCalculatorTest {
+
+    private fun linearTransponder(
+        upLow: Long = 145_000_000L,
+        upHigh: Long = 145_500_000L,
+        downLow: Long = 435_000_000L,
+        downHigh: Long? = 435_500_000L,
+        inverted: Boolean = false,
+        info: String = "Linear Transponder",
+        downlinkMode: String? = "USB",
+        uplinkMode: String? = "LSB"
+    ) = SatRadio(
+        uuid = "linear", info = info, isAlive = true,
+        downlinkLow = downLow, downlinkHigh = downHigh,
+        downlinkMode = downlinkMode, uplinkLow = upLow, uplinkHigh = upHigh,
+        uplinkMode = uplinkMode, isInverted = inverted, catnum = 12345
+    )
+
+    private fun fmTransponder() = SatRadio(
+        uuid = "fm", info = "FM Repeater", isAlive = true,
+        downlinkLow = 435_600_000L, downlinkHigh = null,
+        downlinkMode = "FM", uplinkLow = 145_900_000L, uplinkHigh = null,
+        uplinkMode = "FM", isInverted = false, catnum = 99999
+    )
+
+    private fun pos(distanceRateKmS: Double = 0.0) = OrbitalPos().apply {
+        this.distanceRate = distanceRateKmS
+    }
+
+    @Test
+    fun isLinearTransponder_returnsTrueForLinear() {
+        assertTrue(DopplerFrequencyCalculator.isLinearTransponder(linearTransponder()))
+    }
+
+    @Test
+    fun isLinearTransponder_returnsFalseForFM() {
+        assertFalse(DopplerFrequencyCalculator.isLinearTransponder(fmTransponder()))
+    }
+
+    @Test
+    fun isLinearTransponder_returnsFalseForNullDownlinkHigh() {
+        val xpdr = linearTransponder(downHigh = null)
+        assertFalse(DopplerFrequencyCalculator.isLinearTransponder(xpdr))
+    }
+
+    @Test
+    fun isNamedLinearTransponder_returnsTrueForLinearTransponderName() {
+        assertTrue(DopplerFrequencyCalculator.isNamedLinearTransponder(linearTransponder()))
+    }
+
+    @Test
+    fun isNamedLinearTransponder_returnsTrueForSsbTransponderName() {
+        val xpdr = linearTransponder(info = "Mode V/U SSB Transponder", downlinkMode = "USB", uplinkMode = "LSB")
+        assertTrue(DopplerFrequencyCalculator.isNamedLinearTransponder(xpdr))
+    }
+
+    @Test
+    fun isNamedLinearTransponder_returnsFalseForRangeEntryWithoutTransponderName() {
+        val driftingRangeEntry = linearTransponder(info = "Upper side band (drifting)")
+        assertFalse(DopplerFrequencyCalculator.isNamedLinearTransponder(driftingRangeEntry))
+    }
+
+    @Test
+    fun isNamedLinearTransponder_returnsFalseForFmRepeater() {
+        assertFalse(DopplerFrequencyCalculator.isNamedLinearTransponder(fmTransponder()))
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_linear_noDoppler() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(0.0)
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlink(435_200_000L, xpdr, orbitalPos)
+        assertNotNull(uplink)
+        assertEquals(145_200_000L, uplink)
+    }
+
+    @Test
+    fun computeDownlinkFromUplink_linear_noDoppler() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(0.0)
+        val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(145_200_000L, xpdr, orbitalPos)
+        assertNotNull(downlink)
+        assertEquals(435_200_000L, downlink)
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_withDoppler_positiveRangeRate() {
+        // Satellite receding (positive range rate) → ground must transmit higher freq to compensate.
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(7.0)
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlink(435_200_000L, xpdr, orbitalPos)
+        assertNotNull(uplink)
+        assertTrue(uplink!! > 145_200_000L)
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_fmTransponder_returnsNull() {
+        val orbitalPos = pos()
+        val result = DopplerFrequencyCalculator.computeUplinkFromDownlink(435_600_000L, fmTransponder(), orbitalPos)
+        assertNull(result)
+    }
+
+    @Test
+    fun computeDownlinkFromUplink_fmTransponder_returnsNull() {
+        val orbitalPos = pos()
+        val result = DopplerFrequencyCalculator.computeDownlinkFromUplink(145_900_000L, fmTransponder(), orbitalPos)
+        assertNull(result)
+    }
+
+    @Test
+    fun computeDownlinkFromUplink_withPositiveOffset_addsOffsetToDownlink() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(0.0)
+        val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplinkWithOffset(
+            uplinkHz = 145_200_000L,
+            transponder = xpdr,
+            orbitalPos = orbitalPos,
+            offsetHz = 2_500L
+        )
+        assertEquals(435_202_500L, downlink)
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_withPositiveOffset_subtractsOffsetBeforeMapping() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(0.0)
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlinkWithOffset(
+            downlinkHz = 435_202_500L,
+            transponder = xpdr,
+            orbitalPos = orbitalPos,
+            offsetHz = 2_500L
+        )
+        assertEquals(145_200_000L, uplink)
+    }
+
+    @Test
+    fun computeOffsetRoundTrip_handlesNegativeOffset() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(0.0)
+        val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplinkWithOffset(
+            uplinkHz = 145_200_000L,
+            transponder = xpdr,
+            orbitalPos = orbitalPos,
+            offsetHz = -2_500L
+        )
+        assertEquals(435_197_500L, downlink)
+
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlinkWithOffset(
+            downlinkHz = downlink!!,
+            transponder = xpdr,
+            orbitalPos = orbitalPos,
+            offsetHz = -2_500L
+        )
+        assertEquals(145_200_000L, uplink)
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_invertedTransponder() {
+        val xpdr = linearTransponder(inverted = true, downHigh = 435_500_000L)
+        val orbitalPos = pos(0.0)
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlink(435_200_000L, xpdr, orbitalPos)
+        assertNotNull(uplink)
+        assertEquals(145_300_000L, uplink)
+    }
+
+    @Test
+    fun computeUplinkFromDownlink_roundTrip() {
+        val xpdr = linearTransponder()
+        val orbitalPos = pos(3.5)
+        val originalDownlink = 435_250_000L
+        val uplink = DopplerFrequencyCalculator.computeUplinkFromDownlink(originalDownlink, xpdr, orbitalPos)
+        assertNotNull(uplink)
+        val roundTripDownlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(uplink!!, xpdr, orbitalPos)
+        assertNotNull(roundTripDownlink)
+        val error = kotlin.math.abs(roundTripDownlink!! - originalDownlink)
+        assertTrue("Round-trip error too large: $error", error < 10000)
+    }
+}

core/presentation/src/main/res/values-zh/strings.xml

@@ -60,6 +60,9 @@
     <string name="radar_string_no">否</string>
     <string name="radar_string_yes">是</string>
     <string name="radar_visible">日照中</string>
+    <string name="radar_doppler_tx_hint">输入上行频率 (MHz)</string>
+    <string name="radar_doppler_rx_hint">输入下行频率 (MHz)</string>
+    <string name="radar_doppler_offset_hint">偏移 (kHz)</string>
 
     <!-- Map screen -->
     <string name="map_prev">上一个</string>

core/presentation/src/main/res/values/strings.xml

@@ -84,6 +84,9 @@
     <string name="radar_string_no">No</string>
     <string name="radar_string_yes">Yes</string>
     <string name="radar_visible">Visible</string>
+    <string name="radar_doppler_tx_hint">Enter TX freq (MHz)</string>
+    <string name="radar_doppler_rx_hint">Enter RX freq (MHz)</string>
+    <string name="radar_doppler_offset_hint">Offset (kHz)</string>
 
     <!-- Map screen -->
     <string name="map_prev">Prev</string>