From f6cf651830829752923a9e109475424691232f83 Mon Sep 17 00:00:00 2001
From: Brandon Rhodes <brandon@rhodesmill.org>
Date: Sat, 15 Feb 2025 02:22:49 -0500
Subject: [PATCH] Document how to load satellites from JSON OMM file

---
 sgp4/__init__.py     | 31 +++++++++++++++++++++----------
 sgp4/sample_omm.json | 19 +++++++++++++++++++
 2 files changed, 40 insertions(+), 10 deletions(-)
 create mode 100644 sgp4/sample_omm.json

diff --git a/sgp4/__init__.py b/sgp4/__init__.py
index f3994fe..a2d908e 100644
--- a/sgp4/__init__.py
+++ b/sgp4/__init__.py
@@ -169,19 +169,30 @@
 Reading OMM data takes two steps, because OMM supports several different
 text formats.  First, parse the input text to recover the field names
 and values that it stores; second, build a Python satellite object from
-those field values.  For example, to load OMM from XML:
+those field values.  The fastest and most efficient format is usually
+CSV, since the column names are only given once, on the first line:
 
->>> with open('sample_omm.xml') as f:
-...     fields = next(omm.parse_xml(f))
->>> sat = Satrec()
->>> omm.initialize(sat, fields)
+>>> with open('sample_omm.csv') as f:
+...     for fields in omm.parse_csv(f):
+...         sat = Satrec()
+...         omm.initialize(sat, fields)
 
-Or, to load OMM from CSV:
+The JSON format is more verbose because it repeats the field names over
+again in every single record:
 
->>> with open('sample_omm.csv') as f:
-...     fields = next(omm.parse_csv(f))
->>> sat = Satrec()
->>> omm.initialize(sat, fields)
+>>> import json
+>>> with open('sample_omm.json') as f:
+...     record_list = json.load(f)
+>>> for fields in record_list:
+...     sat = Satrec()
+...     omm.initialize(sat, fields)
+
+The most verbose format is XML:
+
+>>> with open('sample_omm.xml') as f:
+...     for fields in omm.parse_xml(f):
+...         sat = Satrec()
+...         omm.initialize(sat, fields)
 
 Either way, the satellite object should wind up properly initialized and
 ready to start producing positions.
diff --git a/sgp4/sample_omm.json b/sgp4/sample_omm.json
new file mode 100644
index 0000000..8a63452
--- /dev/null
+++ b/sgp4/sample_omm.json
@@ -0,0 +1,19 @@
+[{
+    "OBJECT_NAME": "VANGUARD 1",
+    "OBJECT_ID": "1958-002B",
+    "EPOCH": "2025-02-14T14:36:48.662784",
+    "MEAN_MOTION": 10.85873516,
+    "ECCENTRICITY": 0.1841322,
+    "INCLINATION": 34.2493,
+    "RA_OF_ASC_NODE": 19.2327,
+    "ARG_OF_PERICENTER": 100.1057,
+    "MEAN_ANOMALY": 281.1229,
+    "EPHEMERIS_TYPE": 0,
+    "CLASSIFICATION_TYPE": "U",
+    "NORAD_CAT_ID": 5,
+    "ELEMENT_SET_NO": 999,
+    "REV_AT_EPOCH": 39027,
+    "BSTAR": 0.00035436,
+    "MEAN_MOTION_DOT": 2.64e-6,
+    "MEAN_MOTION_DDOT": 0
+}]