hongshaorou/openrocket
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #2503 from JoePfeiffer/update-extension-documentation

Browse Source 
Update simulation extensions documentation to reflect switch to gradle
This commit is contained in:
Sibo Van Gool 2024-07-09 23:40:17 +02:00 committed by GitHub
commit 47b6fa273b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 141 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
core/src-extra/AirStart.java
View File

@ -1,21 +0,0 @@
import info.openrocket.core.simulation.SimulationStatus;
import info.openrocket.core.simulation.exception.SimulationException;
import info.openrocket.core.simulation.listeners.AbstractSimulationListener;
import info.openrocket.core.util.Coordinate;
/**
* Simulation listener that launches a rocket from a specific altitude.
*/
public class AirStart extends AbstractSimulationListener {
/** Launch altitude */
private static final double ALTITUDE = 1000.0;
@Override
public void startSimulation(SimulationStatus status) throws SimulationException {
Coordinate position = status.getRocketPosition();
position = position.add(0, 0, ALTITUDE);
status.setRocketPosition(position);
}
}

243
docs/source/user_guide/simulation_extensions.rst
View File

@ -80,15 +80,18 @@ we need to talk about the simulation status, flight data, and simulation listene
Simulation Status Simulation Status
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
As a simulation proceeds, it maintains its state in a `SimulationStatus`. The `SimulationStatus` object contains As a simulation proceeds, it maintains its state in a
information about the rocket's current position, orientation, velocity, and simulation state. It also contains a `SimulationStatus` object. This object contains
reference to a copy of the rocket design and its configuration. Any simulation listener method may modify the state of information about the rocket's current position, orientation,
velocity, simulation state, and the simulation's event queue. It also contains a
reference to a copy of the rocket design and its configuration. Any
simulation listener method (see below) may modify the state of
the rocket by changing the properties of the `SimulationStatus` object. the rocket by changing the properties of the `SimulationStatus` object.
You can obtain current information regarding the state of the simulation by calling `get*()` methods. For instance, the You can obtain current information regarding the state of the simulation by calling `get*()` methods. For instance, the
rocket's current position is returned by calling `getRocketPosition()`; the rocket's position can be changed by calling rocket's current position is returned by calling `getRocketPosition()`; the rocket's position can be changed by calling
`setRocketPosition<Coordinate position>`. All of the `get*()` and `set*()` methods can be found in `setRocketPosition(Coordinate position)`. All of the `get*()` and `set*()` methods can be found in
:file:`code/src/net/sf/openrocket/simulation/SimulationStatus.java`. Note that while some information can be obtained in :file:`core/src/main/java/info/openrocket/core/simulation/SimulationStatus.java`. Note that while some information can be obtained in
this way, it is not as complete as that found in `FlightData` and `FlightDataBranch` objects. this way, it is not as complete as that found in `FlightData` and `FlightDataBranch` objects.
Flight Data Flight Data
@ -97,7 +100,7 @@ Flight Data
OpenRocket refers to simulation variables as `FlightDataType`s, which are `List<Double>` objects with one list for each OpenRocket refers to simulation variables as `FlightDataType`s, which are `List<Double>` objects with one list for each
simulation variable and one element in the list for each time step. To obtain a `FlightDataType`, for example the current simulation variable and one element in the list for each time step. To obtain a `FlightDataType`, for example the current
motor mass, from `flightData`, we call `flightData.get(FlightDataType.TYPE_MOTOR_MASS)`. The standard `FlightDataType` motor mass, from `flightData`, we call `flightData.get(FlightDataType.TYPE_MOTOR_MASS)`. The standard `FlightDataType`
lists are all created in `core/src/net/sf/openrocket/simulation/FlightDataType.java`; the mechanism for creating a new lists are all created in `core/src/main/java/info/openrocket/core/simulation/FlightDataType.java`; the mechanism for creating a new
`FlightDataType` if needed for your extension will be described later. `FlightDataType` if needed for your extension will be described later.
Data from the current simulation step can be obtained with e.g. `flightData.getLast(FlightDataType.TYPE_MOTOR_MASS)`. Data from the current simulation step can be obtained with e.g. `flightData.getLast(FlightDataType.TYPE_MOTOR_MASS)`.
@ -105,7 +108,7 @@ Data from the current simulation step can be obtained with e.g. `flightData.getL
The simulation data for each stage of the rocket's flight is referred to as a `FlightDataBranch`. Every simulation has The simulation data for each stage of the rocket's flight is referred to as a `FlightDataBranch`. Every simulation has
at least one `FlightDataBranch` for its sustainer, and will have additional branches for its boosters. at least one `FlightDataBranch` for its sustainer, and will have additional branches for its boosters.
Finally, the collection of all of the `FlightDataBranch`es and some summary data for the simulation is stored in a Finally, the collection of all of the `FlightDataBranch` es and some summary data for the simulation is stored in a
`FlightData` object. `FlightData` object.
Flight Conditions Flight Conditions
@ -137,7 +140,7 @@ This method is called when the simulation is first started. It obtains the desir
configuration, and inserts them into the simulation status to simulate an air-start. configuration, and inserts them into the simulation status to simulate an air-start.
The full set of listener methods, with documentation regarding when they are called, can be found in The full set of listener methods, with documentation regarding when they are called, can be found in
:file:`core/src/net/sf/openrocket/simulation/listeners/AbstractSimulationListener.java`. :file:`core/src/main/java/info/openrocket/core/simulation/listeners/AbstractSimulationListener.java`.
The listener methods can have three return value types: The listener methods can have three return value types:
@ -153,7 +156,8 @@ The listener methods can have three return value types:
Every listener receives a ``SimulationStatus`` (see above) object as the first argument, and may also have additional arguments. Every listener receives a ``SimulationStatus`` (see above) object as the first argument, and may also have additional arguments.
Each listener method may also throw a ``SimulationException``. This is considered an error during simulation (not a bug), Each listener method may also throw a ``SimulationException``. This is
considered an error during simulation (not a program bug),
and an error dialog is displayed to the user with the exception message. The simulation data produced thus far is not and an error dialog is displayed to the user with the exception message. The simulation data produced thus far is not
stored in the simulation. Throwing a ``RuntimeException`` is considered a bug in the software and will result in a bug report dialog. stored in the simulation. Throwing a ``RuntimeException`` is considered a bug in the software and will result in a bug report dialog.
@ -184,100 +188,104 @@ You can either create your extension outside the source tree and make sure it is
classpath when OpenRocket is executed, or you can insert it in the source tree and compile it along with OpenRocket. classpath when OpenRocket is executed, or you can insert it in the source tree and compile it along with OpenRocket.
Since all of OpenRocket's code is freely available, and reading the code for the existing extensions will be very helpful Since all of OpenRocket's code is freely available, and reading the code for the existing extensions will be very helpful
in writing your own, the easiest approach is to simply insert it in the source tree. If you select this option, a very in writing your own, the easiest approach is to simply insert it in the source tree. If you select this option, a very
logical place to put your extension is in: logical place to put your extension is in :file:`core/src/main/java/info/openrocket/core/simulation/extension/`
.. code-block:: java The extension examples provided with OpenRocket are located in a
subdirectory of this named :file:`example/`.
core/src/net/sf/openrocket/simulation/extension/example/ Your configurator, if any, will logically go in :file:`swing/src/main/java/info/openrocket/swing/simulation/extension/`
This is where the extension examples provided with OpenRocket are located. Your configurator, if any, will logically go in: Configurators for the example extensions are located in a subdirectory
of this named :file:`example/`.
.. code-block:: java
swing/src/net/sf/openrocket/simulation/extension/example/
Extension Example Extension Example
----------------- -----------------
To make things concrete, we'll start by creating a simple example extension, to air-start a rocket from a hard-coded altitude. To make things concrete, we'll start by creating a simple example extension, to air-start a rocket from a hard-coded altitude.
Later, we'll add a configurator to the extension so we can set the launch altitude through a GUI at runtime. This is a Later, we'll add a configurator to the extension so we can set the launch altitude through a GUI at runtime. This is a
simplified version of the ``AirStart`` extension located in the OpenRocket source code tree; that class also sets a simplified version of the ``AirStart`` extension included in the extension
start velocity. ``example`` directory in the OpenRocket source code tree (that extension also sets a
start velocity).
.. code-block:: java .. code-block:: java
:linenos:
package net.sf.openrocket.simulation.extension.example; package info.openrocket.core.simulation.extension;
import net.sf.openrocket.simulation.SimulationStatus; import info.openrocket.core.simulation.SimulationConditions;
import net.sf.openrocket.simulation.exception.SimulationException; import info.openrocket.core.simulation.SimulationStatus;
import net.sf.openrocket.simulation.extension.AbstractSimulationExtension; import info.openrocket.core.simulation.exception.SimulationException;
import net.sf.openrocket.simulation.listeners.AbstractSimulationListener; import info.openrocket.core.simulation.extension.AbstractSimulationExtension;
import net.sf.openrocket.util.Coordinate; import info.openrocket.core.simulation.listeners.AbstractSimulationListener;
import info.openrocket.core.util.Coordinate;
/** /**
* Simulation extension that launches a rocket from a specific altitude. * Simulation extension that launches a rocket from a specific altitude.
*/ */
public class AirStartExample extends AbstractSimulationExtension { public class AirStartExample extends AbstractSimulationExtension {
public void initialize(SimulationConditions conditions) throws SimulationException { public void initialize(SimulationConditions conditions) throws SimulationException {
conditions.getSimulationListenerList().add(new AirStartListener()); conditions.getSimulationListenerList().add(new AirStartListener());
} }
@Override @Override
public String getName() { public String getName() {
return "Air-Start Example"; return "Air-Start Example";
} }
@Override @Override
public String getDescription() { public String getDescription() {
return "Simple extension example for air-start"; return "Simple extension example for air-start";
} }
private class AirStartListener extends AbstractSimulationListener { private class AirStartListener extends AbstractSimulationListener {
@Override @Override
public void startSimulation(SimulationStatus status) throws SimulationException { public void startSimulation(SimulationStatus status) throws SimulationException {
status.setRocketPosition(new Coordinate(0, 0, 1000.0)); status.setRocketPosition(new Coordinate(0, 0, 1000.0));
} }
} }
} }
There are several important features in this example: There are several important features in this example:
* The ``initialize()`` method in lines 14-16, which adds the listener to the simulation's ``List`` of listeners. This is the * The ``initialize()`` method in lines 15-17, which adds the listener to the simulation. This is the
only method that is required to be defined in your extension. only method that is actually required to be defined in your
* The ``getName()`` method in lines 19-21, which provides the extension's name. A default ``getName()`` is provided by extension, though any real extension (including this example) will
almost certainly have more.
* The ``getName()`` method in lines 19-22, which provides the extension's name. A default ``getName()`` is provided by
``AbstractSimulationExtension``, which simply uses the classname (so for this example, ``getName()`` would have returned ``AbstractSimulationExtension``, which simply uses the classname (so for this example, ``getName()`` would have returned
``"AirStartExample"`` if this method hadn't overridden it). ``"AirStartExample"`` if this method hadn't overridden it).
* The ``getDescription()`` method in lines 24-26, which provides a brief description of the purpose of the extension. * The ``getDescription()`` method in lines 24-27, which provides a brief description of the purpose of the extension.
This is the method that provides the text for the :guilabel:`Info` button dialog shown in the first section of this page. This is the method that provides the text for the :guilabel:`Info` button dialog shown in the first section of this page.
* The listener itself in lines 28-34, which provides a single ``startSimulation()`` method. When the simulation starts * The listener itself in lines 29-35, which provides a single ``startSimulation()`` method. When the simulation starts
executing, this listener is called, and the rocket is set to an altitude of 1000 meters. executing, this listener is called, and the rocket is set to an altitude of 1000 meters.
This will create the extension when it's compiled, but it won't put it in the simulation extension menu. To be able to This will create the extension when it's compiled, but it won't put it in the simulation extension menu. To be able to
actually use it, we need a provider, like this: actually use it, we need a provider, like this:
.. code-block:: java .. code-block:: java
:linenos:
package net.sf.openrocket.simulation.extension.example; import info.openrocket.core.plugin.Plugin;
import info.openrocket.core.simulation.extension.AbstractSimulationExtensionProvider;
import net.sf.openrocket.plugin.Plugin; @Plugin
import net.sf.openrocket.simulation.extension.AbstractSimulationExtensionProvider; public class AirStartExampleProvider extends AbstractSimulationExtensionProvider {
public AirStartExampleProvider() {
super(AirStartExample.class, "Launch conditions", "Air-start example");
}
}
@Plugin This class adds your extension to the extension menu with the
public class AirStartExampleProvider extends AbstractSimulationExtensionProvider { ``super`` call in line 7. The first parameter (``"Launch Conditions"``) is the first menu level,
public AirStartExampleProvider() {
super(AirStartExample.class, "Launch conditions", "Air-start example");
}
}
This class adds your extension to the extension menu. The first ``String`` (``"Launch Conditions"``) is the first menu level,
while the second (``"Air-start example"``) is the actual menu entry. These strings can be anything you want; using a while the second (``"Air-start example"``) is the actual menu entry. These strings can be anything you want; using a
first level entry that didn't previously exist will add it to the first level menu. first level entry that didn't previously exist will add it to the first level menu.
Try it! Putting the extension in a file named :file:`core/src/net/sf/openrocket/simulation/extensions/example/AirStartExample.java` Try it! Putting the extension in a file named :file:`core/src/main/java/info/openrocket/core/simulation/extension/AirStartExample.java`
and the provider in :file:`core/src/net/sf/openrocket/simulation/extensions/example/AirStartExampleProvider.java`, compiling, and the provider in
and running will give you a new entry in the extensions menu; adding it to the simulation will cause your simulation to :file:`core/src/main/java/info/openrocket/core/simulation/extension/AirStartExampleProvider.java`,
and compiling, and running OpenRocket will give you a new entry in the extensions menu; adding it to the simulation will cause your simulation to
start at an altitude of 1000 meters. start at an altitude of 1000 meters.
Adding a Configurator Adding a Configurator
@ -287,33 +295,35 @@ To be able to configure the extension at runtime, we need to write a configurato
communicate with the extension. First, we'll modify the extension as follows: communicate with the extension. First, we'll modify the extension as follows:
.. code-block:: java .. code-block:: java
:linenos:
package net.sf.openrocket.simulation.extension.example; package info.openrocket.core.simulation.extension;
import net.sf.openrocket.simulation.SimulationStatus; import info.openrocket.core.simulation.SimulationConditions;
import net.sf.openrocket.simulation.exception.SimulationException; import info.openrocket.core.simulation.SimulationStatus;
import net.sf.openrocket.simulation.extension.AbstractSimulationExtension; import info.openrocket.core.simulation.exception.SimulationException;
import net.sf.openrocket.simulation.listeners.AbstractSimulationListener; import info.openrocket.core.simulation.extension.AbstractSimulationExtension;
import net.sf.openrocket.util.Coordinate; import info.openrocket.core.simulation.listeners.AbstractSimulationListener;
import info.openrocket.core.util.Coordinate;
/** /**
* Simulation extension that launches a rocket from a specific altitude. * Simulation extension that launches a rocket from a specific altitude.
*/ */
public class AirStartExample extends AbstractSimulationExtension { public class AirStartExample extends AbstractSimulationExtension {
public void initialize(SimulationConditions conditions) throws SimulationException { public void initialize(SimulationConditions conditions) throws SimulationException {
conditions.getSimulationListenerList().add(new AirStartListener()); conditions.getSimulationListenerList().add(new AirStartListener());
} }
@Override @Override
public String getName() { public String getName() {
return "Air-Start Example"; return "Air-Start Example";
} }
@Override @Override
public String getDescription() { public String getDescription() {
return "Simple extension example for air-start"; return "Simple extension example for air-start";
} }
public double getLaunchAltitude() { public double getLaunchAltitude() {
return config.getDouble("launchAltitude", 1000.0); return config.getDouble("launchAltitude", 1000.0);
@ -324,19 +334,19 @@ communicate with the extension. First, we'll modify the extension as follows:
fireChangeEvent(); fireChangeEvent();
} }
private class AirStartListener extends AbstractSimulationListener { private class AirStartListener extends AbstractSimulationListener {
@Override @Override
public void startSimulation(SimulationStatus status) throws SimulationException { public void startSimulation(SimulationStatus status) throws SimulationException {
status.setRocketPosition(new Coordinate(0, 0, getLaunchAltitude())); status.setRocketPosition(new Coordinate(0, 0, getLaunchAltitude()));
} }
} }
} }
This adds two methods to the extension (``getLaunchAltitude()`` and ``setLaunchAltitude()``), and calls ``getLaunchAltitude()`` This adds two methods to the extension (``getLaunchAltitude()`` and ``setLaunchAltitude()``), and calls ``getLaunchAltitude()``
from within the listener to obtain the configured launch altitude. ``config`` is a ``Config`` object, provided by from within the listener to obtain the configured launch altitude. ``config`` is a ``Config`` object, provided by
``AbstractSimulationExtension`` (so it isn't necessary to call a constructor yourself). ``AbstractSimulationExtension`` (so it isn't necessary to call a constructor yourself).
:file:`core/src/net/sf/openrocket/util/Config.java` includes methods to interact with a configurator, allowing the :file:`core/src/main/java/info/openrocket/core/util/Config.java` includes methods to interact with a configurator, allowing the
extension to obtain ``double``, ``string``, and other configuration values. extension to obtain ``double``, ``string``, and other configuration values.
In this case, we'll only be defining a single configuration field in our configurator, ``"launchAltitude"``. In this case, we'll only be defining a single configuration field in our configurator, ``"launchAltitude"``.
@ -352,32 +362,34 @@ assures that the changes we make to the air-start altitude are propagated throug
The configurator itself looks like this: The configurator itself looks like this:
.. code-block:: java .. code-block:: java
:linenos:
package net.sf.openrocket.simulation.extension.example; package info.openrocket.swing.simulation.extension;
import javax.swing.JComponent; import javax.swing.JComponent;
import javax.swing.JLabel; import javax.swing.JLabel;
import javax.swing.JPanel; import javax.swing.JPanel;
import javax.swing.JSpinner; import javax.swing.JSpinner;
import net.sf.openrocket.document.Simulation; import info.openrocket.core.document.Simulation;
import net.sf.openrocket.gui.SpinnerEditor; import info.openrocket.core.simulation.extension.AirStartExample;
import net.sf.openrocket.gui.adaptors.DoubleModel; import info.openrocket.swing.gui.SpinnerEditor;
import net.sf.openrocket.gui.components.BasicSlider; import info.openrocket.swing.gui.adaptors.DoubleModel;
import net.sf.openrocket.gui.components.UnitSelector; import info.openrocket.swing.gui.components.BasicSlider;
import net.sf.openrocket.plugin.Plugin; import info.openrocket.swing.gui.components.UnitSelector;
import net.sf.openrocket.simulation.extension.AbstractSwingSimulationExtensionConfigurator; import info.openrocket.core.plugin.Plugin;
import net.sf.openrocket.unit.UnitGroup; import info.openrocket.swing.simulation.extension.AbstractSwingSimulationExtensionConfigurator;
import info.openrocket.core.unit.UnitGroup;
@Plugin @Plugin
public class AirStartConfigurator extends AbstractSwingSimulationExtensionConfigurator<AirStart> { public class AirStartExampleConfigurator extends AbstractSwingSimulationExtensionConfigurator<AirStartExample> {
public AirStartConfigurator() { public AirStartExampleConfigurator() {
super(AirStart.class); super(AirStartExample.class);
} }
@Override @Override
protected JComponent getConfigurationComponent(AirStart extension, Simulation simulation, JPanel panel) { protected JComponent getConfigurationComponent(AirStartExample extension, Simulation simulation, JPanel panel) {
panel.add(new JLabel("Launch altitude:")); panel.add(new JLabel("Launch altitude:"));
DoubleModel m = new DoubleModel(extension, "LaunchAltitude", UnitGroup.UNITS_DISTANCE, 0); DoubleModel m = new DoubleModel(extension, "LaunchAltitude", UnitGroup.UNITS_DISTANCE, 0);
@ -396,15 +408,16 @@ The configurator itself looks like this:
} }
} }
After some boilerplate, this class creates a new ``DoubleModel`` to manage the air-start altitude. The most important things After some boilerplate, this class creates a new ``DoubleModel`` to
manage the air-start altitude (line 29). The most important things
to notice about the ``DoubleModel`` constructor are the parameters ``"LaunchAltitude"`` and ``UnitGroup.UNITS_DISTANCE``. to notice about the ``DoubleModel`` constructor are the parameters ``"LaunchAltitude"`` and ``UnitGroup.UNITS_DISTANCE``.
* ``"LaunchAltitude"`` is used by the system to synthesize calls to the ``getLaunchAltitude()`` and ``setLaunchAltitude()`` * ``"LaunchAltitude"`` is used by the system to synthesize calls to the ``getLaunchAltitude()`` and ``setLaunchAltitude()``
methods mentioned earlier. The name of the ``DoubleModel``, ``"LaunchAltitude"``, **MUST** match the names of the corresponding methods defined in ``AirStartExample`` above. The name of the ``DoubleModel``, ``"LaunchAltitude"``, **MUST** match the names of the corresponding
``set`` and ``get`` methods exactly. If they don't, there will be an exception at runtime when the user attempts to change the value. ``set`` and ``get`` methods exactly. If they don't, there will be an exception at runtime when the user attempts to change the value.
* ``UnitGroup.UNITS_DISTANCE`` specifies the unit group to be used by this ``DoubleModel``. OpenRocket uses SI (MKS) units internally, * ``UnitGroup.UNITS_DISTANCE`` specifies the unit group to be used by this ``DoubleModel``. OpenRocket uses SI (MKS) units internally,
but allows users to select the units they wish to use for their interface. Specifying a ``UnitGroup`` provides the conversions but allows users to select the units they wish to use for their interface. Specifying a ``UnitGroup`` provides the conversions
and unit displays for the interface. The available ``UnitGroup`` options are defined in :file:`core/src/net/sf/openrocket/unit/UnitGroup.java`. and unit displays for the interface. The available ``UnitGroup`` options are defined in :file:`core/src/main/java/info/openrocket/core/unit/UnitGroup.java`
The remaining code in this method creates a ``JSpinner``, a ``UnitSelector``, and a ``BasicSlider`` all referring to this ``DoubleModel``. The remaining code in this method creates a ``JSpinner``, a ``UnitSelector``, and a ``BasicSlider`` all referring to this ``DoubleModel``.
When the resulting configurator is displayed, it looks like this: When the resulting configurator is displayed, it looks like this:
@ -425,8 +438,8 @@ Example User Extensions Provided With OpenRocket
================================================ ================================================
Several examples of user extensions are provided in the OpenRocket source tree. As mentioned previously, the extensions Several examples of user extensions are provided in the OpenRocket source tree. As mentioned previously, the extensions
are all located in :file:`core/src/net/sf/openrocket/simulation/extension/example` and their configurators are all located are all located in :file:`core/src/main/java/info/openrocket/core/simulation/extension/example/` and their configurators are all located
in :file:`swing/src/net/sf/openrocket/simulation/extension/example`. Also recall that every extension has a corresponding in :file:`swing/src/main/java/info/openrocket/swing/simulation/extension/example/`. Also recall that every extension has a corresponding
provider. provider.
.. list-table:: .. list-table::
@ -453,7 +466,3 @@ provider.
* - Stop simulation at specified time or number of steps * - Stop simulation at specified time or number of steps
- `StopSimulation` - `StopSimulation`
- `StopSimulationConfigurator` - `StopSimulationConfigurator`
.. note::
Documentation for adding user-created simulation listeners, without making use of the full extension mechanism, is also
available at ``Simulation Listeners``.