Transfer

POST/transfer/lambert

Purpose

Solves Lambert’s problem: given a departure position, an arrival position, and the time to travel between them, find the orbit that connects them.

The answer is two velocity vectors. Differencing them against the velocities you actually have gives the delta-v of a transfer, which is why this underpins rendezvous, intercept, and phasing analysis.

This endpoint is pure geometry. It touches no constellation, so it works immediately after startup and takes no constellation_id.

Request

Parameter	Type	Unit	Default	Required	Description
`r1_km`	array of 3 numbers	km	—	Yes	Departure position in ECI, as `[x, y, z]`.
`r2_km`	array of 3 numbers	km	—	Yes	Arrival position in ECI.
`tof_s`	number	s	—	Yes	Time of flight, in SECONDS. The CLI takes `--tof-minutes`; this takes seconds.
`direction`	string	n/a	`short_way`	No	`short_way` sweeps under 180 degrees; `long_way` sweeps over it.

The unit differs from the CLI. orbitforge transfer lambert takes --tof-minutes; this endpoint takes tof_s in seconds. Sending 60 here means one minute, not one hour, and the request succeeds either way.

Because tof_s is required, a missing field fails loudly:


Failed to deserialize the JSON body into the target type: missing field `tof_s` at line 1 column 58

A wrong value does not.

Example

The same quarter-revolution transfer the CLI page uses, expressed in seconds:


curl -s -X POST http://127.0.0.1:8080/transfer/lambert \
  -H 'content-type: application/json' \
  -d '{
        "r1_km": [7000, 0, 0],
        "r2_km": [0, 8000, 0],
        "tof_s": 3600.0
      }'


{
  "v1_km_s": [4.606920466650254, 5.853215954289316, 0.0],
  "v2_km_s": [-5.121563960003151, -3.8752684723640893, -0.0],
  "transfer_angle_deg": 90.0,
  "semi_major_axis_km": 6825.117775722259
}

Response fields.
Parameter	Type	Unit	Default	Required	Description
`v1_km_s`	array of 3 numbers	km/s	—	No	Velocity required at departure, ECI.
`v2_km_s`	array of 3 numbers	km/s	—	No	Velocity on arrival, ECI.
`transfer_angle_deg`	number	deg	—	No	Angle swept between the two position vectors.
`semi_major_axis_km`	number	km	—	No	Size of the connecting orbit.

Reading the result

Departure speed is 7.449 km/s and arrival speed 6.422 km/s. Speed falls because the spacecraft climbs from 7000 km to 8000 km, trading kinetic energy for potential. On any transfer to a higher radius the arrival speed should be lower, which makes this a free sanity check on your inputs.

The z-components are zero because both positions lie in the equatorial plane, so the transfer orbit does too. Any out-of-plane component produces an inclined transfer, and the plane change is usually the expensive part.

These are velocities, not delta-v

The endpoint returns the velocities the transfer requires. To get its cost, difference them against what you have:

\Delta v_{\text{depart}} = \left| \mathbf{v}_1 - \mathbf{v}_{\text{initial}} \right|, \qquad \Delta v_{\text{arrive}} = \left| \mathbf{v}_{\text{final}} - \mathbf{v}_2 \right|

The usual workflow is to sweep tof_s, compute total delta-v for each, and take the minimum. That curve is rarely monotonic: very short flights need an extreme transfer orbit, and very long ones can suffer unfavorable arrival geometry.

Frames are your responsibility

Both positions must be in the same inertial frame. The endpoint performs no frame conversion and takes no epoch: it is geometry, and nothing in the response indicates whether your two vectors were consistently expressed.

Mixing an ECI departure with an ECEF arrival produces a confident solution to a problem you did not intend.