Terran Republic Interstellar Plotter System

Introduction

TRIPS (Terran Interstellar Plotter System) is a JavaFX-based 3D stellar cartography application for visualizing and plotting interstellar routes. It combines Spring Boot for backend services with JavaFX for 3D visualization, using an embedded H2 database for persistence.

Origins: Initially developed with Chuck Gannon to help visualize the stellar neighborhood for his Caine Riordan series. See charlesegannon.com.

Key capabilities:

• View and edit stellar data in tabular form
• Plot stars in an interactive 3D visualization
• Plan interstellar routes using graph algorithms
• Explore solar systems with orbital visualization
• Generate procedural planets with realistic terrain
• Import data from major astronomical catalogs (Gaia, SIMBAD, VizieR)
• Use for scientific research or science fiction world-building

---

Prerequisites

• Java 25 (Eclipse Temurin recommended)
• Maven (or use the included mvnw-java25.sh wrapper)
• Docker — required for running integration tests (the project uses Testcontainers with PostgreSQL for database testing). Docker Desktop or a compatible runtime must be running before you execute mvn test or mvn install. To skip tests: ./mvnw-java25.sh clean install -DskipTests

Building

# Build the project
./mvnw-java25.sh clean install

# Build without tests (no Docker required)
./mvnw-java25.sh clean install -DskipTests

# Run the application
cd tripsapplication
../mvnw-java25.sh spring-boot:run

Packaging for Distribution

# macOS (.dmg installer)
./mvnw-java25.sh clean package -Pjpackage-mac

# Windows (.exe installer)
./mvnw-java25.sh clean package -Pjpackage-win

Output is written to tripsapplication/target/jpackage/. See the Packaging Guide for more details.

macOS Application Data

When running as a packaged macOS application, TRIPS stores all data under ~/Library/Application Support/TRIPS/. For example, for a user named jsmith:

/Users/jsmith/Library/Application Support/TRIPS/
├── data/
│   └── tripsdb.mv.db          # H2 database
├── files/
│   ├── programdata/            # Application preferences and saved state
│   └── scriptfiles/            # Groovy scripts

Logs are written to ~/Library/Logs/TRIPS/terranrepublicviewer.log.

To reset the application to a clean state, delete the ~/Library/Application Support/TRIPS/ directory.

Sample Datasets

Bulk catalogs and sample datasets are not tracked in git (they inflate the repo and rotate often). Download them yourself and drop them in either the repo root or files/:

File	Source	Notes
HYG-MERGED-2M-TRIPS-*.csv	astronexus HYG database (HYG v3 merged with TRIPS fields, ~2M stars, ~830 MB)	Optional. Used for large-catalog imports via Data Workbench.
exoplanet.eu_catalog_*.csv	exoplanet.eu (download "All Planets, csv")	Used by the Data Workbench Exoplanets tab.
30ly.trips.csv	TRIPS sample dataset (the local-30-light-year set used for first-time-launch demos). Ask a maintainer for the latest copy if you don't already have it.	Optional; the app will still start without it.
files/exoplanets/exoplanets.csv	NASA Exoplanet Archive or the exoplanet.eu export above.	Optional; replaced at import time.

The small reference CSVs the app actually needs at runtime (constellation tables, comet parameters, planetary sims under tripsapplication/src/main/resources/planetsim/, etc.) are tracked in git via positive exceptions in .gitignore.

If you accidentally git add a large catalog, git rm --cached <file> will untrack it without deleting your local copy.

Quick Start

• Installation
• Running TRIPS
• User Manual

Documentation Map

• Features
• Architecture and Technical Docs
• Data Workbench Guide
• Packaging Guide

Contributing

• Helping with programming
• Helping with documentation
• Contributing
• Code of Conduct