### Clean Build and Run Example

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Use this command to perform a clean build and then run the default example.

```bash
mvn clean compile exec:java
```

--------------------------------

### Basic Satellite Tracking with predict4java

Source: https://github.com/g4dpz/predict4java/blob/master/README.md

This example demonstrates how to load TLE data, create a satellite object, define a ground station, and get the satellite's current position. Ensure you have the predict4java library added as a dependency.

```java
import uk.me.g4dpz.satellite.*;

// Load TLE data
String[] tle = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26045.79523799  .00007779  00000+0  15107-3 0  9994",
    "2 25544  51.6315 185.5279 0011056  98.8248 261.3993 15.48601910552787"
};

// Create satellite
TLE tleData = new TLE(tle);
Satellite satellite = SatelliteFactory.createSatellite(tleData);

// Define ground station
GroundStationPosition groundStation = new GroundStationPosition(
    52.4670,  // Latitude (degrees, North positive)
    -2.022,   // Longitude (degrees, East positive)
    200.0     // Altitude (meters above sea level)
);

// Get current position
Date now = new Date();
SatPos position = satellite.getPosition(groundStation, now);

System.out.println("Azimuth: " + Math.toDegrees(position.getAzimuth()));
System.out.println("Elevation: " + Math.toDegrees(position.getElevation()));
System.out.println("Range: " + position.getRange() + " km");
```

--------------------------------

### Compile and Run BasicSatelliteTracking Example

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Navigate to the examples directory and run this command to compile and execute the BasicSatelliteTracking example.

```bash
# Navigate to examples directory
cd examples

# Compile and run BasicSatelliteTracking (default)
mvn compile exec:java
```

--------------------------------

### Compile and Run PassPrediction Example

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Modify the mainClass in pom.xml to PassPrediction and then run this command to compile and execute the example.

```bash
mvn compile exec:java
```

--------------------------------

### Building predict4java from Source

Source: https://github.com/g4dpz/predict4java/blob/master/README.md

This command initiates the build process for the predict4java library using Maven. Ensure you have Maven 3.x installed.

```bash
mvn clean install
```

--------------------------------

### Repository Directory Structure

Source: https://github.com/g4dpz/predict4java/blob/master/PROJECT_STATUS.md

Visual representation of the project's file organization, separating Java source code, examples, and the C++ port.

```text
predict4java/
├── src/                          # Java source code
│   ├── main/java/               # Library implementation
│   └── test/java/               # 149 comprehensive tests
├── examples/                     # Java examples
│   ├── BasicSatelliteTracking.java
│   ├── PassPrediction.java
│   ├── DopplerShiftCalculation.java
│   └── MultiSatelliteTracking.java
├── predict4cpp/                  # C++ port
│   ├── include/                 # Public headers
│   ├── src/                     # Implementation
│   ├── examples/                # C++ examples
│   ├── benchmarks/              # Performance tests
│   ├── QUICKSTART.md           # Getting started guide
│   ├── PORTING_NOTES.md        # Porting documentation
│   └── COMPARISON.md           # Java vs C++ comparison
├── config/                       # Code quality configs
│   ├── checkstyle/
│   └── spotbugs/
├── .github/workflows/           # CI/CD pipelines
├── pom.xml                      # Maven build (development)
├── pom-release.xml              # Maven build (release)
└── README.md                    # Main documentation
```

--------------------------------

### Predicting Next Satellite Pass with predict4java

Source: https://github.com/g4dpz/predict4java/blob/master/README.md

This example shows how to predict the next satellite pass over a ground station using the PassPredictor class. It requires TLE data and ground station information.

```java
PassPredictor predictor = new PassPredictor(tleData, groundStation);
SatPassTime nextPass = predictor.nextSatPass(new Date());

System.out.println("AOS: " + nextPass.getStartTime());
System.out.println("Max Elevation: " + nextPass.getMaxEl() + "°");
System.out.println("LOS: " + nextPass.getEndTime());
```

--------------------------------

### Get Satellite Positions Over Time Range

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Calculates satellite positions for a given time range with a specified increment. Requires a Predictor instance.

```java
List<SatPos> positions = predictor.getPositions(
    referenceDate,      // The reference time
    incrementSeconds,   // Time step between calculations (seconds)
    minutesBefore,      // Minutes before reference time
    minutesAfter        // Minutes after reference time
);
```

--------------------------------

### Get Single Satellite Position at Current Time

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Calculates a single satellite position at the current time by requesting positions over a short duration with a 60-second increment.

```java
Date now = new Date();
List<SatPos> positions = predictor.getPositions(now, 60, 0, 1);
SatPos position = positions.get(0);  // First position in the list
```

--------------------------------

### Build Project Locally

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Commands for packaging the project, including options for skipping tests, running full verification, or performing a release build.

```bash
# Build without tests
mvn clean package -DskipTests

# Build with all checks
mvn clean verify

# Build release artifacts (requires GPG)
mvn clean package -P release
```

--------------------------------

### Display Project File Structure

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Visual representation of the CI/CD configuration files within the repository.

```text
.github/
├── dependabot.yml                 # Dependency update config
└── workflows/
    ├── README.md                  # Workflow documentation
    ├── codeql-analysis.yml        # Security scanning (existing)
    └── maven-ci.yml               # Main CI/CD pipeline (NEW)

CI_CD_GUIDE.md                     # Comprehensive CI/CD guide (NEW)
CI_CD_SETUP.md                     # Quick setup guide (NEW)
CI_CD_IMPLEMENTATION_SUMMARY.md    # This file (NEW)
CHANGELOG.md                       # Updated with CI/CD changes
README.md                          # Updated with badges
```

--------------------------------

### Create Satellite Instances

Source: https://context7.com/g4dpz/predict4java/llms.txt

Uses the SatelliteFactory to instantiate the correct propagation model based on orbital period.

```java
import uk.me.g4dpz.satellite.SatelliteFactory;
import uk.me.g4dpz.satellite.Satellite;
import uk.me.g4dpz.satellite.TLE;

// Create TLE data
String[] isstle = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(isstle);

// Create satellite instance (automatically selects SGP4 or SDP4)
Satellite satellite = SatelliteFactory.createSatellite(tle);

// Verify satellite type
System.out.println("Satellite: " + satellite.getTLE().getName());
System.out.println("Uses Deep Space model: " + satellite.getTLE().isDeepspace());
```

--------------------------------

### Verify CI/CD Configuration Files

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Command to confirm the existence of essential CI/CD configuration files.

```bash
ls -la .github/workflows/maven-ci.yml
ls -la .github/dependabot.yml
ls -la CI_CD_GUIDE.md
ls -la CI_CD_SETUP.md
```

--------------------------------

### Execute Maven lifecycle commands

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Standard Maven commands for testing, quality verification, building, and reporting.

```bash
mvn clean test
```

```bash
mvn checkstyle:check && mvn compile spotbugs:check
```

```bash
mvn clean package
```

```bash
mvn jacoco:report && open target/site/jacoco/index.html
```

--------------------------------

### Run local environment tests

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Use these commands to align the local Java environment with CI and execute the test suite.

```bash
# Test with same Java version as CI
sdk use java 11.0.x-tem
mvn clean test

# Check for hardcoded paths or assumptions
```

--------------------------------

### Build Maven Package

Source: https://github.com/g4dpz/predict4java/blob/master/OPTIMIZATIONS.md

Package the project using Maven after applying optimizations. This command builds the project and creates distributable artifacts.

```bash
mvn clean package
```

--------------------------------

### Deploy Java Library to Maven Central

Source: https://github.com/g4dpz/predict4java/blob/master/PROJECT_STATUS.md

Use this command to trigger the release deployment process using the specified release POM file.

```bash
mvn clean deploy -f pom-release.xml
```

--------------------------------

### Run Quality Checks Locally

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Commands to execute static analysis tools and generate project site reports.

```bash
# Checkstyle
mvn checkstyle:check

# SpotBugs
mvn compile spotbugs:check

# All quality reports
mvn site
```

--------------------------------

### Run Maven Tests

Source: https://github.com/g4dpz/predict4java/blob/master/OPTIMIZATIONS.md

Execute the project's test suite using Maven to verify optimizations. Ensure all tests pass to confirm the integrity of the changes.

```bash
mvn clean test
```

--------------------------------

### Run Local Tests

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Command to execute tests locally to match the CI environment.

```bash
# Test locally with CI Java version
mvn clean test
```

--------------------------------

### Verify Workflow Files

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Command to list the GitHub Actions workflow files in the repository.

```bash
ls -la .github/workflows/
```

--------------------------------

### Run Tests Locally

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Commands for executing the full test suite, specific tests, or tests with coverage reporting.

```bash
# Run all tests
mvn clean test

# Run specific test
mvn test -Dtest=PassPredictorTest

# Run tests with coverage
mvn clean test jacoco:report
```

--------------------------------

### Build Status Badges

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Markdown snippets for displaying build status and code coverage badges in the README.

```markdown
[![Build Status](https://github.com/g4dpz/predict4java/workflows/Java%20CI%20with%20Maven/badge.svg)](https://github.com/g4dpz/predict4java/actions)
```

```markdown
[![codecov](https://codecov.io/gh/g4dpz/predict4java/branch/master/graph/badge.svg)](https://codecov.io/gh/g4dpz/predict4java)
```

--------------------------------

### Generate and View Local Coverage Reports

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Execute these commands to run tests, generate a JaCoCo report, and open the results in a browser.

```bash
mvn clean test jacoco:report
open target/site/jacoco/index.html
```

--------------------------------

### Generate and Export GPG Keys

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Commands to generate a GPG key pair and export the private key in base64 format for use in GitHub secrets.

```bash
gpg --gen-key
gpg --list-keys
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID
```

```bash
gpg --export-secret-keys YOUR_KEY_ID | base64
```

--------------------------------

### Configure Ground Station Position

Source: https://context7.com/g4dpz/predict4java/llms.txt

Defines observer coordinates and optional horizon elevation masks for terrain-aware tracking.

```java
import uk.me.g4dpz.satellite.GroundStationPosition;

// Basic ground station setup (latitude, longitude, altitude in meters)
GroundStationPosition london = new GroundStationPosition(
    51.5074,   // Latitude: 51.5074° N
    -0.1278,   // Longitude: 0.1278° W (negative for West)
    11.0       // Altitude: 11 meters above sea level
);

// Ground station with name
GroundStationPosition newYork = new GroundStationPosition(
    40.7128,   // Latitude: 40.7128° N
    -74.0060,  // Longitude: 74.0060° W
    10.0,      // Altitude: 10 meters
    "NYC Ground Station"
);

// Access properties
System.out.println("Station: " + newYork.getName());
System.out.println("Latitude: " + newYork.getLatitude());
System.out.println("Longitude: " + newYork.getLongitude());
System.out.println("Altitude: " + newYork.getHeightAMSL() + " meters");

// Set custom horizon elevations (36 values for 10-degree azimuth sectors)
// Useful for terrain masking where mountains block low elevations
int[] horizonMask = new int[36];  // Default: all zeros (flat horizon)
horizonMask[0] = 5;   // 5° elevation required at North (0°)
horizonMask[9] = 10;  // 10° elevation required at East (90°)
london.setHorizonElevations(horizonMask);
```

--------------------------------

### Track Multiple Satellites

Source: https://context7.com/g4dpz/predict4java/llms.txt

Demonstrates tracking multiple satellites by iterating through a map of TLE data and using PassPredictor for each.

```java
import uk.me.g4dpz.satellite.*;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Define multiple satellites
Map<String, String[]> satellites = new HashMap<>();
satellites.put("ISS", new String[]{
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
});
satellites.put("NOAA-19", new String[]{
    "NOAA 19",
    "1 33591U 09005A   26046.50000000  .00000123  00000-0  12345-4 0  9999",
    "2 33591  99.1234 123.4567 0012345  45.6789 314.5678 14.12345678123456"
});

// Ground station
GroundStationPosition groundStation = new GroundStationPosition(
    37.7749, -122.4194, 50.0  // San Francisco
);

Date now = new Date();
System.out.println("=== Multi-Satellite Tracking ===");
System.out.println("Location: San Francisco");
System.out.println("Time: " + now);
System.out.println();

// Track each satellite
for (Map.Entry<String, String[]> entry : satellites.entrySet()) {
    String name = entry.getKey();
    try {
        TLE tle = new TLE(entry.getValue());
        PassPredictor predictor = new PassPredictor(tle, groundStation);
        List<SatPos> positions = predictor.getPositions(now, 60, 0, 1);
        SatPos pos = positions.get(0);

        double el = Math.toDegrees(pos.getElevation());
        double az = Math.toDegrees(pos.getAzimuth());

        System.out.println(name + ":");
        System.out.printf("  Position: Az %.1f°, El %.1f°%n", az, el);
        System.out.printf("  Range: %.1f km%n", pos.getRange());
        System.out.printf("  Status: %s%n", el > 0 ? "VISIBLE" : "Below horizon");
        System.out.println();

    } catch (Exception e) {
        System.out.println(name + ": Error - " + e.getMessage());
    }
}
```

--------------------------------

### Trigger Build via Push

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Git commands to commit and push changes to the master branch to trigger a build.

```bash
git add .
git commit -m "ci: test CI/CD pipeline"
git push origin master
```

--------------------------------

### Trigger CI/CD Pipeline

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Commands to initiate the CI/CD pipeline via push or pull request.

```bash
# Option A: Push to master
git add .
git commit -m "ci: implement advanced CI/CD pipeline"
git push origin master

# Option B: Create PR
git checkout -b test-ci
git add .
git commit -m "ci: implement advanced CI/CD pipeline"
git push origin test-ci
# Create PR on GitHub
```

--------------------------------

### Trigger Build via Pull Request

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Git commands to create a new branch and push it to trigger a build for a pull request.

```bash
git checkout -b test-ci
git add .
git commit -m "ci: test CI/CD pipeline"
git push origin test-ci
```

--------------------------------

### Configure Workflow Triggers

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

YAML configuration defining the events that trigger the GitHub Actions workflow.

```yaml
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
```

--------------------------------

### Set GitHub Secrets via CLI

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Use the GitHub CLI (`gh`) to securely set repository secrets. This is an alternative to using the GitHub Web UI.

```bash
# Via GitHub CLI
gh secret set CODECOV_TOKEN
```

--------------------------------

### Configure Java Matrix in Maven CI

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Add new Java versions to the build matrix by editing the `java` array in `.github/workflows/maven-ci.yml`.

```yaml
strategy:
  matrix:
    java: [ '11', '17', '21', '23' ]  # Add new version
```

--------------------------------

### Configure Maven Caching

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Snippet for enabling Maven dependency caching within the GitHub Actions workflow.

```yaml
cache: 'maven'
```

--------------------------------

### Validate Workflows Locally

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_SETUP.md

Command to validate workflow configuration locally using the act tool.

```bash
act -l
```

--------------------------------

### Set GitHub Secrets via Web UI

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Instructions for adding new repository secrets through the GitHub web interface, located under Settings → Secrets and variables → Actions.

```text
# Via GitHub Web UI
# Settings → Secrets and variables → Actions → New repository secret
```

--------------------------------

### Add Coverage Quality Gate

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Integrate a coverage threshold check into the build job using the JaCoCo Maven plugin. Set `jacoco.haltOnFailure=true` to fail the build if thresholds are not met.

```bash
- name: Check coverage threshold
  run: |
    mvn jacoco:check \
      -Djacoco.haltOnFailure=true \
      -Djacoco.instructionRatio=0.90 \
      -Djacoco.branchRatio=0.75
```

--------------------------------

### Display Codecov Badge in Markdown

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Use this Markdown snippet to display the project's Codecov coverage status in a README file.

```markdown
[![codecov](https://codecov.io/gh/g4dpz/predict4java/branch/master/graph/badge.svg)](https://codecov.io/gh/g4dpz/predict4java)
```

--------------------------------

### Add Dependency Integration

Source: https://context7.com/g4dpz/predict4java/llms.txt

Configuration snippets for including predict4java in Maven or Gradle projects.

```xml
<!-- Maven pom.xml -->
<dependency>
    <groupId>uk.me.g4dpz</groupId>
    <artifactId>predict4java</artifactId>
    <version>1.2.2</version>
</dependency>
```

```groovy
// Gradle build.gradle
implementation 'uk.me.g4dpz:predict4java:1.2.2'
```

--------------------------------

### Set Artifact Retention Policy

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_IMPLEMENTATION_SUMMARY.md

Configuration for defining the number of days build artifacts are retained in the GitHub Actions UI.

```yaml
retention-days: 30
```

--------------------------------

### Calculate Satellite Position Relative to Ground Station

Source: https://context7.com/g4dpz/predict4java/llms.txt

Use this snippet to calculate and display a satellite's real-time position relative to a specified ground station. Ensure you have the TLE data and ground station coordinates correctly set up. The output includes azimuth, elevation, range, and ground track details.

```java
import uk.me.g4dpz.satellite.*;
import java.util.Date;

// Setup satellite and ground station
String[] tleData = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(tleData);
Satellite satellite = SatelliteFactory.createSatellite(tle);

GroundStationPosition groundStation = new GroundStationPosition(
    52.4670, -2.022, 200.0  // UK location
);

// Calculate position at current time
Date now = new Date();
SatPos position = satellite.getPosition(groundStation, now);

// Position relative to ground station (in radians, convert to degrees)
double azimuthDeg = Math.toDegrees(position.getAzimuth());
double elevationDeg = Math.toDegrees(position.getElevation());

System.out.println("=== Satellite Position ===");
System.out.println("Time: " + now);
System.out.println("Azimuth: " + String.format("%.2f", azimuthDeg) + "°");
System.out.println("Elevation: " + String.format("%.2f", elevationDeg) + "°");
System.out.println("Range: " + String.format("%.1f", position.getRange()) + " km");
System.out.println("Range Rate: " + String.format("%.3f", position.getRangeRate()) + " km/s");

// Sub-satellite point (ground track)
double latDeg = Math.toDegrees(position.getLatitude());
double lonDeg = Math.toDegrees(position.getLongitude());
System.out.println("\n=== Ground Track ===");
System.out.println("Latitude: " + String.format("%.4f", latDeg) + "°");
System.out.println("Longitude: " + String.format("%.4f", lonDeg) + "°");
System.out.println("Altitude: " + String.format("%.1f", position.getAltitude()) + " km");

// Visibility and eclipse status
System.out.println("\n=== Status ===");
System.out.println("Above Horizon: " + position.isAboveHorizon());
System.out.println("Eclipsed: " + position.isEclipsed());

// Check if satellite is visible
if (position.getElevation() > 0) {
    System.out.println("Satellite is VISIBLE from your location!");
} else {
    System.out.println("Satellite is below the horizon.");
}

```

--------------------------------

### Update Dependency Configuration

Source: https://github.com/g4dpz/predict4java/blob/master/CHANGELOG.md

Use these snippets to update your build configuration to version 1.2.0 of the predict4java library.

```xml
<dependency>
    <groupId>com.badgersoft</groupId>
    <artifactId>predict4java</artifactId>
    <version>1.2.0</version>
</dependency>
```

```gradle
implementation 'com.badgersoft:predict4java:1.2.0'
```

--------------------------------

### Calculate Satellite Footprint

Source: https://context7.com/g4dpz/predict4java/llms.txt

Calculates the coverage area of a satellite using getRangeCircle, which returns 360 latitude/longitude points.

```java
import uk.me.g4dpz.satellite.*;
import java.util.Date;

// Setup and get position
String[] tleData = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(tleData);
Satellite satellite = SatelliteFactory.createSatellite(tle);
GroundStationPosition gs = new GroundStationPosition(0, 0, 0);

SatPos position = satellite.getPosition(gs, new Date());

// Get the coverage footprint (360 points, one per degree of azimuth)
double[][] rangeCircle = position.getRangeCircle();

System.out.println("=== Satellite Footprint ===");
System.out.println("Sub-satellite point: " +
    String.format("%.2f°, %.2f°",
        Math.toDegrees(position.getLatitude()),
        Math.toDegrees(position.getLongitude())));
System.out.println("Altitude: " + String.format("%.1f km", position.getAltitude()));
System.out.println();
System.out.println("Footprint boundary points (every 30°):");

// Print every 30th point (12 points total)
for (int i = 0; i < 360; i += 30) {
    double lat = rangeCircle[i][0];  // Already in degrees
    double lon = rangeCircle[i][1];  // Already in degrees
    System.out.printf("  Azimuth %3d°: Lat %.2f°, Lon %.2f°%n", i, lat, lon);
}
```

--------------------------------

### Add Predict4Java Dependency (Gradle)

Source: https://github.com/g4dpz/predict4java/blob/master/RELEASE_1.2.2_SUMMARY.md

Add this line to your Gradle project's build.gradle file to include Predict4Java version 1.2.2.

```gradle
implementation 'uk.me.g4dpz:predict4java:1.2.2'
```

--------------------------------

### Parse TLE Data

Source: https://context7.com/g4dpz/predict4java/llms.txt

Parses NORAD Two-Line Element sets from strings or files to extract orbital parameters.

```java
import uk.me.g4dpz.satellite.TLE;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.List;

// Create TLE from three-line string array
String[] tleLines = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(tleLines);

// Access orbital parameters
System.out.println("Satellite Name: " + tle.getName());           // ISS (ZARYA)
System.out.println("Catalog Number: " + tle.getCatnum());         // 25544
System.out.println("Inclination: " + tle.getIncl() + " degrees"); // 51.6416
System.out.println("Eccentricity: " + tle.getEccn());             // 0.0006703
System.out.println("Mean Motion: " + tle.getMeanmo() + " rev/day"); // 15.72125391
System.out.println("Is Deep Space: " + tle.isDeepspace());        // false

// Import multiple satellites from file
InputStream fileStream = new FileInputStream("satellites.tle");
List<TLE> satellites = TLE.importSat(fileStream);
for (TLE sat : satellites) {
    System.out.println("Loaded: " + sat.getName());
}
```

--------------------------------

### Add Gradle Dependency for predict4java

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Add this to your build.gradle file to include the predict4java library in your Gradle project.

```gradle
implementation 'uk.me.g4dpz:predict4java:1.2.0'
```

--------------------------------

### Calculate Satellite Positions Over Time

Source: https://context7.com/g4dpz/predict4java/llms.txt

Use PassPredictor.getPositions to generate a time series of satellite positions, including azimuth, elevation, latitude, longitude, and range. This is useful for plotting orbital paths or tracking during a pass. Specify reference time, interval, and time window.

```java
import uk.me.g4dpz.satellite.*;
import java.util.Date;
import java.util.List;

// Setup
String[] tleData = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(tleData);
GroundStationPosition groundStation = new GroundStationPosition(51.5074, -0.1278, 11.0);
PassPredictor predictor = new PassPredictor(tle, groundStation);

// Get positions: reference time, interval (seconds), minutes before, minutes after
Date referenceTime = new Date();
int incrementSeconds = 60;    // Calculate every 60 seconds
int minutesBefore = 5;        // Start 5 minutes before reference
int minutesAfter = 10;        // End 10 minutes after reference

List<SatPos> positions = predictor.getPositions(
    referenceTime,
    incrementSeconds,
    minutesBefore,
    minutesAfter
);

System.out.println("=== Position Time Series ===");
System.out.println("Positions calculated: " + positions.size());
System.out.println();

for (SatPos pos : positions) {
    double az = Math.toDegrees(pos.getAzimuth());
    double el = Math.toDegrees(pos.getElevation());
    double lat = Math.toDegrees(pos.getLatitude());
    double lon = Math.toDegrees(pos.getLongitude());

    System.out.printf("Time: %s | Az: %6.1f° | El: %5.1f° | Lat: %6.2f° | Lon: %7.2f° | Range: %7.1f km%n",
        pos.getTime(), az, el, lat, lon, pos.getRange());
}
```

--------------------------------

### Satellite.getPosition

Source: https://context7.com/g4dpz/predict4java/llms.txt

Calculates the satellite's position relative to a ground station at a specific time.

```APIDOC
## Satellite.getPosition

### Description
The getPosition method calculates the satellite's position relative to a ground station at a specific time. It returns a SatPos object containing azimuth, elevation, range, range rate, latitude, longitude, altitude, and eclipse status.

### Parameters
#### Request Body
- **groundStation** (GroundStationPosition) - Required - The location of the ground station (latitude, longitude, altitude).
- **time** (Date) - Required - The specific time for which to calculate the position.

### Response
#### Success Response (200)
- **azimuth** (double) - Azimuth angle in radians.
- **elevation** (double) - Elevation angle in radians.
- **range** (double) - Range to the satellite in km.
- **rangeRate** (double) - Range rate in km/s.
- **latitude** (double) - Sub-satellite latitude in radians.
- **longitude** (double) - Sub-satellite longitude in radians.
- **altitude** (double) - Satellite altitude in km.
- **aboveHorizon** (boolean) - Visibility status.
- **eclipsed** (boolean) - Eclipse status.
```

--------------------------------

### Check Satellite Visibility from Ground Station

Source: https://context7.com/g4dpz/predict4java/llms.txt

Determines if a satellite will ever rise above the horizon from a specified ground station. Useful for filtering visible satellites. Requires ground station coordinates and satellite TLE data.

```java
import uk.me.g4dpz.satellite.*;

// Define ground station
GroundStationPosition groundStation = new GroundStationPosition(
    51.5074, -0.1278, 11.0  // London
);

// Check multiple satellites
String[][] satellites = {
    {"ISS (ZARYA)",
     "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
     "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"},
    {"HUBBLE",
     "1 20580U 90037B   26046.50000000  .00001234  00000-0  12345-4 0  9999",
     "2 20580  28.4699 123.4567 0002345  45.6789 314.5678 15.09876543123456"}
};

System.out.println("=== Visibility Check for London ===");
for (String[] tleLines : satellites) {
    TLE tle = new TLE(tleLines);
    Satellite sat = SatelliteFactory.createSatellite(tle);

    boolean canBeSeen = sat.willBeSeen(groundStation);
    String status = canBeSeen ? "VISIBLE" : "Never visible";
    System.out.println(tle.getName() + ": " + status);
}

```

--------------------------------

### Customize Workflow Triggers

Source: https://github.com/g4dpz/predict4java/blob/master/CI_CD_GUIDE.md

Modify the `on` section in the workflow file to change when the CI pipeline runs, such as adding new branches for push or pull request events.

```yaml
on:
  push:
    branches: [ master, develop ]  # Add branches
  pull_request:
    branches: [ master ]
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
```

--------------------------------

### Add Predict4Java Dependency (Maven)

Source: https://github.com/g4dpz/predict4java/blob/master/RELEASE_1.2.2_SUMMARY.md

Include this XML snippet in your Maven project's pom.xml to add Predict4Java version 1.2.2 as a dependency.

```xml
<dependency>
    <groupId>uk.me.g4dpz</groupId>
    <artifactId>predict4java</artifactId>
    <version>1.2.2</version>
</dependency>
```

--------------------------------

### Add Maven Dependency for predict4java

Source: https://github.com/g4dpz/predict4java/blob/master/examples/README.md

Add this to your pom.xml to include the predict4java library in your Maven project.

```xml
<dependency>
    <groupId>uk.me.g4dpz</groupId>
    <artifactId>predict4java</artifactId>
    <version>1.2.0</version>
</dependency>
```

--------------------------------

### Predict Satellite Passes

Source: https://context7.com/g4dpz/predict4java/llms.txt

Use PassPredictor to calculate the next satellite pass or a series of passes over a specified duration. Requires TLE data and ground station coordinates. Filters can be applied to select passes based on maximum elevation.

```java
import uk.me.g4dpz.satellite.*;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.List;
import java.util.TimeZone;

// Setup
String[] tleData = {
    "ISS (ZARYA)",
    "1 25544U 98067A   26046.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
};
TLE tle = new TLE(tleData);
GroundStationPosition groundStation = new GroundStationPosition(40.7128, -74.0060, 10.0);

// Create pass predictor
PassPredictor predictor = new PassPredictor(tle, groundStation);

// Predict the next single pass
Date startTime = new Date();
SatPassTime nextPass = predictor.nextSatPass(startTime);

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

System.out.println("=== Next Pass ===");
System.out.println("AOS (Start): " + sdf.format(nextPass.getStartTime()) + " UTC");
System.out.println("TCA (Max El): " + sdf.format(nextPass.getTCA()) + " UTC");
System.out.println("LOS (End): " + sdf.format(nextPass.getEndTime()) + " UTC");
System.out.println("AOS Azimuth: " + nextPass.getAosAzimuth() + "°");
System.out.println("Max Elevation: " + String.format("%.1f", nextPass.getMaxEl()) + "°");
System.out.println("LOS Azimuth: " + nextPass.getLosAzimuth() + "°");
System.out.println("Pole Passed: " + nextPass.getPolePassed());

// Calculate pass duration
long durationMs = nextPass.getEndTime().getTime() - nextPass.getStartTime().getTime();
double durationMin = durationMs / 60000.0;
System.out.println("Duration: " + String.format("%.1f", durationMin) + " minutes");

// Predict multiple passes over a time period
int hoursAhead = 24;  // Look 24 hours ahead
boolean windBack = true;  // Check if pass is already in progress
List<SatPassTime> passes = predictor.getPasses(startTime, hoursAhead, windBack);

System.out.println("\n=== Passes in Next 24 Hours ===");
int passNum = 1;
for (SatPassTime pass : passes) {
    // Filter for good passes (elevation > 10°)
    if (pass.getMaxEl() > 10.0) {
        System.out.println("Pass #" + passNum++);
        System.out.println("  Start: " + sdf.format(pass.getStartTime()));
        System.out.println("  Max El: " + String.format("%.1f°", pass.getMaxEl()));
        System.out.println("  End: " + sdf.format(pass.getEndTime()));
        System.out.println();
    }
}
```