Quick start

What you will accomplish

By the end of this page you will have generated a 60-satellite Walker Delta constellation, propagated it for six hours, and produced a CZML file that animates on a 3D globe.

Expect 20 to 40 minutes, most of it waiting for the first compile.

Prerequisites

Requirement	Why	Check
Rust toolchain	The engine that does the physics	`cargo --version`
Node.js	Only for the 3D viewer, not for the engine	`node --version`
A local copy of the workspace	Source is built from a checkout	`ls Cargo.toml`

Install Rust from rustup.rs and Node.js from nodejs.org . Accept the defaults for both, then open a new terminal so the changes take effect.

Steps

Build the engine

From the root of the workspace:


cargo build

The first build downloads and compiles every dependency and takes several minutes with a large amount of scrolling output. That is expected. When your prompt returns with no error, the engine is ready.

Subsequent builds are seconds, not minutes.

Generate a constellation

A Walker Delta is defined by how many orbital planes you want, how many satellites go in each plane, how high they fly, and how tilted the orbits are.


orbitforge constellation walker \
  --name demo --planes 6 --sats-per-plane 10 \
  --altitude-km 550 --inclination-deg 53 --fov-deg 45 \
  --output demo.json


Generated 'demo' with 60 satellites (6 planes x 10 per plane) -> demo.json

What you just asked for:

Flags used above. The full set is in the CLI reference.
Parameter	Type	Unit	Default	Required	Description
`--planes`	integer	count	—	Yes	Number of orbital planes, the "rings" the satellites travel in.
`--sats-per-plane`	integer	count	—	Yes	Satellites evenly spaced within each plane.
`--altitude-km`	float	km	—	Yes	Height above the Earth ellipsoid. 550 km is a typical low Earth orbit.
`--inclination-deg`	float	deg	—	Yes	Orbit tilt. 0 deg is equatorial, 90 deg is polar. 53 deg favors mid latitudes.
`--fov-deg`	float	deg	`45`	No	Payload field of view, used later for coverage footprints.
`--output`	path	n/a	—	Yes	Where to write the constellation definition.

Propagate it

Generating a constellation only places satellites at an initial instant. Propagating advances them through time and records where they go.


orbitforge simulate \
  --constellation demo.json --duration-hours 6 --step-seconds 60 \
  --czml demo.czml


Simulated 60 satellites over 6.0 h at 60 s steps (361 samples each) using two_body.
Wrote CZML -> demo.czml

361 samples is 6 hours at 60-second steps, inclusive of both endpoints.

two_body is the default propagation model: a point-mass Earth with no oblateness, drag, or third-body effects. It is fast and adequate for a first look. It is not adequate for a design review. Choosing a fidelity level is covered in the propagation guides.

Watch it orbit

Start the viewer from the apps/orbitforge-web directory:


npm install
npm run dev

Open the URL it prints, then load demo.czml. You should see 60 satellites in six distinct planes, with trails, moving against a 3D Earth.

Verification

You succeeded if all four are true:

demo.json exists and is non-empty.
The simulate command reported 60 satellites and 361 samples each.
demo.czml exists and is substantially larger than demo.json.
The globe shows six evenly spaced planes, not a single ring or a random cloud.

If the satellites form one ring rather than six planes, --planes was probably passed as 1.

Interpreting the result

The six planes are spaced evenly in right ascension of the ascending node, the angle where each orbit crosses the equator going north. Within a plane the ten satellites are spaced evenly in true anomaly, their position around the ring. That even spread is what makes a Walker pattern useful: coverage gaps are distributed rather than concentrated.

At 550 km the orbital period is roughly 96 minutes, so six hours is close to four revolutions. You should see each satellite return near its starting point slightly displaced, because the Earth rotates underneath.

Troubleshooting

Symptom	Cause	Fix
`command not found: orbitforge`	The binary is not on your PATH	Run it as `cargo run -p orbitforge-cli --` followed by the same arguments
`cargo build` fails on a missing linker	No C toolchain	On macOS run `xcode-select --install`
Simulate reports 0 samples	`--duration-hours` smaller than `--step-seconds`	Increase duration or reduce the step
Globe renders but nothing moves	The viewer clock is outside the scenario window	Reset the viewer clock to the scenario start epoch

Next steps

Link budgets to find out whether these satellites can actually close a link to the ground.
simulate reference for every flag, including higher-fidelity force models.
Accuracy and limitations before you put any of this in a review.

Question? Give us feedbackDocuments Varaha Constellation Designer main (pre-release)