Top  Previous  Next

Formations are a container for one or more Spacecraft objects. Formations are a specialized version of a List of Spacecraft (you can create a List of most types of FreeFlyer objects). The benefit of a Formation over a List of Spacecraft is that the Formation provides additional control over the visualization of the Spacecraft, and allows you to read TLE data into each Spacecraft in the Formation using a single line of script.


Note: The Save, Restore, Get, and Put commands cannot be used with Formations.


There are a variety of Sample Mission Plans (included with your FreeFlyer installation) that demonstrate various applications of this topic. Continue to the FreeFlyer Scripting Samples page to view descriptions and images of these examples or jump to one of the Mission Plans listed below.


Coverage and Contact Samples

Chain Visibility



Debris Field Visualization

MMS Visualization

Satellite Breakup Simulation


Interfacing with External Resources Samples

Download TLEs


FreeFlyer Scripting Samples

Launch Site Visualization

Sync TLEs


Spacecraft Propagation Samples

A-Train Orbit Plane with Debris

Walker Constellation



Creating a Formation

Unlike Lists, Formation objects can be created via the Object Browser as well as through FreeFlyer Script. The Formation object editor consists of two pages. From the first page, you can define the initialization source for the states of each Spacecraft in the Formation. The choices are:


Initialize using an SGP4 TLE

Initialize using a RINEX Broadcast Ephemeris

Initialize using a SP3 Precise Ephemeris File

Define the states in FreeForm Script - discussed in detail below.


Properties Page of the Formation Object Editor

Properties Page of the Formation Object Editor


On the second page, you can control visualization options for the Formation. You can choose whether to visualize each Spacecraft as a point, or to draw using a 3D model. These options maps to the ViewAsGroup and GroupPointSize properties discussed below.


Visualization Page of the Formation Object Editor

Visualization Page of the Formation Object Editor


The format for the creation of Formation objects in FreeFlyer script follows the same syntax as creation of most other FreeFlyer objects:


Formation myFormation;

Formation LEOFormation;



Setting the Number of Spacecraft in a Formation

When you first create a Formation in FreeFlyer script, it will be empty. To begin editing a Formation, start by setting its "Count", or length. This specifies how many Spacecraft the Formation will contain. The Count can be set using any numeric value, including functions which return numeric values, such as the GetNumberOfSGP4States() function used below.


myFormation.Count = 12;

LEOFormation.Count = GetNumberOfSGP4States("LEO_TLE.tle");


Note that a Formation's count can also be set during its initial creation, as shown below:


// Initialize a Formation with 12 Spacecraft:

Formation myFormation[12];


The number of elements in a Formation can be increased or decreased at any time by changing the value of the Formation.Count. You can also use the Formation.Clear() method to reset the Formation back to empty. To remove individual elements from a Formation, use the Formation.RemoveAt() method, as shown below:


// Decrease the number of elements in a Formation:

LEOFormation.Count = 3;


// Remove the first element from a Formation:



// Remove all elements from a Formation:



Note: When you remove elements from a Formation, the removed Spacecraft objects will continue to exist in memory if there were any other references to those objects. The Spacecraft will be removed from the Formation, but it will only be cleared completely from memory if the Formation was the only thing that held a reference to that Spacecraft. References can be created in various ways, such as by the using reference assignment operator (:=), or by displaying the object in output views (e.g. the View command). References are also held when you use methods with state - you can call the ResetMethodStates() method on the Spacecraft before clearing it from the Formation to remove those references. References are also held when you use the Save command; those references can be released by calling Object.ClearSavedStates().



Editing a Formation

As mentioned above, the Formation object allows access to additional properties and methods for visualization and data input. These are:


Formation.ViewAsGroup - This property determines whether the Formation will be visualized as a group within the Mission View, or as individual Spacecraft. Set this property to 0 in order to draw each Spacecraft with its specified 3D model and tail history. Set to 1 to draw each Spacecraft in the Formation as a point. Performance is significantly enhanced when the Formation is viewed as a group.


Formation.GroupPointSize - When ViewAsGroup is enabled, this property determines the size of points drawn for each Spacecraft in the Formation.


Formation.LoadTLE - This method populates the Spacecraft object with all the states in a TLE file. The method returns the number of states loaded.


LEOFormation.ViewAsGroup = 1;

LEOFormation.GroupPointSize = 2;



myFormation.ViewAsGroup = 0;

myFormation.GroupPointSize = 8;


Once the Count is set, you can begin to edit the properties of the individual Formation elements. You can do this individually for each element, or use a For loop to set properties for all elements at once.


// Edit one element at a time

myFormation[0].A = 9000;

myFormation[0].E = 0.2;

myFormation[0].I = 30;



// Edit all elements at once using a For loop

Variable i;

For i = 0 to myFormation.Count-1;


     myFormation[i].A = 9000;

     myFormation[i].E = 0.2;

     myFormation[i].I = 30;

     myFormation[i].RAAN = 30*i;




You can also use reference assignment (the := operator) to configure a Spacecraft object contained within a Formation to refer to another Spacecraft object that you created separately. This will cause any references to that Formation element to refer to the specified Spacecraft object. The example below demonstrates using reference assignment with a Spacecraft contained in a Formation:


Spacecraft LEO;


// Any references to myFormation[0] will now point to the LEO Spacecraft object

myFormation[0] := LEO;


Setting the Propagator

All Spacecraft in a Formation or List of Spacecraft are created using the default Propagator and ForceModel. The default Propagator is the highest fidelity Propagator available with your license level. For example, with the Mission license, all Formation elements are created with an RK89 Propagator.


The properties of the Propagator of a Spacecraft within a Formation or List can be accessed through syntax such as:


(myFormation[i].Propagator AsType RK89).Tolerance = 1e-9;


To override the default Propagator with another type of Propagator, such as an Ephemeris, use the SetPropagatorType method, as shown below. See the Working with Integrators or Working with Ephemerides chapters for more information.



(myFormation[i].Propagator AsType Ephemeris).LoadEphemeris("SampleEphemeris.ephem");


To set the attitude motion model for an element of a Formation, use the SetAttitudeMotionModel method:






Propagating and Maneuvering Formations

One of the primary advantages of using Lists and Formations is the capability to Step the entire constellation forward in time with a single command. This ensures that each Spacecraft in the List or Formation is synched at the same epoch, and is much less cumbersome that stepping each Spacecraft individually.


// Step the whole Formation

Step myFormation;


// Step the Formation in a While Loop

While (myFormation[0].ElapsedTime < TIMESPAN(1 days));

     View myFormation;

     Step myFormation;



You can also step an individual element of the List or Formation. This could be useful if you want to Maneuver one Spacecraft in the constellation using a FiniteBurn, and the step the remaining Spacecraft to the new epoch. Of course, in order to maneuver using a finite burn, Tanks and Thrusters must be configured as well.


// Create and Attach Tank and Thruster to myFormation[0]

Create Thruster Thruster1;

Create SphericalTank SphericalTank1;


Attach Thruster1 to myFormation[0];

Attach SphericalTank1 to myFormation[0];

Attach SphericalTank1 to Thruster1;


// Maneuver and Step individual elements of the List

Maneuver myFormation[0] using FiniteBurn1;


// Step the Formation to the maximum epoch contained within the Formation



Note: Similar to stepping the Spacecraft object, the Formation.Step() method can also be used in place of a Step command.



Output and Visualization

Formations can be visualized using the View and Map commands as well as the ViewWindow object. The example below shows how to create two output views of the Formation created in the examples above. This could be constructed using FreeFlyer script or the command editors.


While (myFormation[0].ElapsedTime < TIMESPAN(1 days));

     View myFormation;

     Map myFormation;

     Step myFormation;



3D View of myFormation when viewed as a Group

3D View of myFormation when viewed as a Group


3D View of myFormation when not viewed as a Group

3D View of myFormation when not viewed as a Group



See Also

Formation Properties and Methods

List<Object> Properties and Methods