precise

Package precise

Package precise provides types and utilities for handling precise GNSS orbit and clock products from various sources (SP3, RINEX CLK, RTCM SSR, etc.).

Core Types

OrbitRecord

Generic representation of a satellite's position (and optionally velocity) at a specific time. This is the common format used across all precise product types.

type OrbitRecord struct {
    Time     time.Time
    System   gnss.System
    SvID     int
    Position coordinates.Vector3D  // ECEF position in meters
    Clock    float64                // Satellite clock bias in seconds
    Velocity *coordinates.Vector3D  // ECEF velocity in m/s (optional)
}

ClockRecord

Represents precise clock data from RINEX CLK files or other sources.

type ClockRecord struct {
    Time      time.Time
    DataType  ClockDataType  // AS, AR, etc.
    Name      string         // Station or satellite ID
    System    int
    SvID      int
    Bias      float64        // Clock bias in seconds
    BiasSig   float64        // Sigma
    Rate      float64        // Clock rate
    // ... additional fields
}

SP3Record (New in refactor-precise branch)

Enhanced representation specifically for SP3 precise orbit products. Combines position and velocity data with product metadata.

type SP3Record struct {
    Time   time.Time
    System gnss.System
    SvID   int

    // Position (always present)
    Position coordinates.Vector3D  // ECEF, kilometers (SP3 native)
    Clock    float64                // Microseconds
    PosSigma coordinates.Vector3D
    ClkSigma int

    // Velocity (optional, nil if not available)
    Velocity     *coordinates.Vector3D  // dm/s
    ClockRate    *float64
    VelSigma     *coordinates.Vector3D
    ClockRateSigma *int

    // Event/prediction flags
    ClockEventFlag    string
    ClockPredictFlag  string
    OrbitManeuverFlag string
    OrbitPredictFlag  string

    // Product metadata
    ProductMeta *SP3ProductMetadata
}

Key Features:

• Preserves SP3 native units for efficient storage
• Nullable velocity fields for products that don't include them
• Embedded product metadata (analysis center, type, reference frame, etc.)
• Conversion to OrbitRecord with automatic unit conversion

SP3ProductMetadata (New in refactor-precise branch)

Describes the characteristics of an SP3 product source.

type SP3ProductMetadata struct {
    AnalysisCenter   string  // "IGS", "COD", "GRG", "ESA", etc.
    ProductType      string  // "final", "rapid", "ultra-rapid", "predicted"
    ReferenceFrame   string  // "IGS20", "IGS14", "ITRF2020", etc.
    ReferencePoint   string  // "APC" or "CoM"
    Campaign         string  // "operational", "repro3", etc.
    OrbitType        string  // "FIT", "HLM", "BCT", etc.
    GPSWeek          int
    SamplingInterval int     // seconds
}

Use Cases:

• Filter orbits by analysis center (compare CODE vs IGS)
• Select product type (final vs rapid vs ultra-rapid)
• Ensure consistent reference frame across datasets
• Track reprocessing campaigns for time series analysis

Unit Conventions

Different precise product formats use different units. This package provides explicit handling:

Use the provided conversion methods:

• SP3Record.ToOrbitRecord() - Converts SP3 native units to SI units
• ClockRecords.LinearInterpolateClockBias() - Returns bias in seconds

Collections and Filtering

All record types provide collection types with helper methods:

OrbitRecords

records := precise.OrbitRecords{...}

// Filter by satellite
gps08 := records.FilterBySatellite(gnss.GPS, 8)

// Get time range
start, end := records.GetTimeRange()

SP3Records

sp3Recs := precise.SP3Records{...}

// Filter by satellite and time
filtered := sp3Recs.
    FilterBySatellite(gnss.GPS, 8).
    FilterByTimeRange(start, end)

// Filter by product characteristics
igsFinal := sp3Recs.FilterByProduct("IGS", "final")
codeFinal := sp3Recs.FilterByProduct("COD", "final")

// Get only records with velocity data
withVel := sp3Recs.WithVelocity()

// Convert all to OrbitRecords
orbitRecs := sp3Recs.ToOrbitRecords()

ClockRecords

clocks := precise.ClockRecords{...}

// Filter by satellite
gps08Clocks := clocks.FilterBySatellite(gnss.GPS, 8)

// Interpolate clock bias at specific time
bias, err := precise.LinearInterpolateClockBias(gps08Clocks, targetTime)

// Find nearest clock value
bias, found := precise.GetNearestClock(gps08Clocks, targetTime, tolerance)

Usage Example

package main

import (
    "fmt"
    "time"

    "gitlab.com/earthscope/gnsstools/pkg/common/gnss"
    "gitlab.com/earthscope/gnsstools/pkg/common/gnss/precise"
    "gitlab.com/earthscope/gnsstools/pkg/encoding/sp3"
)

func main() {
    // Load and parse SP3 file
    file, _ := os.Open("COD0OPSFIN_20240010000_01D_05M_ORB.SP3")
    sp3Data, _ := sp3.NewSP3(file)
    _ = sp3Data.Read()

    // Extract product metadata and convert
    productMeta, _ := sp3.ParseProductFromFilename("COD0OPSFIN_20240010000_01D_05M_ORB.SP3")
    sp3Records := sp3Data.ConvertToSP3RecordsWithMetadata(productMeta)

    // Filter for GPS satellite 8
    gps08 := precise.SP3Records(sp3Records).
        FilterBySatellite(gnss.GPS, 8)

    // Convert to standard OrbitRecords (meters, seconds)
    orbitRecs := gps08.ToOrbitRecords()

    // Use in processing
    for _, orb := range orbitRecs {
        fmt.Printf("GPS 08 @ %s: pos=(%.3f, %.3f, %.3f) m\n",
            orb.Time.Format(time.RFC3339),
            orb.Position[0], orb.Position[1], orb.Position[2])

        if orb.Velocity != nil {
            fmt.Printf("  vel=(%.3f, %.3f, %.3f) m/s\n",
                orb.Velocity[0], orb.Velocity[1], orb.Velocity[2])
        }
    }
}

See Also

• pkg/encoding/sp3 - SP3 file parser with P+V record merging
• pkg/encoding/sp3/REFACTOR_NOTES.md - Detailed SP3 refactor documentation
• pkg/position/ppp-ar - PPP with ambiguity resolution using precise products