Binary Orbit 3D Visualizer 🌌

Check it out live: https://orbit.r71.org/

Welcome to the Binary Orbit 3D Visualizer! This graph is for plotting existing (or new) binary star data in a way that can be easily visualized.

---

🔌 Raw API

If you'd rather skip the web UI and just get orbit fits over HTTP, hit the endpoint directly:

POST https://orbit.r71.org/process

Request body (JSON):

{
  "data": [
    {"t": 2000.0, "x":  1.0, "y":  0.0, "weight": 1.0},
    {"t": 2001.0, "x":  0.5, "y":  0.8, "weight": 1.0},
    {"t": 2002.0, "x": -0.5, "y":  0.8, "weight": 1.0},
    {"t": 2003.0, "x": -1.0, "y":  0.0, "weight": 1.0}
  ],
  "periodBound": [2.0, 40.0]
}

Response: a 7-element JSON array, in order: semi-major axis, eccentricity, inclination (rad), longitude of ascending node (rad), argument of periapsis (rad), mean anomaly at epoch (rad), period (years).

Optional "method" field picks the fitter:

• "de" (default) — differential evolution + BFGS polish. Fastest.
• "gd" — multistart noisy gradient descent + BFGS polish. A little slower, slightly more robust on datasets with many competing period harmonics.

curl -s -X POST https://orbit.r71.org/process \
  -H 'content-type: application/json' \
  -d '{"data":[{"t":2000,"x":1,"y":0,"weight":1},{"t":2001,"x":0.5,"y":0.8,"weight":1},{"t":2002,"x":-0.5,"y":0.8,"weight":1},{"t":2003,"x":-1,"y":0,"weight":1}],"periodBound":[2,10],"method":"de"}'

POST https://orbit.r71.org/evaluate — score an existing fit against observations. Body: {"data": [...], "parameters": [sm, e, i, node, periapsis, m0, p]}. Response: {"loss": ..., "r_squared": ...} where r_squared = 1 − SS_res/SS_tot (closer to 1 is a better fit).

The endpoints are open and free — there's no auth and no rate limit, so please be reasonable if you're scripting them.

---

🌟 What Can It Do? (Key Features)

• See Orbits in 3D: Get a sense of a binary system in three-dimensional space.
• Fit Your Data: Crunch observational data and find out the best-fit orbit, displaying the key parameters.
• Interactivity:
  • Sample Orbits: The data for 4 actual orbital systems are included with this site.
  • Upload Data: This tool supports uploading your own binary star data.
  • Change Faulty Data:
    • Remove Point: You can remove outliers from the visualizations and calculations
    • Highlight Point: Make a specific data point stand out by coloring it black.
    • Flip Coordinates: Historical data often contains points with some coordinates flipped, so flip them back!
• Get the Results: Once optimized, you'll see the orbital parameters that describe the orbit.

---

• Set Period Bounds: You must give the tool a range containing the true period for it to function.

🚀 Using The Tool

1. Getting Data on the Screen

• Using The Sample Data:

  • Ensure the "Use sample data" checkbox is ticked.
  • Pick an example orbit from the dropdown list.

• Using Your Own Data:

  • To see the correct data format, load some sample data and then click the "Download updated data file" button. That'll give you a template.
  • Once your file is ready, use the file browser (it will appear when you uncheck "Use sample data") to load your data.

Important Note: At this stage, you'll only see the raw data points plotted in the 3D space. The orbit hasn't been fitted yet!

2. Fitting Data

• Ensure Period Bounds are Set Correctly
  • The default period bounds are 2-40 years. Many binary systems are well outside of this range, so ensure you have the bounds set to an appropriate timeframe.
  • The units are always years, so make sure units are converted before putting them in.
• Hit "Optimize Orbit!"

3. Tweaking Data

• Choose Appropriate Setting
  • Do Nothing
  • Remove Point Removes points.
  • Highlight point Makes points black to distinguish them.
  • Negate RA Negates the RA coordinate of the point.
  • Negate Dec Negates the Dec coordinate of the point.
  • Negate RA and Dec Negates the RA and Dec coordinates of the point.
• Click any point on the graph.
  • When all data is adjusted. It is highly recommended that you re-fit the data using the "Optimize Orbit!" button.

4. Download Updated Data and Read Parameters

• Download Updated Data
  • Click the "Download updated data file" button.
• Read Parameters
  • Read all 7 orbital parameters at the bottom section of the page.

---

Running It Yourself

The site and the optimizer are the same Python process — server.py serves the static files, proxies the Desmos SDK at /desmos-calculator.js (so the API key never reaches the browser), and exposes POST /process for orbit fits. Requires numpy and scipy.

1. Put your Desmos API key in the environment:

   export DESMOS_API_KEY=dcb31709b452b1cf9dc26972add0fda6   # Desmos demo key (dev only)

2. Run the server:

   python3 server.py --host 127.0.0.1 --port 8081

3. Open http://127.0.0.1:8081/.

To override the fitting endpoint (e.g. if you host the frontend elsewhere), create config.js with export const API_ENDPOINT_URL = "...".

For a production fork, request your own Desmos API key from partnerships@desmos.com.