diff --git a/.gitignore b/.gitignore index aae3fccce..38050b5fa 100644 --- a/.gitignore +++ b/.gitignore @@ -89,3 +89,6 @@ fabric.properties openrocket.log *.snap + +# Sphinx documentation +docs/build \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..3a7e5af64 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt + +sphinx: + configuration: docs/source/conf.py \ No newline at end of file diff --git a/README.md b/README.md index 8cd2580bb..4f99b5548 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ OpenRocket is a free, fully featured model rocket simulator that allows you to d [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) ![GitHub release](https://img.shields.io/github/release/openrocket/openrocket.svg) [![Github Releases (by release)](https://img.shields.io/github/downloads/openrocket/openrocket/latest/total.svg)](https://GitHub.com/openrocket/openrocket/releases/) +[![Read the Docs](https://readthedocs.org/projects/openrocket/badge/?version=latest)](https://openrocket.readthedocs.io/en/latest/) [![snap release](https://snapcraft.io/openrocket/badge.svg)](https://snapcraft.io/openrocket) ![Chocolatey release](https://img.shields.io/chocolatey/v/openrocket) @@ -36,16 +37,18 @@ OpenRocket is a free, fully featured model rocket simulator that allows you to d ... plus many more -πŸ“– Read more on [our website](https://openrocket.info/) or the [OpenRocket Wiki](http://wiki.openrocket.info). +πŸ“– Read more on [our website](https://openrocket.info/). ## πŸ’Ύ Installers You can find the OpenRocket installers [here](https://openrocket.info/downloads.html). -## πŸ“ Release Notes - Release notes are available on each [release's page](https://github.com/openrocket/openrocket/releases) or on [our website](https://openrocket.info/release_notes.html). +## πŸ“– Documentation + +You can find our documentation on [ReadTheDocs](https://openrocket.readthedocs.io/en/latest/). + ## πŸš€ Getting started The easiest way to get started is to open one of our in-program example designs: diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..2de6e3c90 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +## Building the docs +Install Sphinx and additional dependencies using pip, Python's package manager. Open your command line interface +inside the :file:`openrocket/docs` directory and run: +```bash +pip install -r requirements.txt +``` + +Build the docs by running in the `docs` directory: +```bash +make html +``` + +To clean your build (necessary when you change the theme or make other changes to the build configuration), run: +```bash +make clean +``` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..dc1312ab0 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..4985b4d60 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx +sphinx-rtd-theme +sphinx-rtd-dark-mode +sphinx_new_tab_link \ No newline at end of file diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 000000000..0a761bf1f --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,110 @@ +/* Change the ReadTheDocs theme */ +.wy-nav-content { + max-width: 65% !important; +} + +.wy-side-nav-search, .wy-nav-top { + background: #1d8be1; +} + +.wy-side-nav-search .logo { + max-width: 42% !important; +} + +.seealso .admonition-title { + background: #85898c !important; +} + +.seealso .admonition-title::before { + content: "\f064"; + margin-right: 0.5em; +} + +.seealso { + background: #eee !important; +} + +.tip .admonition-title::before { + content: "\f0eb"; + margin-right: 0.5em; +} + +.note .admonition-title::before { + content: "\f05a"; + margin-right: 0.5em; +} + +.warning .admonition-title::before { + content: "\f071"; + margin-right: 0.5em; +} + +.attention .admonition-title { + background: #e87f7a !important; +} + +.attention .admonition-title::before { + content: "\f0f3"; + margin-right: 0.5em; +} + +.attention { + background: #ffd6cc !important; +} + +.admonition-todo { + background: #f4ccff !important; +} + +.admonition-todo .admonition-title { + background: #ff33df !important; +} + +.hlist { + table-layout: fixed; /* Ensure equals spacing between columns */ +} + +/* Custom OpenRocket CSS */ + +.or-figclass { + text-align: center; +} + +.or-image-border img { + border: 1px solid #ccc; + padding: 3px; +} + +.clear-both { + clear: both; +} + +/* Custom cell classes */ +.or-table > thead > tr > th { + text-align: center; +} +.or-table > tbody > tr > td:has(.or-table-good) { + background-color: #7FFF7F !important; /* Green */ +} + +.or-table > tbody > tr > td:has(.or-table-okay) { + background-color: #FFFF7F !important; /* Yellow */ +} + +.or-table > tbody > tr > td:has(.or-table-poor) { + background-color: #ffac7f !important; /* Orange */ +} +.or-table-cell { + color: #2d2d2d; + margin: auto !important; + text-align: center; !important; +} + +.or-table > tbody > tr > td:has(.or-table-bad) { + background-color: #FF7F7F !important; /* Red */ +} + +/* Remove the bottom margin in line blocks in tables */ +.or-table-line-blocks .line-block { + margin-bottom: 0 !important; +} diff --git a/docs/source/_static/navbar-logo.png b/docs/source/_static/navbar-logo.png new file mode 100644 index 000000000..11576451b Binary files /dev/null and b/docs/source/_static/navbar-logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..af78096b3 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,102 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'OpenRocket' +copyright = '2024, OpenRocket team' +author = 'OpenRocket team' +github_url = 'https://github.com/openrocket/openrocket' + +# The full version, including alpha/beta/rc tags +release = '23.09' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.todo', + 'sphinx_new_tab_link', + 'sphinx_rtd_dark_mode', +] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# user starts in light mode +default_dark_mode = False + +# -- Options for todo extension ---------------------------------------------- + +# Show TODOs in the output +todo_include_todos = True + +# -- Options for ReadTheDocs ------------------------------------------------- + +html_theme_options = { + #'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard + #'analytics_anonymize_ip': False, + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'both', + 'style_external_links': True, + 'vcs_pageview_mode': '', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': False, + 'navigation_depth': 3, + 'includehidden': True, + 'titles_only': False +} + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +html_logo = "_static/navbar-logo.png" + +# Configure Sphinx to update the sidebar whenever the navigation data changes. +html_context = { + 'navigation_update': True +} + +html_css_files = [ + 'custom.css', +] + +# -- Substitutions ----------------------------------------------------------- +rst_prolog = """ +.. |java_vers| replace:: 17 +.. |br_no_pad| raw:: html + +
+""" diff --git a/docs/source/dev_guide/api_documentation.rst b/docs/source/dev_guide/api_documentation.rst new file mode 100644 index 000000000..bc9f1d087 --- /dev/null +++ b/docs/source/dev_guide/api_documentation.rst @@ -0,0 +1,4 @@ +***************** +API Documentation +***************** + diff --git a/docs/source/dev_guide/architecture.rst b/docs/source/dev_guide/architecture.rst new file mode 100644 index 000000000..53a49a9d2 --- /dev/null +++ b/docs/source/dev_guide/architecture.rst @@ -0,0 +1,110 @@ +*********************** +OpenRocket Architecture +*********************** + +This section describes the high-level architecture of OpenRocket, the important modules and their interactions, and the technology stack. +It is intended for developers who want to understand the structure of the code and how it works. + +.. contents:: Table of Contents + :depth: 2 + :local: + +---- + +Introduction +============ + +OpenRocket is a Java application that runs on the desktop. It is built using the Swing GUI toolkit. The choice of Java +was originally made because it is a platform-independent language, making it possible to run OpenRocket on Windows, macOS, and Linux. +While the popularity of Java has waned in recent years, it is still a good choice for desktop applications because of its +mature libraries and tools. Additionally, rewriting OpenRocket in another language would be a massive undertaking that is +not currently feasible given the size of the developer team. Of course, any suggestions and help in this area are welcome. + +OpenRocket is released under the GNU General Public License (GPL) version 3.0. This means that the source code is open and +available for anyone to use, modify, and distribute. The only major restriction is that any derivative works must also be +released under the GNU GPL. This ensures that the code remains open and free for everyone. So, no one can take the code and +sell it as a proprietary product. + +Java Platform Module System (JPMS) +================================== + +OpenRocket leverages the **Java Platform Module System** (**JPMS**) to enhance modularity, encapsulation, and maintainability. +JPMS allows OpenRocket to be organized into two distinct modules, the ``core`` module and the ``swing`` module, +each with its own well-defined boundaries and dependencies. + +Each module in OpenRocket is described by a `module-info.java` file located at the root of the module's source directory +(:file:`/src/main/java.module-info.java`). This file declares: + + * **Module Name:** A unique identifier for the module (e.g., `info.openrocket.core`, `info.openrocket.swing`). + * **Dependencies:** The modules that this module depends on to function correctly. For example, the `info.openrocket.swing` module depends on the `info.openrocket.core` module. + * **Exported Packages:** The packages within the module that are accessible to other modules. + * **Services:** The services provided or consumed by the module (if applicable). + +By embracing JPMS, OpenRocket gains several advantages: + + * **Strong Encapsulation:** Modules explicitly control what packages are exposed, preventing accidental access to internal implementation details. + * **Reliable Configuration:** The module system verifies dependencies at compile time and runtime, reducing the risk of missing or incompatible components. + * **Improved Maintainability:** Modules can be developed and tested independently, making it easier to understand, modify, and evolve the codebase. + * **Scalability:** The modular structure facilitates the addition of new features or the replacement of existing components without impacting the entire application. + + +Core Module +=========== + +The ``core`` module contains the core functionality of OpenRocket, such as the rocket simulation engine, the file format +parsers and writers, and the rocket design classes. This module is intended to be reusable and can be used in other +applications that need rocket simulation capabilities. + +Swing Module +============ + +The ``swing`` module contains the user interface of OpenRocket. It is built using the Swing GUI toolkit and provides a graphical +interface for designing rockets, running simulations, and viewing the results. This module depends on the core module +and uses its functionality to perform the simulations and display the results. + +Rocket Components +================= + + + +Aerodynamic Calculators and Simulators +====================================== + +Simulation Listeners +==================== + + +Component Database +================== + +Thrust Curves +============= + +:abbr:`OR (OpenRocket)` uses Thrustcurves.org for its thrustcurves/motors. + +Scripts +======= + +Plugins +======= + +File Format (.ork) +================== + +The OpenRocket native format uses the file extension \*.ork. It is an XML format file combined with any needed graphics +files, contained in a ZIP archive. The extension \*.ork.gz is also accepted by OpenRocket, though plain .ork is recommended. +In other to view the contents of the file, you can simply rename the file extension to .zip and extract the contents. + + +The ``version`` attribute of the tag describes the file format version used, while the ``creator`` +attribute *may* describe the software and version used to write the document. The file format version is increased +every time the format is changed. The minor number is increased when changes are made that are mostly backward-compatible, +meaning that older software versions should be able to read the design sans the new features. The major number is +increased when changes are made that render the design problematic or impossible to read for older software. For maximum +compatibility software should save a file in the oldest file format version that supports all the necessary design features. + +For an overview of the changes between file format versions, see the `fileformat.txt `_ +file in the root directory of the repository. + + + diff --git a/docs/source/dev_guide/building_releasing.rst b/docs/source/dev_guide/building_releasing.rst new file mode 100644 index 000000000..7f6bee3cb --- /dev/null +++ b/docs/source/dev_guide/building_releasing.rst @@ -0,0 +1,287 @@ +********************** +Building and Releasing +********************** + +This guide explains the build system of OpenRocket (Gradle), and how to release a new version of OpenRocket. + +.. contents:: Table of Contents + :depth: 2 + :local: + +---- + +Gradle +====== + +`Gradle `__ is the build system for OpenRocket. It is used to compile the source code, run tests, and create the JAR file. +Key features of Gradle are: + +- **Incremental builds**: Gradle only rebuilds what is necessary, which makes the build process faster. + +- **Dependency management**: Gradle has a robust dependency management system capable of handling project and third-party libraries. + +- **Performance**: Gradle uses techniques like build caching and parallel execution to improve performance of the build process. + +The root directory of the OpenRocket repository contains several Gradle files: + +- ``build.gradle``: This is the main build script file where you define your project configuration and tasks such as compile and run tasks, dependency management, plugins usage, and more. + +- ``settings.gradle``: Used for multi-project build configurations to include which sub-projects should be part of the build. + For OpenRocket, this file is used to identify the ``core`` and ``swing`` sub-projects. + +- ``gradle.properties``: Contains project-wide properties that can be accessed from the build script. For example, the version number of OpenRocket can be defined here. + +- ``gradlew`` and ``gradlew.bat``: These are Gradle Wrapper scripts for Unix-based and Windows systems respectively. + It allows users to run Gradle builds without requiring Gradle to be installed on the system. + +The ``core`` and ``swing`` sub-projects contain their own ``build.gradle`` and ``gradle.properties`` files that define the tasks specific to those sub-projects. + +Gradle in IntelliJ +------------------ + +If you use IntelliJ IDEA, you can access the Gradle tasks within the IDE. First, open the Gradle tool window by going to +:menuselection:`View --> Tool Windows --> Gradle` or by clicking on the Gradle icon in the right-hand side of the window: + +.. figure:: /img/dev_guide/building_releasing/gradle_in_intellij.png + :align: center + :width: 80% + :alt: Opening the Gradle tool window in IntelliJ IDEA. + + Opening the Gradle tool window in IntelliJ IDEA. + +This shows the following window: + +.. figure:: /img/dev_guide/building_releasing/intellij_gradle_window.png + :align: center + :width: 30% + :alt: The Gradle tool window in IntelliJ IDEA. + + The Gradle tool window in IntelliJ IDEA. + +Here's a breakdown of the Gradle tasks: + +- *info.openrocket*: the root project + - *Tasks*: Gradle tasks specific to the root project. + - *application*: Contains tasks related to running or debugging your application from within the IDE. + - *build*: Includes tasks for building the entire project. + - *build setup*: Tasks for initializing a new Gradle build, such as creating new Gradle files. + - *distribution*: Tasks for assembling the application distribution, like creating zips or tarballs of the build outputs. + - *documentation*: Tasks for generating documentation, typically using tools like Javadoc. + - *help*: Provides tasks that list other tasks or project properties. + - *info.openrocket*: Custom tasks specific to the 'info.openrocket' module. + - *other*: Any other tasks that do not fit into the predefined categories. + - *shadow*: Related to the Shadow plugin, which packages the project’s artifacts along with its dependencies into a single "fat" JAR. + - *verification*: Tasks for testing and verifying the project, such as running unit tests. + - *Dependencies*: Lists the dependencies of the project. + - *Run Configurations*: Gradle run configurations that can be used in IntelliJ. +- *core*: the core module + - *Tasks*: Gradle tasks specific to the 'core' module. + - *Dependencies*: Lists the dependencies of the 'core' module. +- *swing*: the swing module + - *Tasks*: Gradle tasks specific to the 'swing' module. + - *Dependencies*: Lists the dependencies of the 'swing' module. + +Most Important Gradle Tasks +--------------------------- + +Here are some of the most important Gradle tasks for OpenRocket: + +.. list-table:: Most Important Gradle Tasks + :widths: 25 25 50 + :header-rows: 1 + + * - Module + - Task + - Description + + * - root (*info.openrocket*) + - ``clean`` + - Deletes the build directory and all its contents (basically cleans up the project). + + * - root (*info.openrocket*) + - ``run`` + - Runs the OpenRocket application. + + * - root (*info.openrocket*) + - ``check`` + - Runs the unit tests and checks the code quality using the Checkstyle static analysis tool. + + * - root (*info.openrocket*) + - ``build`` + - Compiles the source code, runs the unit tests, and creates the JAR file for the *core* and *swing* module. + + * - root (*info.openrocket*) + - ``dist`` + - Creates a distributable JAR file of OpenRocket (a combination of the *core* and *swing* JAR) at :file:`openrocket/build/libs/OpenRocket-.jar`. + + * - core + - ``serializeEngines`` + - Fetch the latest thrust curves from ThrustCurve.org and serialize them to the OpenRocket format. The resulting serialized file is saved in the ``src`` dir so it can be used for a build. + + * - core + - ``serializeEnginesDist`` + - Same as ``serializeEngines``, but loads the serialized file to the distribution directory (:file:`openrocket/build`) so it can be used in the final build. + + * - core + - ``submoduleUpdate`` + - Updates the submodule dependencies of the *core* module. + +You can run these tasks from the command line using the Gradle Wrapper scripts. For example for the task ``run``, run the +following command in the root directory of the OpenRocket repository: + +.. code-block:: bash + + # On macOS and Linux: + ./gradlew run + + # On Windows: + gradlew.bat run + +install4j +========= + +`install4j `__ is used to create the packaged installers for OpenRocket from the JAR file. +install4j generously provides a free license for open source projects, including OpenRocket. Currently, only the OpenRocket administrators have access +to the install4j license. + +Code Signing +------------ + +An important part of generating the installers is `code signing `__. +This is done to ensure that the installer is not tampered with between the time it is created and the time it is run by the user. +Once the OpenRocket installer has been code signed, users will receive no more (or the minimum amount of) warnings from +their operating system that the installer is from an unknown source and may contain malware. +More information on how to do code signing in install4j can be found `here `__. + +Only the OpenRocket administrators have access to the code signing certificates. + +Code signing for Windows is done using a digital certificate from Sectigo. More information on the code signing procedure, +including whitelisting OpenRocket by Microsoft, see the `README file on GitHub `__. + +For macOS, the code signing is done using an Apple Developer ID. Besides code signing, the OpenRocket app also needs to +be notarized. Luckily, install4j takes care of this. More information on the code signing procedure for macOS can be found in the +`README file on GitHub `__. + +Linux does not require code signing. + +Creating the Installers +----------------------- + +First you need to build the project using Gradle (see above). This will create the JAR file that will be used to create the installers. + +Then, open install4j (requires a license) and load the project file *openrocket/install4j//openrocket-.install4j* +from the repository. Go to the :menuselection:`Build` tab and click on the :guilabel:`Start Build` button. This will create the installers in +the *openrocket/install4j//media/* directory. + +.. figure:: /img/dev_guide/building_releasing/install4j_build.png + :align: center + :width: 80% + :alt: Building the installers in install4j. + + Building the installers in install4j. + +If you do not have access to the code signing certificates, you can create the installers without code signing by +enabling the checkboxes ``Disable code signing`` and ``Disable notarization`` in the ``Build`` tab. + +Release Procedure +================= + +The release procedure for OpenRocket is as follows: + +1. Update the `ReleaseNotes.md `__ with the changes that are part of the new release. + This includes new features, bug fixes, and other changes that are part of the release. Make sure to include the version number and the release date. + Take a look at the previous release notes to see how it should be formatted. + +2. Update the component database and thrustcurves by running the gradle tasks ``subModuleUpdate`` and ``serializeEnginesDist`` respectively. + +3. **Update the version number** in ``openrocket/core/src/main/resources/build.properties`` to the correct version number. + + For official releases, the version number should use the format ``YY.MM`` (*year.month*). For example, if the software is released in + September 2023, the version number should be ``23.09``. If there are multiple releases in the same month, add an incremental number + to the version number, e.g. ``23.09.01``. + + If a new release contains significant changes, it may be necessary to release alpha or beta versions first. In that case, the version + number should be appended with ``.alpha.`` or ``.beta.`` plus an incremental number. For example, if the software is in beta stage + in September 2023, the version number should be ``23.09.beta.01``. In general, alpha releases are not necessary. This is only for very rough releases. + Beta releases are only necessary if there are significant changes that need to be tested by the community before the final release. + + One final option is to release a release candidate (RC) version. This is a version that is considered to be the final version, + but needs to be tested by the community before the final release. The version number should be appended with ``.RC.`` plus an incremental number. + For example, if the software is in RC stage in September 2023, the version number should be ``23.09.RC.01``. + + The official release that comes after the beta release should have the same version number as the beta release, but without the ``.beta.`` part. + For instance, if the beta testing started in September 2023 with version number ``23.09.beta.01``, the final release should have version number ``23.09``, + even if the final release is in November 2023. This is to ensure consistency in the version numbering and to link the beta release(s) to the final release. + +4. **Build the project JAR file** using Gradle (see above). + +5. **Test the JAR file** to ensure that it works correctly and that the new version number is applied to the splash screen and under :menuselection:`Help --> About`. + +6. **Create the packaged installers** using install4j (see above). + + .. warning:: + Make sure to **enable code signing** for the installers. + + Make sure that `DS_Store `__ for the macOS + installer is updated. Instructions can be found `here `__. + +7. **Test the installers** to ensure that they work correctly. + +8. **Prepare the website** *(for official releases only, not for alpha, beta, or release candidate releases)*. + + The `source code for the website `__ needs to be updated to point to the new release. + Follow these steps: + + - Add the release to `downloads_config.json `__. + - Update the ``current_version`` in `_config `__. + - Add a new entry to `_whats_new `__ for the new release. + Create a ``wn-.md`` file with the changes that are part of the new release. Please take a close look to the previous entries to see how it should be formatted. + - Update the `release notes `__ + (which is a link to the What's new file that you just created). Again, take a close look at the previous entries to see how it should be formatted. + + .. warning:: + Make sure to **update the website on the** ``development`` **branch**. The ``master`` branch is the branch that is live + on the website. First update the ``development`` branch and test the changes on the website. In a later step, the + changes will be merged to the ``master`` branch. + +9. **Publish the release on GitHub**. + + Go to the `releases page `__. Click *Draft a new release*. + Select *Choose a tag* and enter a new tag name, following the format ``release-``, e.g. ``release-23.09``. + The title should follow the format ``OpenRocket ()``, e.g. ``OpenRocket 23.09 (2023-11-16)``. + + Fill in the release text, following the `ReleaseNotes.md `__. + If you want to credit the developers who contributed to the release, you can tag them anywhere in the release text using the `@username` syntax. + They will then be automatically displayed in the contributors list on the release page. + + Finally, upload all the packaged installers and the JAR file to the release. The source code (zip and tar.gz) is + automatically appended to each release, you do not need to upload it manually. + + If this is an alpha, beta, or release candidate release, tick the *Set as a pre-release* checkbox. + + Click *Publish release*. + +10. **Push the changes to the website** + + First, build the ``development`` branch locally to verify that the changes that you made in step 8 are correct. + If everything is working (test the download links, the release notes, and the What's new page), create a new PR + that merges the changes from the ``development`` branch to the ``master`` branch. + +11. **Send out the release announcement**. + + Send out the release announcement to the OpenRocket mailing list, the TRF forum, and the OpenRocket social media channels + (Discord, Facebook...). + + The announcement should include the new features, bug fixes, and other changes that are part of the new release. + Make sure to include the download links to the new release. Here is an `example announcement `__. + +12. **Merge the** ``unstable``` **branch to the** ``master``` **branch**. + + After the release is published, merge the changes from the `unstable `__ branch + to the `master `__ branch. + +13. **Upload the new release to** `SourceForge `__. + + The downloads page on SourceForge is still very actively used, so be sure to upload the new release there as well. + +14. **Update package managers** (e.g. snap, Chocolatey, Homebrew) with the new release. diff --git a/docs/source/dev_guide/codebase_walkthrough.rst b/docs/source/dev_guide/codebase_walkthrough.rst new file mode 100644 index 000000000..86c6a3b85 --- /dev/null +++ b/docs/source/dev_guide/codebase_walkthrough.rst @@ -0,0 +1,201 @@ +******************** +Codebase Walkthrough +******************** + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Important Modules and Packages +============================== + +Root Directory Structure +======================== + + + +Module Folder Structure +======================= + +OpenRocket uses the Gradle build system, where each modules (``info.openrocket.core`` and ``info.openrocket.swing``) adheres to the following folder structure: + +.. code-block:: none + + β”œβ”€β”€ gradle # Gradle Wrapper + β”œβ”€β”€ libs # (optional) Library JAR files that cannot be obtained from the gradle dependency system + β”œβ”€β”€ resources-src # Source files for the resources in the src dir (e.g. InkScape project file for the splash screen) + β”œβ”€β”€ scripts # Utility scripts + β”œβ”€β”€ src # Source code and resources + β”‚ β”œβ”€β”€ main # Application source code and resources + β”‚ β”‚ β”œβ”€β”€ java # Java source code + β”‚ β”‚ β”œβ”€β”€ resources # Resource files (e.g. images, configuration files, data files) + β”‚ β”œβ”€β”€ test # Test source code and resources + β”‚ β”‚ β”œβ”€β”€ java # Java test source code + β”‚ β”‚ β”œβ”€β”€ resources # Resource files for testing + β”œβ”€β”€ src-extra # Extra source code, not part of the main application (e.g. template code for an OpenRocket plugin) + +Core Module +----------- + +The following is an overview of the packages in the ``info.openrocket.core`` module (:file:`openrocket/core/src/main/java/info/openrocket/core`): + +.. code-block:: none + + β”œβ”€β”€ aerodynamics # Calculation of aerodynamic properties (e.g. aerodynamic forces, CD) + β”‚ └── barrowman # Barrowman method for calculating aerodynamic properties + β”œβ”€β”€ appearance # Appearance of components (e.g. color, texture) + β”‚ └── defaults # Default appearance settings + β”œβ”€β”€ arch # Get info on the system architecture (macOS, Windows, Linux) + β”œβ”€β”€ communication # Communication with external sites/programs (e.g. retrieve the latest version of OpenRocket from GitHub) + β”œβ”€β”€ database # Database handling (component database, motor database) + β”‚ └── motor # Thrust curve (i.e. motor) database + β”œβ”€β”€ document # OpenRocket document and simulation handling + β”‚ β”œβ”€β”€ attachments # Attachments to OpenRocket documents + β”‚ └── events # OpenRocket events (i.e. document changed, simulation changed) + β”œβ”€β”€ file # File handling + β”‚ β”œβ”€β”€ iterator # Iterate files in e.g. a directory or a zip file + β”‚ β”œβ”€β”€ motor # Motor files handling + β”‚ β”œβ”€β”€ openrocket # OpenRocket file handling + β”‚ β”‚ β”œβ”€β”€ importt # Import OpenRocket files + β”‚ β”‚ └── savers # Save OpenRocket files + β”‚ β”œβ”€β”€ rasaero # RASAero II file handling + β”‚ β”‚ β”œβ”€β”€ export # Export OpenRocket files to RASAero II + β”‚ β”‚ └── importt # Import RASAero II files to OpenRocket + β”‚ β”œβ”€β”€ rocksim # RockSim file handling + β”‚ β”‚ β”œβ”€β”€ export # Export OpenRocket files to RockSim + β”‚ β”‚ └── importt # Import RockSim files to OpenRocket + β”‚ β”œβ”€β”€ simplesax # XML file handling + β”‚ β”œβ”€β”€ svg # SVG file handling + β”‚ β”‚ └── export # SVG export + β”‚ └── wavefrontobj # Wavefront OBJ file handling + β”‚ └── export # Export OpenRocket components to Wavefront OBJ + β”‚ β”œβ”€β”€ components # Export OpenRocket components + β”‚ └── shapes # Export general geometry shapes + β”œβ”€β”€ formatting # Formatting of e.g. motor config names + β”œβ”€β”€ gui + β”‚ └── util # Filename filter + β”œβ”€β”€ l10n # Localization (translation of OpenRocket into languages other than English) + β”œβ”€β”€ logging # Errors, warnings, and aborts + β”œβ”€β”€ masscalc # Mass property (e.g. mass, CG, moments of inertia) calculation drivers. Actual component mass calculations are in the components themselves + β”œβ”€β”€ material # Material properties (physical properties of materials) + β”œβ”€β”€ models # Physical models (e.g. atmosphere, gravity, wind) + β”‚ β”œβ”€β”€ atmosphere # Atmosphere models + β”‚ β”œβ”€β”€ gravity # Gravity models + β”‚ └── wind # Wind models + β”œβ”€β”€ motor # Motor configuration, ID, and thrustcurves + β”œβ”€β”€ optimization # Optimization algorithms + β”‚ β”œβ”€β”€ general # Parameter search space algorithms + β”‚ β”‚ β”œβ”€β”€ multidim # Multidimensional parallel search optimization + β”‚ β”‚ └── onedim # One dimensional golden-section search optimization + β”‚ β”œβ”€β”€ rocketoptimization # Optimization of rocket parameters for specified goal functions + β”‚ β”‚ β”œβ”€β”€ domains # Limits on optimization parameters + β”‚ β”‚ β”œβ”€β”€ goals # Max, min, and specific value optimization goals + β”‚ β”‚ β”œβ”€β”€ modifiers # Modify rocket parameters + β”‚ β”‚ └── parameters # Simulation results that can be optimized + β”‚ └── services # Provide parameters etc to optimizer + β”œβ”€β”€ plugin # Plugin interface (more general but less developed than extension interface) + β”œβ”€β”€ preset # Component presets + β”‚ β”œβ”€β”€ loader # Component database file loader + β”‚ └── xml # Component database file writer + β”œβ”€β”€ rocketcomponent # Rocket components (e.g. fins, nose cone, tube) + β”‚ └── position # Position of rocket components + β”œβ”€β”€ rocketvisitors # Create lists of components and motors + β”œβ”€β”€ scripting # Javascript scripting of OR functionality + β”œβ”€β”€ simulation # Flight simulation code + β”‚ β”œβ”€β”€ customexpression # User defined custom expression handling + β”‚ β”œβ”€β”€ exception # Exceptions occurring during simulation + β”‚ β”œβ”€β”€ extension # User defined simulation extensions + β”‚ β”‚ β”œβ”€β”€ example # Examples of simulation extensions + β”‚ β”‚ └── impl # Helper methods for implementing extensions + β”‚ └── listeners # Code "listening" to simulation to implement functionality + β”‚ β”œβ”€β”€ example # Example user listeners + β”‚ └── system # Listeners used by OpenRocket itself + β”œβ”€β”€ startup # Root Application and related classes + β”œβ”€β”€ thrustcurve # Thrustcurve file and thrustcurve.org API + β”œβ”€β”€ unit # Definitions of units and unit conversions + β”œβ”€β”€ util # Miscellaneous utility methods + β”‚ └── enums # Conversion of enums to names + └── utils # More utility methods + + +Swing Module +------------ + +The following is an overview of the packages in the ``info.openrocket.swing`` module (*openrocket/swing/src/main/java/info/openrocket/swing*): + +.. code-block:: none + + β”œβ”€β”€ communication + β”œβ”€β”€ file + β”‚ β”œβ”€β”€ motor + β”‚ β”œβ”€β”€ photo + β”‚ └── wavefrontobj + β”œβ”€β”€ gui + β”‚ β”œβ”€β”€ adaptors + β”‚ β”œβ”€β”€ components + β”‚ β”‚ └── compass + β”‚ β”œβ”€β”€ configdialog + β”‚ β”œβ”€β”€ customexpression + β”‚ β”œβ”€β”€ dialogs + β”‚ β”‚ β”œβ”€β”€ flightconfiguration + β”‚ β”‚ β”œβ”€β”€ motor + β”‚ β”‚ β”‚ └── thrustcurve + β”‚ β”‚ β”œβ”€β”€ optimization + β”‚ β”‚ β”œβ”€β”€ preferences + β”‚ β”‚ └── preset + β”‚ β”œβ”€β”€ figure3d + β”‚ β”‚ β”œβ”€β”€ geometry + β”‚ β”‚ └── photo + β”‚ β”‚ β”œβ”€β”€ exhaust + β”‚ β”‚ └── sky + β”‚ β”‚ └── builtin + β”‚ β”œβ”€β”€ figureelements + β”‚ β”œβ”€β”€ help + β”‚ β”‚ └── tours + β”‚ β”œβ”€β”€ main + β”‚ β”‚ β”œβ”€β”€ componenttree + β”‚ β”‚ └── flightconfigpanel + β”‚ β”œβ”€β”€ plot + β”‚ β”œβ”€β”€ preset + β”‚ β”œβ”€β”€ print + β”‚ β”‚ β”œβ”€β”€ components + β”‚ β”‚ └── visitor + β”‚ β”œβ”€β”€ rocketfigure + β”‚ β”œβ”€β”€ scalefigure + β”‚ β”œβ”€β”€ simulation + β”‚ β”œβ”€β”€ theme + β”‚ β”œβ”€β”€ util + β”‚ β”œβ”€β”€ watcher + β”‚ └── widgets + β”œβ”€β”€ logging + β”œβ”€β”€ simulation + β”‚ └── extension + β”‚ β”œβ”€β”€ example + β”‚ └── impl + β”œβ”€β”€ startup + β”‚ β”œβ”€β”€ jij + β”‚ └── providers + └── utils + +Units used in OpenRocket +======================== + +OpenRocket always uses internally pure SI units. For example all rocket dimensions and flight distances are in meters, all +masses are in kilograms, density is in kg/mΒ³, temperature is in Kelvin etc. This convention is also used when storing the +design in the OpenRocket format. + +The only exception to this rule is angles: + +- Angles are represented as radians internally, but in the file format they are converted to degrees. This is to make + the file format more human-readable and to avoid rounding errors. + +- Latitude and longitude of the launch site are represented in degrees both internally and externally. + +When displaying measures to the user, the values are converted into the preferred units of the user. This is performed +using classes in the package ``info.openrocket.core.unit``. The ``Unit`` class represents a single unit and it includes methods for +converting between that unit and SI units in addition to creating a string representation with a suitable amount of decimals. +A ``UnitGroup`` describes a measurable quantity such as temperature and contains the units available for that quantity, +such as Celsius, Fahrenheit and Kelvin. diff --git a/docs/source/dev_guide/contributing_to_the_docs.rst b/docs/source/dev_guide/contributing_to_the_docs.rst new file mode 100644 index 000000000..43b77fc00 --- /dev/null +++ b/docs/source/dev_guide/contributing_to_the_docs.rst @@ -0,0 +1,399 @@ +********************************* +Contributing to the Documentation +********************************* + +This document explains how to contribute to the OpenRocket documentation. It provides information on why we use Sphinx +for our documentation, how to edit and build the documentation, and the style guide for writing documentation. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Why Sphinx? +=========== + +This documentation is generated using `Sphinx `__. Sphinx is a tool that makes it +easy to create intelligent and beautiful documentation. It is used by many open-source projects, including +`Python `__, `NumPy `__, and `Matplotlib `__. +Sphinx uses `reStructuredText `__ as its markup language, which is a lightweight markup language that is easy to read and write. Sphinx also supports `Markdown `__ and `LaTeX `__. + +Previously, OpenRocket used MediaWiki for its documentation, but we decided to switch to Sphinx for several reasons: + +- Sphinx is more powerful, modern, and flexible than MediaWiki. It allows us to create more complex and interactive documentation. + +- Sphinx is easier to maintain than MediaWiki. It is easier to update and manage the documentation in the source files. + +- Sphinx can give warnings and errors when building the documentation, which helps to catch mistakes and inconsistencies. + +- The documentation is hosted on our GitHub repository, together with the source code. This ensures all resources are concentrated, + makes it easier to keep the documentation in sync with the code, and allows for better version control. + +- Lastly, for some users who wanted to contribute to the MediaWiki documentation, their access to the MediaWiki was blocked. + We were never able to solve that issue. + +Read the Docs +------------- + +The OpenRocket documentation is hosted on `Read the Docs `__. Read the Docs is a popular +platform for hosting documentation for open-source projects. It automatically builds the documentation from the source +files in the OpenRocket repository and makes it available online. This makes it easy for users to access the documentation +and for contributors to update it. It also supports versioning, so you can view the documentation for different versions of +OpenRocket, and it has a search feature that allows you to quickly find what you are looking for. Additionally, you can also +add translations to the documentation, which makes it accessible to a wider audience. + +---- + +Editing and Building the Documentation +====================================== + +If you would like to contribute to the documentation, you can do so by editing the reStructuredText files in the +:file:`docs/source` directory of the OpenRocket repo. You can then build the documentation by first +`installing Sphinx `__ and some extra dependencies. +Open a new terminal window in the :file:`docs` directory and run the following command: + +.. code-block:: bash + + pip install -r requirements.txt + +To build the docs, run the following command from the ``docs`` directory: + +.. code-block:: bash + + make html + +This will generate the documentation in the :file:`docs/build/html` directory. You can then view the documentation by opening the +``index.html`` file in your web browser. + +To clean your build (necessary when you change the theme or make other changes to the build configuration), run: + +.. code-block:: bash + + make clean + + +If you would like to contribute to the documentation, please submit a pull request with your changes. If you are not sure how to +do this, please see the ``Obtaining the Source Code`` section in :doc:`Development Environment Setup `. +Also check out the `GitHub documentation `__ +on how to submit a pull request. If you don't want to go through the hassle of setting up a development environment, you can also +`submit an issue `__ with your proposed changes and we will take care of the rest, +or you can `contact us `__. + +---- + +Style Guide +=========== + +This section provides a style guide for writing documentation for OpenRocket. It covers conventions that we use in the docs +and useful tips for writing reStructuredText/Sphinx docs. + +.. _heading_levels: + +Heading levels +-------------- + +Normally, in reStructuredText, there are no heading levels assigned to certain characters as the structure is determined +from the succession of headings. However, we have set the following heading level rules for the documentation: + +- \# with overline, for parts *(not really used at the moment)* + +- \* with overline, for chapters + +- \= for sections + +- \- for subsections + +- \^ for subsubsections + +- \" for paragraphs + +Note that the overline and underline characters must be the same length as the text they are underlining. + +For example: + +.. code-block:: rst + + ***************************************** + H1: This is a chapter (title of the page) + ***************************************** + + H2: This is a section + ===================== + + H3: This is a subsection + ------------------------ + + H4: This is a subsubsection + ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + H5: This is a paragraph + """"""""""""""""""""""" + +Horizontal Rules +---------------- + +Horizontal rules are used to separate sections of the documentation. They are created using four or more hyphens (----). + +For example: + +.. code-block:: rst + + This is a section + ================= + + ---- + + This is another section + ======================= + +.. note:: + + As seen in the example, it is recommended to **always add a horizontal rule before starting a new section** + (H2, see :ref:`Heading levels `). + +Adding Images +------------- + +Images are added to the documentation like this: + +.. code-block:: rst + + .. figure:: /img/path/to/your/image.png + :width: 50% (please always express this as a percentage, and don't go over 95% width) + :align: "left", "center", or "right" ("center" should be used in general) + :alt: Alternative text + :figclass: or-image-border (optional, for custom styling) + + This is the caption of the image. + +Images are stored in the :file:`img` directory in the :file:`docs/source` directory. When adding images, please make sure +they are in the correct format (PNG, JPEG, or SVG) and that you place them in the correct directory. Use the same directory +structure as the rst source file that you want to include the image in. For example, if you want to include an image in +:file:`docs/source/user_guide/quick_start.rst`, place the image in :file:`docs/source/img/user_guide/quick_start/`. + +Just for fun, here is an image of my cat: + +.. figure:: /img/dev_guide/contributing_to_the_docs/Oscar.jpeg + :width: 50% + :align: center + :alt: A cute cat + :figclass: or-image-border + + This is a picture of my cat, Oscar. + +Hyperlinks +---------- + +Hyperlinks to external sites are created like this: + +.. code-block:: rst + + `link text `__ + +Replace ``link text`` with the text you want to display as the hyperlink, and ``www.your_url.com`` with the actual URL +of the hyperlink. For example: `Hey, I'm a link! `__. + +.. warning:: + + Always use a double underscore at the end. Don't use a single underscore, as this can cause issues when you have + multiple hyperlinks with the same text. + +Admonitions: Tip, Note, Warning, Attention, See also +---------------------------------------------------- + +As you saw just above, you can add notes and warnings to draw attention to important information. The following are +all the possible admonition type: "**attention**", "**caution**", "**danger**", "**error**", "**hint**", "**important**", +"**note**", "**tip**", "**warning**". More information can be found +`here `__. + +The most uses admonitions in the OpenRocket docs are: + +Tip +^^^ + +.. code-block:: rst + + .. tip:: + + This is a tip. + +.. tip:: + + This is what the tip looks like. + +Note +^^^^ + +.. code-block:: rst + + .. note:: + + This is a note. + +.. note:: + + This is what the note looks like. + +Warning +^^^^^^^ + +.. code-block:: rst + + .. warning:: + + This is a warning. + +.. warning:: + + This is what the warning looks like. + +Attention +^^^^^^^^^ + +.. code-block:: rst + + .. attention:: + + This is an attention. + +.. attention:: + + This is what a point of attention looks like. + +See Also +^^^^^^^^ + +.. code-block:: rst + + .. seealso:: + + This is a seealso. + +.. seealso:: + + See also the following page :doc:`Development Overview ` + +Semantic Markup +--------------- + +Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as \:rolename\:\`content\`. +More information can be found `here `__. What +this means is that you can add roles to pieces of text that have a specific meaning so that Sphinx renders that text +in an appropriate way. Below you find some of the most common roles used in the OpenRocket documentation: + +\:menuselection\: Role +^^^^^^^^^^^^^^^^^^^^^^ + +The ``:menuselection:`` role is used to represent a sequence of menu selections in a user interface. + +Example: + :menuselection:`File --> Open example` + +(Ensure you use the correct arrow character, which is ``-->``.) + +\:command\: Role +^^^^^^^^^^^^^^^^ + +The ``:command:`` role is used to represent a command that a user can enter in a command-line interface. + +Example: + To list the contents of a directory, use the :command:`ls` command. + +\:file\: Role +^^^^^^^^^^^^^ + +The ``:file:`` role is used to indicate a file or a file path. + +Example: + Open the configuration file :file:`conf.py` to modify the settings. + +\:kbd\: Role +^^^^^^^^^^^^ + +The ``:kbd:`` role is used to indicate keyboard keys or shortcuts. + +Example: + Press :kbd:`Ctrl` + :kbd:`C` to copy the text. + +\:guilabel\: Role +^^^^^^^^^^^^^^^^^ + +The ``:guilabel:`` role is used to indicate labels of GUI elements like buttons, labels, or fields. + +Example: + Click the :guilabel:`Submit` button to save your changes. + +Substitutions +------------- + +Sphinx allows you to define substitutions that can be used to replace text in the documentation. This is useful for +replacing frequently used text that is prone to update (e.g. versions of something, or dates). More information can be +found `here `__. +Custom substitutions are defined in :file:`docs/source/conf.py` in the ``rst_prolog`` section. For example, there is a +substitution for ``|java_vers|`` that defines the version of Java that OpenRocket requires. You can then use this +substitution in the documentation like this: OpenRocket uses Java ``|java_vers|`` (Java |java_vers|). + +Escaping Special Characters +--------------------------- + +If you need to include a special character in your text that is normally interpreted by Sphinx, you can escape it by +preceding it with a backslash. For example, to include a backslash in your text, you would write ``\\``. To include +a colon, you would write ``\:``. + +---- + +.. note:: + + The reStructuredText syntax and Sphinx' capabilities are **very rich**. This page barely scratches the surface of what you can do. + Please take the time to read the `documentation on reStructuredText `__ + and `Sphinx `__. If you find interesting features that you think would be + useful for the OpenRocket documentation, please use them and document them here! + + +Line Wrapping +------------- + +Please try to keep your lines in the .rst files under Β± 120 characters. This makes it easier to read the documentation in +the source files and prevent horizontal scrolling for code blocks. You can break up normal text on a new line without issues, +if there is no blank line between two lines of text, the two lines will be rendered as one paragraph in the output. + +Here is an example of correct and incorrect line wrapping inside the source code: + +.. figure:: /img/dev_guide/contributing_to_the_docs/Line-Wrapping.png + :width: 80% + :align: center + :alt: Correct and incorrect line wrapping. + :figclass: or-image-border + + Correct and incorrect line wrapping of a .rst file. + +For breaking up list items, you must ensure that the next line is indented by the same amounts of spaces as the first line +of the list item. For example: + +.. code-block:: rst + + - This is a list item that is very long and needs to be broken up into multiple lines. This is a list item that is very long and needs to be broken up into multiple lines. This is a list item that is very long and needs to be broken up into multiple lines. + + - This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple + lines. This is a list item that is broken up into multiple lines. + +If you do not have the right indentation, you will get a compile warning when you build the documentation. + +ToDo's +------ + +If you are working on a part of the documentation that is not yet finished, you can add a ToDo note to remind yourself to +finish it later. You can do this by adding a ``todo`` directive to the text. For example: + +.. code-block:: rst + + .. todo:: + + This section is not yet finished. Please come back later to complete it. + +You can view the ToDo's in the documentation if you set the ``todo_include_todos`` option to ``True`` in the +:file:`docs/source/conf.py` file. After you've done this and rebuilt the docs, you should see a list of all the ToDo's here: + +.. todolist:: diff --git a/docs/source/dev_guide/contributing_to_the_website.rst b/docs/source/dev_guide/contributing_to_the_website.rst new file mode 100644 index 000000000..2d4401695 --- /dev/null +++ b/docs/source/dev_guide/contributing_to_the_website.rst @@ -0,0 +1,12 @@ +*************************** +Contributing to the Website +*************************** + +OpenRocket's website, `openrocket.info `__, is hosted on GitHub Pages. The website is built +using `Jekyll `__, a static site generator. The website's source code is located in the +`openrocket.github.io `__ repository. The website's content is +written in `Markdown `__ and `HTML `__ +(including CSS and JavaScript). + +Please consult the `README file `__ in the +openrocket.github.io repository for instructions on how to contribute to the website. diff --git a/docs/source/dev_guide/contributing_to_translations.rst b/docs/source/dev_guide/contributing_to_translations.rst new file mode 100644 index 000000000..2906ecfed --- /dev/null +++ b/docs/source/dev_guide/contributing_to_translations.rst @@ -0,0 +1,111 @@ +**************************** +Contributing to Translations +**************************** + +OpenRocket is translated into multiple languages. If you want to help with translations, this document will guide you through the process. + +.. contents:: Table of Contents + :depth: 2 + :local: + +---- + +.. todo:: + Reference a doc in user_guide for changing the language + +.. todo:: + Add current state of translations? + +How Translations Work +===================== + +OpenRocket's GUI elements do not (*should not*) display hard-coded text. Instead, they use a `Translator `__ +object with a certain key to look up the text to display. The Translator object is responsible for looking up the text +in the appropriate language file and returning the translated text. + +The language files are located in the :file:`core/src/main/resources/l10n` directory. The base file for all translations is +``messages.properties``, which contains the English text. Each language has its own file, named ``messages_xx.properties``, +where ``xx`` is the language code (e.g. ``messages_nl.properties`` for Dutch). The l10n files are a simple key-value pair +where the key is the text to be translated and the value is the translated text. For example, this is a snippet from the +``messages.properties`` file: + +.. code-block:: properties + + ! RocketPanel + RocketPanel.lbl.ViewType = View Type: + RocketPanel.lbl.Zoom = Zoom: + RocketPanel.lbl.Stability = Stability: + +Comments start with a ``!`` and are ignored. The key is the text to be translated, and the value is the translated text. +The key should be unique within the file and should start with the name of the class that uses the text, followed by the type +of widget that uses the text, followed by a representation of the text. For example, the key ``RocketPanel.lbl.ViewType`` +is used by the ``RocketPanel`` class in a label widget to display the text "View Type:". The value for this key is "View Type:". + +Other language files use the exact same keys as the ``messages.properties`` base file, but with the translated text as the value. +For example, this is a snippet from the ``messages_nl.properties`` file: + +.. code-block:: properties + + ! RocketPanel + RocketPanel.lbl.ViewType = Weergavetype: + RocketPanel.lbl.Zoom = Zoom: + RocketPanel.lbl.Stability = Stabiliteit: + +When you now create a widget in the GUI, you should use the Translator object to get the translated text. For example, to +create a label widget with the text "View Type:", you would use the following code: + +.. code-block:: java + + private static final Translator trans = Application.getTranslator(); + + JLabel label = new JLabel(trans.get("RocketPanel.lbl.ViewType")); + +When the GUI is displayed, the Translator object will look up the key ``RocketPanel.lbl.ViewType`` in the appropriate language +file and return the translated text. If the key is not found in the language file, the Translator object will return the English. +This way, the GUI can be easily translated into different languages by simply adding a new language file with the translated text. + +---- + +Modifying an Existing Translation +================================= + +Open the l10n file for the language you want to modify in the :file:`core/src/main/resources/l10n` directory. For example, to modify +the French translation, open the :file:`messages_fr.properties` file, since ``fr`` corresponds to the language code of French. +Find the key for the text you want to modify and change the value. + +When you are done, create a pull request with your changes. The maintainers will review your changes and merge them if they are +appropriate. + +---- + +Creating a New Translation +========================== + +If you want to create a new translation for a language that is not yet supported, you can create a new language file in the +:file:`core/src/main/resources/l10n` directory. The file should be named ``messages_xx.properties``, where ``xx`` is the language code +of the language you want to translate to. For example, to create a translation for Finnish, you would create a file named +:file:`messages_fi.properties`. + +Copy the contents of the :file:`messages.properties` file into the new file. Translate the English text into the new language and +save the file. + +Edit the :file:`swing/src/main/java/info/openrocket/swing/gui/util/SwingPreferences.java` file and add the new language to the +``SUPPORTED_LOCALES`` array. For example, to add Finnish, you would change this line: + +.. code-block:: java + + for (String lang : new String[] { "en", "ar", "de", "es", "fr", "it", "nl", "ru", "cs", "pl", "ja", "pt", "tr" }) { + +To this (notice the addition of ``"fi"`` at the end) + +.. code-block:: java + + for (String lang : new String[] { "en", "ar", "de", "es", "fr", "it", "nl", "ru", "cs", "pl", "ja", "pt", "tr", "fi" }) { + +Finally, add yourself to the list of translation contributors (you deserve some fame! πŸ™‚). This is done in the +:file:`swing/src/main/java/info/openrocket/swing/gui/dialogs/AboutDialog.java` file. +In this file, edit the String 'CREDITS' and add your details to the list after the 'Translations by:'-tag. + +When you are done, create a pull request with your changes. The maintainers will review your changes and merge them if they are. +If you are not at all familiar with git, you can also `create an issue `__ +with your changes and the maintainers will create the pull request for you. diff --git a/docs/source/dev_guide/development_guidelines.rst b/docs/source/dev_guide/development_guidelines.rst new file mode 100644 index 000000000..8a695dd28 --- /dev/null +++ b/docs/source/dev_guide/development_guidelines.rst @@ -0,0 +1,33 @@ +********************** +Development Guidelines +********************** + +In order to maintain a high level of code quality and improve the efficiency for other developers to verify your code, +we have established the following guidelines for contributing to the project. + +.. contents:: Table of Contents + :depth: 2 + :local: + +---- + +Coding Standards +================ + +Where possible, write unit tests for your code (see :doc:`Testing and Debugging `). +This will help to ensure that your code is correct, and will help to prevent regressions in the future. +Also include edge cases in your tests. + +Use `atomic commits `__. Each commit should be a single logical change. +Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a +feature, it should be split into two separate commits. + +Commit messages should be clear, concise, and useful. The first line should be a short description of the commit, then a blank line, +then a more detailed explanation. The commit message should be in the present tense. For example, "Fix bug" and not "Fixed bug". + +If applicable, include a reference to the issue that the commit addresses. For example, if you're working on a fix for GitHub +issue #123, then format your commit message like this: "[#123] Fix bug". This makes it easier to track which commits are +associated with which issues. + +Pull Request Process +==================== \ No newline at end of file diff --git a/docs/source/dev_guide/development_overview.rst b/docs/source/dev_guide/development_overview.rst new file mode 100644 index 000000000..5a55522c7 --- /dev/null +++ b/docs/source/dev_guide/development_overview.rst @@ -0,0 +1,74 @@ +******************** +Development Overview +******************** + +Welcome to the OpenRocket Development Guide! This documentation is designed for developers interested in contributing to OpenRocket. + +This guide covers the architecture, codebase, and development workflows in detail. To dive deeper into specific topics, +use the links below to navigate to different sections of this development guide. To learn more about the technical aspects +of OpenRocket, such as the aerodynamic calculations, refer to the `Technical documentation `__. + +Code structure +============== + +OpenRocket is a Java application organized using the Java Platform Module System (JPMS) and built with `Gradle `__. +The code is organized in the following two packages: + +- `info.openrocket.core `__ - The backend of OpenRocket. \ + This package contains the classes that represent the rocket and its components, as well as the simulation engine. \ + The classes in this package are not dependent on any GUI libraries and can be used in other applications. + +- `info.openrocket.swing `__ - The GUI of OpenRocket. \ + This package contains the classes that create the user interface. OpenRocket uses the Java Swing library for the GUI. + +Further Reading +=============== + +Explore the following sections to learn more about OpenRocket's development: + +- :doc:`Development Environment Setup ` + |br_no_pad| + *How to set up your development environment to build and run OpenRocket.* + +- :doc:`OpenRocket Architecture ` + |br_no_pad| + *An overview of the high-level code architecture of OpenRocket.* + +- :doc:`Codebase Walkthrough ` + |br_no_pad| + *A detailed guide to the codebase of OpenRocket.* + +- :doc:`Development Guidelines ` + |br_no_pad| + *Guidelines for contributing to OpenRocket.* + +- :doc:`Testing and Debugging ` + |br_no_pad| + *How to test and debug the OpenRocket code.* + +- :doc:`API Documentation ` + |br_no_pad| + *Documentation for the OpenRocket API.* + +- :doc:`Building and Releasing ` + |br_no_pad| + *How to build and release new OpenRocket versions.* + +- :doc:`Contributing to the Website ` + |br_no_pad| + *How to contribute to the* `openrocket.info `__ *website.* + +- :doc:`Contributing to Translations ` + |br_no_pad| + *How to contribute to translating the OpenRocket UI into different languages.* + +- :doc:`Contributing to the Documentation ` + |br_no_pad| + *How to contribute to this OpenRocket documentation.* + +- :doc:`FAQ and Troubleshooting ` + |br_no_pad| + *Frequently asked questions and troubleshooting tips for developers.* + +**We encourage contributions from everyone and hope this guide helps you get started with developing OpenRocket. ❀️** + diff --git a/docs/source/dev_guide/development_setup.rst b/docs/source/dev_guide/development_setup.rst new file mode 100644 index 000000000..f25d79748 --- /dev/null +++ b/docs/source/dev_guide/development_setup.rst @@ -0,0 +1,243 @@ +***************************** +Development Environment Setup +***************************** + +This guide will walk you through setting up the development environment to build OpenRocket from the source code. + +.. contents:: Table of Contents + :depth: 2 + :local: + +---- + +Prerequisites +============= + +- `JDK 17 `__. OpenRocket is developed using Java 17, + so you will need to install it to build and run OpenRocket. If you have multiple versions of Java installed, ensure that + Java |java_vers| is the default version. + +- `Git `__. Git is a version control system that is used to manage the source code for OpenRocket. + You will need to install Git to clone the OpenRocket repository. + +- `GitHub Account `__. GitHub is a platform for hosting Git repositories. You will need a GitHub account to + fork the OpenRocket repository and submit pull requests. + +- `Gradle `__. OpenRocket uses Gradle as its build system. You will need to install Gradle to build OpenRocket. + +Obtaining the Source Code +========================= + +The source code for OpenRocket is hosted on `GitHub `__. However, you cannot change +this code directly. This is because the OpenRocket repository is the official repository for the project, and only the project +maintainers can make changes to it. This is to ensure that the codebase remains stable and consistent. +Instead, you must fork the OpenRocket repository, which creates a personal copy of the repository that you can make changes to. +You can then submit a pull request to the OpenRocket repository to propose your changes. + +Forking the Repository +---------------------- + +The first step is to fork the OpenRocket repository. As mentioned earlier, the OpenRocket repository is the official repository +for the project, and only the project maintainers can make changes to it. + +Go to the OpenRocket repository on GitHub (`link `__) and click the :guilabel:`Fork` button: + +.. figure:: /img/dev_guide/development_setup/fork_repo.png + :align: center + :width: 90% + :alt: Forking the official OpenRocket repository. + + Forking the official OpenRocket repository on `github.com/openrocket/openrocket `__. + +You can leave the default settings and click ``Create fork``. This will create a copy of the OpenRocket repository in your GitHub account: + +.. figure:: /img/dev_guide/development_setup/forked_repo.png + :align: center + :width: 80% + :alt: Your forked repo. + + Your forked repo. + +You can always retrieve your forked repository under your GitHub account, under ``Your repositories``, or by visiting the URL +``https://github.com//openrocket`` (replace ```` +with your actual username). + +Cloning the Repository +---------------------- + +Now that you have forked the OpenRocket repository, you can clone it to your local machine. To do this, open a terminal +and run the following command (replace ``[YOUR USERNAME]`` with your GitHub username): + +.. code-block:: bash + + # Use the following command if you have set up SSH keys with GitHub + git clone git@github.com:[YOUR USERNAME]/openrocket.git + + # Otherwise, clone the repository using HTTPS + git clone https://github.com/[YOUR USERNAME]/openrocket.git + +This will clone the OpenRocket repository to your local machine. You can now make changes to the code and push them to your forked repository. + +One final step you need to do is to initialize the submodules. OpenRocket uses submodules for some of its dependencies. +To initialize the submodules, run the following commands: + +.. code-block:: bash + + git submodule init + git submodule update + + +Keeping your Fork in Sync +------------------------- + +Once you have forked the OpenRocket repository, you will need to keep your fork in sync with the official repository. This is because +the official repository may have changes that are not in your fork, and you will want to keep your fork up-to-date with the latest changes. +For example, in the following image you can see that your fork is 10 commits behind the official repository: + +.. figure:: /img/dev_guide/development_setup/forked_repo_outdated.png + :align: center + :width: 80% + :alt: An outdated forked repo. + + An outdated forked repo. + +Luckily, GitHub makes it easy to keep your fork in sync with the official repository. You can do this by clicking the +``Sync fork`` button on your forked repository page and then clicking the :guilabel:`Update branch` button: + +.. figure:: /img/dev_guide/development_setup/sync_fork.png + :align: center + :width: 80% + :alt: Syncing your forked repo on GitHub. + + Syncing your forked repo on GitHub. + +If all went well, your fork should now be up-to-date with the official repository: + +.. figure:: /img/dev_guide/development_setup/forked_repo_up_to_date.png + :align: center + :width: 80% + :alt: An up-to-date forked repo. + + An up-to-date forked repo. + +.. warning:: + It is important to keep your fork in sync with the official repository. If you don't, you may encounter conflicts + when you try to submit a pull request. + + **Regularly check your forked repository to see if it is behind the official repository**. If it is, sync your fork! + +Now you have updated your fork, but you still need to update your local repository (your clone). +To do this, you need to fetch the changes from the official repository and pull them into your local repository. +You can do this by running the following commands: + +.. code-block:: bash + + git fetch && git pull + +Setting Up the Development Environment +====================================== + +This section will guide you through setting up the development environment to build OpenRocket from the source code. + +IntelliJ IDEA +------------- + +`IntelliJ IDEA `__ is a popular Java IDE that is used by many developers. It has a lot of +features that make it easier to develop Java applications. We **highly** recommend using IntelliJ IDEA for developing +OpenRocket. You can download the Community Edition for free from the `JetBrains website `__ +(scroll down to β€œIntelliJ IDEA Community Edition” and click the download button). + +Once you have downloaded and installed IntelliJ IDEA, you can open the OpenRocket project: + +1. **Open IntelliJ IDEA** + Start IntelliJ IDEA and select "Open" (Go to :menuselection:`File --> Open`). + +2. **Select the OpenRocket project** + Navigate to the directory where you cloned OpenRocket and select the project. + +3. **Import Project as Gradle Project** + IntelliJ should automatically detect that this is a Gradle project. If prompted, select ``Load Gradle Project``. + + .. figure:: /img/dev_guide/development_setup/load_gradle_project.png + :align: center + :width: 80% + :alt: Load Gradle Project. + + IntelliJ IDEA will automatically detect that this is a Gradle project and prompt you to load it. Click ``Load Gradle Project``. + +4. **Configure JDK for the Project** + - Go to :menuselection:`File --> Project Structure --> (Project Settings -->) Project`. + - Set the Project SDK to JDK |java_vers|. + + .. figure:: /img/dev_guide/development_setup/project_sdk.png + :align: center + :width: 80% + :alt: Set the project SDK. + + Set the project SDK to JDK |java_vers|. + + If JDK |java_vers| is not listed, you can download it from the Project Structure dialog by \ + going to :menuselection:`(Platform Settings -->) SDKs`, clicking the :guilabel:`+` button, and selecting ``Download JDK...``. Then select \ + version |java_vers| and any vendor (e.g. OpenJDK, Amazon Corretto, ...). + + - Confirm in the Project Structure dialog under :menuselection:`(Project Settings -->) Modules` that the SDK in each module is set to JDK |java_vers|. \ + If not, you can change it by selecting the module and setting the SDK in the right pane. Ensure that the list view on the bottom-right \ + does not show ````. If it does, click the *Module SDK* dropdown and click (again) on the JDK |java_vers| SDK. + + .. figure:: /img/dev_guide/development_setup/modules_sdk.png + :align: center + :width: 80% + :alt: Set the module SDK. + + Set the module SDK to JDK |java_vers|. + +5. **Run the Application** + By default, IntelliJ should be set up with 3 run configurations: + + - ``SwingStartup``: Run the application directly from within IntelliJ. You will user this configuration most of the time. \ + You can also run IntelliJ in debug mode by clicking the green bug icon next to the play button. + + - ``openrocket-jar``: Run all the unit tests and build the application as a JAR file. + + - ``openrocket-test``: Only run the unit tests. + + .. figure:: /img/dev_guide/development_setup/run_configurations.png + :align: center + :width: 80% + :alt: Default installed run configurations. + + The default installed run configurations. + + You can run the application by selecting the ``SwingStartup`` configuration and clicking the green play button. + This will instantiate the OpenRocket application from within IntelliJ IDEA. If you want to stop the running application, + click the red square button on the top-right in IntelliJ. + + .. figure:: /img/dev_guide/development_setup/swingstartup.png + :align: center + :width: 80% + :alt: Running OpenRocket from IntelliJ IDEA. + + Running OpenRocket directly from IntelliJ IDEA. + +6. **That's it!** You can now start developing OpenRocket. πŸš€ + +Command Line Interface +---------------------- + +It is also possible to develop in a text editor and build OpenRocket from the command line using Gradle. Please refer to the :doc:`Building and Releasing ` +section for all the possible Gradle tasks. To run OpenRocket, you can use: + +.. code-block:: bash + + ./gradlew run + +Troubleshooting +=============== + +1. **JDK Not Recognized** + Ensure that the JDK path is correctly configured in :menuselection:`File --> Project Structure --> SDKs`. + +2. **Gradle Sync Issues** + - If IntelliJ fails to import Gradle projects correctly, try refreshing the Gradle project by clicking on the "Reload All Gradle Projects" icon in the Gradle tool window. + - Ensure the `gradle-wrapper.properties` file points to the correct Gradle version which supports Java |java_vers|. + diff --git a/docs/source/dev_guide/faq_troubleshooting.rst b/docs/source/dev_guide/faq_troubleshooting.rst new file mode 100644 index 000000000..3a285640a --- /dev/null +++ b/docs/source/dev_guide/faq_troubleshooting.rst @@ -0,0 +1,16 @@ +*********************** +FAQ and Troubleshooting +*********************** + +.. rubric:: Q: Why does OpenRocket still use the "ancient" Java language? Python and web-based programs are the future. + +A: Java is a very powerful language and is still widely used in the industry. While it is true that Java is not as popular +with (new) developers as Python or web-based languages, there are currently no plans of rewriting the codebase in another +language. The main reason for this is that it would take a lot of time to rewrite the codebase, more time than the current +OpenRocket developers can afford to miss of their (limited) spare time. Besides, the current Java codebase is +still working fine and has been tested by many users over the years. + +That being said, maintaining a Java application does have challenges, mainly in ensuring it runs on all platforms and +hardware configurations. Maintaining the GUI and 3D view has proven to be very challenging. Additionally, Java cannot be +run on mobile devices such as iOS devices. If you are a developer and would like to contribute to the codebase rewrite, +please contact the OpenRocket developers to see what you could do to help! diff --git a/docs/source/dev_guide/testing_and_debugging.rst b/docs/source/dev_guide/testing_and_debugging.rst new file mode 100644 index 000000000..d0410db40 --- /dev/null +++ b/docs/source/dev_guide/testing_and_debugging.rst @@ -0,0 +1,11 @@ +********************* +Testing and Debugging +********************* + +Unit Testing +============ + +Debugging +========= + +IDE debugger, print statements, in-program debug log, debug command line argument... diff --git a/docs/source/img/dev_guide/building_releasing/gradle_in_intellij.png b/docs/source/img/dev_guide/building_releasing/gradle_in_intellij.png new file mode 100644 index 000000000..db33eee7d Binary files /dev/null and b/docs/source/img/dev_guide/building_releasing/gradle_in_intellij.png differ diff --git a/docs/source/img/dev_guide/building_releasing/install4j_build.png b/docs/source/img/dev_guide/building_releasing/install4j_build.png new file mode 100644 index 000000000..76ec53f81 Binary files /dev/null and b/docs/source/img/dev_guide/building_releasing/install4j_build.png differ diff --git a/docs/source/img/dev_guide/building_releasing/intellij_gradle_window.png b/docs/source/img/dev_guide/building_releasing/intellij_gradle_window.png new file mode 100644 index 000000000..b32bba7be Binary files /dev/null and b/docs/source/img/dev_guide/building_releasing/intellij_gradle_window.png differ diff --git a/docs/source/img/dev_guide/contributing_to_the_docs/Line-Wrapping.png b/docs/source/img/dev_guide/contributing_to_the_docs/Line-Wrapping.png new file mode 100644 index 000000000..762e90102 Binary files /dev/null and b/docs/source/img/dev_guide/contributing_to_the_docs/Line-Wrapping.png differ diff --git a/docs/source/img/dev_guide/contributing_to_the_docs/Oscar.jpeg b/docs/source/img/dev_guide/contributing_to_the_docs/Oscar.jpeg new file mode 100644 index 000000000..8e352ab94 Binary files /dev/null and b/docs/source/img/dev_guide/contributing_to_the_docs/Oscar.jpeg differ diff --git a/docs/source/img/dev_guide/development_setup/fork_repo.png b/docs/source/img/dev_guide/development_setup/fork_repo.png new file mode 100644 index 000000000..db8551b38 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/fork_repo.png differ diff --git a/docs/source/img/dev_guide/development_setup/forked_repo.png b/docs/source/img/dev_guide/development_setup/forked_repo.png new file mode 100644 index 000000000..7f2392964 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/forked_repo.png differ diff --git a/docs/source/img/dev_guide/development_setup/forked_repo_outdated.png b/docs/source/img/dev_guide/development_setup/forked_repo_outdated.png new file mode 100644 index 000000000..4ceabaa6b Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/forked_repo_outdated.png differ diff --git a/docs/source/img/dev_guide/development_setup/forked_repo_up_to_date.png b/docs/source/img/dev_guide/development_setup/forked_repo_up_to_date.png new file mode 100644 index 000000000..21252f443 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/forked_repo_up_to_date.png differ diff --git a/docs/source/img/dev_guide/development_setup/load_gradle_project.png b/docs/source/img/dev_guide/development_setup/load_gradle_project.png new file mode 100644 index 000000000..5a8c22c88 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/load_gradle_project.png differ diff --git a/docs/source/img/dev_guide/development_setup/modules_sdk.png b/docs/source/img/dev_guide/development_setup/modules_sdk.png new file mode 100644 index 000000000..c027d9e86 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/modules_sdk.png differ diff --git a/docs/source/img/dev_guide/development_setup/project_sdk.png b/docs/source/img/dev_guide/development_setup/project_sdk.png new file mode 100644 index 000000000..5dd21b86c Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/project_sdk.png differ diff --git a/docs/source/img/dev_guide/development_setup/run_configurations.png b/docs/source/img/dev_guide/development_setup/run_configurations.png new file mode 100644 index 000000000..a25778264 Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/run_configurations.png differ diff --git a/docs/source/img/dev_guide/development_setup/swingstartup.png b/docs/source/img/dev_guide/development_setup/swingstartup.png new file mode 100644 index 000000000..e0133a90e Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/swingstartup.png differ diff --git a/docs/source/img/dev_guide/development_setup/sync_fork.png b/docs/source/img/dev_guide/development_setup/sync_fork.png new file mode 100644 index 000000000..50c2b63af Binary files /dev/null and b/docs/source/img/dev_guide/development_setup/sync_fork.png differ diff --git a/docs/source/img/openrocket_logo_256.png b/docs/source/img/openrocket_logo_256.png new file mode 100644 index 000000000..97bbba818 Binary files /dev/null and b/docs/source/img/openrocket_logo_256.png differ diff --git a/docs/source/img/setup/getting_started/01.02.Rocket_Design.Tab.png b/docs/source/img/setup/getting_started/01.02.Rocket_Design.Tab.png new file mode 100644 index 000000000..cf59bbca0 Binary files /dev/null and b/docs/source/img/setup/getting_started/01.02.Rocket_Design.Tab.png differ diff --git a/docs/source/img/setup/getting_started/02.02.Motor-Configuration.Tab.png b/docs/source/img/setup/getting_started/02.02.Motor-Configuration.Tab.png new file mode 100644 index 000000000..ae3a4d4a3 Binary files /dev/null and b/docs/source/img/setup/getting_started/02.02.Motor-Configuration.Tab.png differ diff --git a/docs/source/img/setup/getting_started/02.04.01.File_Menu.png b/docs/source/img/setup/getting_started/02.04.01.File_Menu.png new file mode 100644 index 000000000..8436f4b71 Binary files /dev/null and b/docs/source/img/setup/getting_started/02.04.01.File_Menu.png differ diff --git a/docs/source/img/setup/getting_started/03.02.Flight_simulations.Tab.png b/docs/source/img/setup/getting_started/03.02.Flight_simulations.Tab.png new file mode 100644 index 000000000..d0d81bce9 Binary files /dev/null and b/docs/source/img/setup/getting_started/03.02.Flight_simulations.Tab.png differ diff --git a/docs/source/img/setup/getting_started/04.01.02.Rocket_Configuration.png b/docs/source/img/setup/getting_started/04.01.02.Rocket_Configuration.png new file mode 100644 index 000000000..98c41fef6 Binary files /dev/null and b/docs/source/img/setup/getting_started/04.01.02.Rocket_Configuration.png differ diff --git a/docs/source/img/setup/getting_started/04.01.05.Rocket_Configuration.Rename.png b/docs/source/img/setup/getting_started/04.01.05.Rocket_Configuration.Rename.png new file mode 100644 index 000000000..38541349a Binary files /dev/null and b/docs/source/img/setup/getting_started/04.01.05.Rocket_Configuration.Rename.png differ diff --git a/docs/source/img/setup/getting_started/11.01.03.Rocket_Build.Nose_Cone.png b/docs/source/img/setup/getting_started/11.01.03.Rocket_Build.Nose_Cone.png new file mode 100644 index 000000000..c0a28cac0 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.01.03.Rocket_Build.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/11.02.01.Rocket_Build.Payload_Bay.png b/docs/source/img/setup/getting_started/11.02.01.Rocket_Build.Payload_Bay.png new file mode 100644 index 000000000..33bc131d0 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.02.01.Rocket_Build.Payload_Bay.png differ diff --git a/docs/source/img/setup/getting_started/11.02.05.Rocket_Build.Payload_Bay.png b/docs/source/img/setup/getting_started/11.02.05.Rocket_Build.Payload_Bay.png new file mode 100644 index 000000000..c2bd69cac Binary files /dev/null and b/docs/source/img/setup/getting_started/11.02.05.Rocket_Build.Payload_Bay.png differ diff --git a/docs/source/img/setup/getting_started/11.02.06.Rocket_Build.Payload_Bay.png b/docs/source/img/setup/getting_started/11.02.06.Rocket_Build.Payload_Bay.png new file mode 100644 index 000000000..c6a9e3008 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.02.06.Rocket_Build.Payload_Bay.png differ diff --git a/docs/source/img/setup/getting_started/11.03.01.Rocket_Build.Transition.png b/docs/source/img/setup/getting_started/11.03.01.Rocket_Build.Transition.png new file mode 100644 index 000000000..4c676d54c Binary files /dev/null and b/docs/source/img/setup/getting_started/11.03.01.Rocket_Build.Transition.png differ diff --git a/docs/source/img/setup/getting_started/11.03.06.Rocket_Build.Transition.png b/docs/source/img/setup/getting_started/11.03.06.Rocket_Build.Transition.png new file mode 100644 index 000000000..c22499914 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.03.06.Rocket_Build.Transition.png differ diff --git a/docs/source/img/setup/getting_started/11.03.07.Rocket_Build.Transition.png b/docs/source/img/setup/getting_started/11.03.07.Rocket_Build.Transition.png new file mode 100644 index 000000000..3e8f6db04 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.03.07.Rocket_Build.Transition.png differ diff --git a/docs/source/img/setup/getting_started/11.04.01.Rocket_Build.Body_Tube.png b/docs/source/img/setup/getting_started/11.04.01.Rocket_Build.Body_Tube.png new file mode 100644 index 000000000..db189f3d7 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.04.01.Rocket_Build.Body_Tube.png differ diff --git a/docs/source/img/setup/getting_started/11.04.02.Rocket_Build.Body_Tube.png b/docs/source/img/setup/getting_started/11.04.02.Rocket_Build.Body_Tube.png new file mode 100644 index 000000000..bec0b6f21 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.04.02.Rocket_Build.Body_Tube.png differ diff --git a/docs/source/img/setup/getting_started/11.05.01.Rocket_Build.Fins.png b/docs/source/img/setup/getting_started/11.05.01.Rocket_Build.Fins.png new file mode 100644 index 000000000..65513d17d Binary files /dev/null and b/docs/source/img/setup/getting_started/11.05.01.Rocket_Build.Fins.png differ diff --git a/docs/source/img/setup/getting_started/11.05.02.Rocket_Build.Fins.png b/docs/source/img/setup/getting_started/11.05.02.Rocket_Build.Fins.png new file mode 100644 index 000000000..4b6e2bddf Binary files /dev/null and b/docs/source/img/setup/getting_started/11.05.02.Rocket_Build.Fins.png differ diff --git a/docs/source/img/setup/getting_started/11.05.03.Rocket_Build.Fins.png b/docs/source/img/setup/getting_started/11.05.03.Rocket_Build.Fins.png new file mode 100644 index 000000000..35b09f9ab Binary files /dev/null and b/docs/source/img/setup/getting_started/11.05.03.Rocket_Build.Fins.png differ diff --git a/docs/source/img/setup/getting_started/11.06.02.Rocket_Build.Launch_Lug.png b/docs/source/img/setup/getting_started/11.06.02.Rocket_Build.Launch_Lug.png new file mode 100644 index 000000000..e72ab9deb Binary files /dev/null and b/docs/source/img/setup/getting_started/11.06.02.Rocket_Build.Launch_Lug.png differ diff --git a/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.3D_Unfinished.png b/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.3D_Unfinished.png new file mode 100644 index 000000000..e72223754 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.3D_Unfinished.png differ diff --git a/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.Launch_Lug.png b/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.Launch_Lug.png new file mode 100644 index 000000000..091df7b27 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.06.03.Rocket_Build.Launch_Lug.png differ diff --git a/docs/source/img/setup/getting_started/11.06.04.Rocket_Build.3D_Finished.png b/docs/source/img/setup/getting_started/11.06.04.Rocket_Build.3D_Finished.png new file mode 100644 index 000000000..4d55e6b59 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.06.04.Rocket_Build.3D_Finished.png differ diff --git a/docs/source/img/setup/getting_started/11.07.03.Rocket_Build.Parachute.png b/docs/source/img/setup/getting_started/11.07.03.Rocket_Build.Parachute.png new file mode 100644 index 000000000..ced1a5b4f Binary files /dev/null and b/docs/source/img/setup/getting_started/11.07.03.Rocket_Build.Parachute.png differ diff --git a/docs/source/img/setup/getting_started/11.08.01.Rocket_Build.Parachute.png b/docs/source/img/setup/getting_started/11.08.01.Rocket_Build.Parachute.png new file mode 100644 index 000000000..49ebfcdfe Binary files /dev/null and b/docs/source/img/setup/getting_started/11.08.01.Rocket_Build.Parachute.png differ diff --git a/docs/source/img/setup/getting_started/11.08.02.Rocket_Build.Parachute.png b/docs/source/img/setup/getting_started/11.08.02.Rocket_Build.Parachute.png new file mode 100644 index 000000000..e88ad8c12 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.08.02.Rocket_Build.Parachute.png differ diff --git a/docs/source/img/setup/getting_started/11.09.01.Rocket_Build.Engine_Block.png b/docs/source/img/setup/getting_started/11.09.01.Rocket_Build.Engine_Block.png new file mode 100644 index 000000000..951471d5a Binary files /dev/null and b/docs/source/img/setup/getting_started/11.09.01.Rocket_Build.Engine_Block.png differ diff --git a/docs/source/img/setup/getting_started/11.09.02.Rocket_Build.Engine_Block.png b/docs/source/img/setup/getting_started/11.09.02.Rocket_Build.Engine_Block.png new file mode 100644 index 000000000..7a3c55267 Binary files /dev/null and b/docs/source/img/setup/getting_started/11.09.02.Rocket_Build.Engine_Block.png differ diff --git a/docs/source/img/setup/getting_started/12.10.01.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.01.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..fd0f94418 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.01.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.05.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.05.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..6c605ff94 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.05.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.06.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.06.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..0174f3d86 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.06.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.07.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.07.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..c43a4a473 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.07.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.11.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.11.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..d47a48cc8 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.11.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.12.Rocket_Build_Appearance.Nose_Cone.png b/docs/source/img/setup/getting_started/12.10.12.Rocket_Build_Appearance.Nose_Cone.png new file mode 100644 index 000000000..90037e403 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.12.Rocket_Build_Appearance.Nose_Cone.png differ diff --git a/docs/source/img/setup/getting_started/12.10.13.Rocket_Build_Appearance.Decal.png b/docs/source/img/setup/getting_started/12.10.13.Rocket_Build_Appearance.Decal.png new file mode 100644 index 000000000..a101dbc39 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.13.Rocket_Build_Appearance.Decal.png differ diff --git a/docs/source/img/setup/getting_started/12.10.16.Rocket_Build_Appearance.Payload_Bay.Decal.png b/docs/source/img/setup/getting_started/12.10.16.Rocket_Build_Appearance.Payload_Bay.Decal.png new file mode 100644 index 000000000..d37e4bfd7 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.16.Rocket_Build_Appearance.Payload_Bay.Decal.png differ diff --git a/docs/source/img/setup/getting_started/12.10.19.Rocket_Build_Appearance.Payload_Bay.Decal.png b/docs/source/img/setup/getting_started/12.10.19.Rocket_Build_Appearance.Payload_Bay.Decal.png new file mode 100644 index 000000000..f4ae314ba Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.19.Rocket_Build_Appearance.Payload_Bay.Decal.png differ diff --git a/docs/source/img/setup/getting_started/12.10.20.Rocket_Build_Appearance.Payload_Bay.Decal.png b/docs/source/img/setup/getting_started/12.10.20.Rocket_Build_Appearance.Payload_Bay.Decal.png new file mode 100644 index 000000000..44c73c166 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.20.Rocket_Build_Appearance.Payload_Bay.Decal.png differ diff --git a/docs/source/img/setup/getting_started/12.10.21.Rocket_Build_Appearance.Fins.png b/docs/source/img/setup/getting_started/12.10.21.Rocket_Build_Appearance.Fins.png new file mode 100644 index 000000000..8691f4869 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.10.21.Rocket_Build_Appearance.Fins.png differ diff --git a/docs/source/img/setup/getting_started/12.11.03.Rocket_Build_Appearance.Fins.png b/docs/source/img/setup/getting_started/12.11.03.Rocket_Build_Appearance.Fins.png new file mode 100644 index 000000000..d2cca978f Binary files /dev/null and b/docs/source/img/setup/getting_started/12.11.03.Rocket_Build_Appearance.Fins.png differ diff --git a/docs/source/img/setup/getting_started/12.11.11.Rocket_Build_Appearance.Fins.png b/docs/source/img/setup/getting_started/12.11.11.Rocket_Build_Appearance.Fins.png new file mode 100644 index 000000000..cedb394ca Binary files /dev/null and b/docs/source/img/setup/getting_started/12.11.11.Rocket_Build_Appearance.Fins.png differ diff --git a/docs/source/img/setup/getting_started/12.11.12.Rocket_Build_Appearance.Fins.png b/docs/source/img/setup/getting_started/12.11.12.Rocket_Build_Appearance.Fins.png new file mode 100644 index 000000000..ad2cb8bb7 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.11.12.Rocket_Build_Appearance.Fins.png differ diff --git a/docs/source/img/setup/getting_started/12.12.01.Rocket_Build.Photo_Studio.png b/docs/source/img/setup/getting_started/12.12.01.Rocket_Build.Photo_Studio.png new file mode 100644 index 000000000..e9821ca3e Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.01.Rocket_Build.Photo_Studio.png differ diff --git a/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Motor.png b/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Motor.png new file mode 100644 index 000000000..283599ad1 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Motor.png differ diff --git a/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Photo_Studio.png b/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Photo_Studio.png new file mode 100644 index 000000000..2a8a897fc Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.02.Rocket_Build.Photo_Studio.png differ diff --git a/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Motor.png b/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Motor.png new file mode 100644 index 000000000..3b6d47caa Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Motor.png differ diff --git a/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Photo_Studio.png b/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Photo_Studio.png new file mode 100644 index 000000000..3db2d8052 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.03.Rocket_Build.Photo_Studio.png differ diff --git a/docs/source/img/setup/getting_started/12.12.05.Rocket_Build.Motor.png b/docs/source/img/setup/getting_started/12.12.05.Rocket_Build.Motor.png new file mode 100644 index 000000000..2357b1862 Binary files /dev/null and b/docs/source/img/setup/getting_started/12.12.05.Rocket_Build.Motor.png differ diff --git a/docs/source/img/setup/getting_started/2023.01.Guide.User_Interface.png b/docs/source/img/setup/getting_started/2023.01.Guide.User_Interface.png new file mode 100644 index 000000000..cb3ba84b3 Binary files /dev/null and b/docs/source/img/setup/getting_started/2023.01.Guide.User_Interface.png differ diff --git a/docs/source/img/setup/getting_started/2023.01.Open_Example.png b/docs/source/img/setup/getting_started/2023.01.Open_Example.png new file mode 100644 index 000000000..ce470a1b1 Binary files /dev/null and b/docs/source/img/setup/getting_started/2023.01.Open_Example.png differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.Parts_Library.Highlighted.jpg b/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.Parts_Library.Highlighted.jpg new file mode 100644 index 000000000..2435e87a2 Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.Parts_Library.Highlighted.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.jpg b/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.jpg new file mode 100644 index 000000000..42a01f0c5 Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Components.Nose_Cone.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Figure.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Figure.jpg new file mode 100644 index 000000000..8966c09fc Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Figure.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Finished.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Finished.jpg new file mode 100644 index 000000000..00a30c8bd Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Finished.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Unfinished.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Unfinished.jpg new file mode 100644 index 000000000..539b09185 Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.3D_Unfinished.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Back_View.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Back_View.jpg new file mode 100644 index 000000000..829401194 Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Back_View.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Side_View.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Side_View.jpg new file mode 100644 index 000000000..d1daae16e Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Side_View.jpg differ diff --git a/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Top_View.jpg b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Top_View.jpg new file mode 100644 index 000000000..120bdfaae Binary files /dev/null and b/docs/source/img/setup/getting_started/Getting_Started.Rocket_Views.Top_View.jpg differ diff --git a/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.02.File.png b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.02.File.png new file mode 100644 index 000000000..748095f8e Binary files /dev/null and b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.02.File.png differ diff --git a/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.03.File.png b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.03.File.png new file mode 100644 index 000000000..8492850f8 Binary files /dev/null and b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.03.File.png differ diff --git a/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.04.File.png b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.04.File.png new file mode 100644 index 000000000..185825190 Binary files /dev/null and b/docs/source/img/setup/getting_started/OR.Guide.User_Interface.04.04.File.png differ diff --git a/docs/source/img/setup/installation/about_dialog.png b/docs/source/img/setup/installation/about_dialog.png new file mode 100644 index 000000000..ba79f0c02 Binary files /dev/null and b/docs/source/img/setup/installation/about_dialog.png differ diff --git a/docs/source/img/setup/installation/off_screen_rendering_right.png b/docs/source/img/setup/installation/off_screen_rendering_right.png new file mode 100644 index 000000000..2845642c0 Binary files /dev/null and b/docs/source/img/setup/installation/off_screen_rendering_right.png differ diff --git a/docs/source/img/setup/installation/off_screen_rendering_setting.png b/docs/source/img/setup/installation/off_screen_rendering_setting.png new file mode 100644 index 000000000..a59f92c71 Binary files /dev/null and b/docs/source/img/setup/installation/off_screen_rendering_setting.png differ diff --git a/docs/source/img/setup/installation/off_screen_rendering_wrong.png b/docs/source/img/setup/installation/off_screen_rendering_wrong.png new file mode 100644 index 000000000..1ca9baad3 Binary files /dev/null and b/docs/source/img/setup/installation/off_screen_rendering_wrong.png differ diff --git a/docs/source/img/setup/installation/splash_screen.png b/docs/source/img/setup/installation/splash_screen.png new file mode 100644 index 000000000..b28129a17 Binary files /dev/null and b/docs/source/img/setup/installation/splash_screen.png differ diff --git a/docs/source/img/setup/installation/thrust_curves_setting.png b/docs/source/img/setup/installation/thrust_curves_setting.png new file mode 100644 index 000000000..53917e2b2 Binary files /dev/null and b/docs/source/img/setup/installation/thrust_curves_setting.png differ diff --git a/docs/source/img/setup/preferences/Access-Preferences.png b/docs/source/img/setup/preferences/Access-Preferences.png new file mode 100644 index 000000000..6c538cd73 Binary files /dev/null and b/docs/source/img/setup/preferences/Access-Preferences.png differ diff --git a/docs/source/img/setup/preferences/ExportPreferences.png b/docs/source/img/setup/preferences/ExportPreferences.png new file mode 100644 index 000000000..5feef66e8 Binary files /dev/null and b/docs/source/img/setup/preferences/ExportPreferences.png differ diff --git a/docs/source/img/setup/preferences/FontSize13.png b/docs/source/img/setup/preferences/FontSize13.png new file mode 100644 index 000000000..aea9b389c Binary files /dev/null and b/docs/source/img/setup/preferences/FontSize13.png differ diff --git a/docs/source/img/setup/preferences/FontSize17.png b/docs/source/img/setup/preferences/FontSize17.png new file mode 100644 index 000000000..a4d11c588 Binary files /dev/null and b/docs/source/img/setup/preferences/FontSize17.png differ diff --git a/docs/source/img/setup/preferences/FontSize9.png b/docs/source/img/setup/preferences/FontSize9.png new file mode 100644 index 000000000..1981541d4 Binary files /dev/null and b/docs/source/img/setup/preferences/FontSize9.png differ diff --git a/docs/source/img/setup/preferences/PodAndBoosterMarker.png b/docs/source/img/setup/preferences/PodAndBoosterMarker.png new file mode 100644 index 000000000..ba9521e96 Binary files /dev/null and b/docs/source/img/setup/preferences/PodAndBoosterMarker.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Design.png b/docs/source/img/setup/preferences/Prefs-Design.png new file mode 100644 index 000000000..4678f456a Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Design.png differ diff --git a/docs/source/img/setup/preferences/Prefs-General.png b/docs/source/img/setup/preferences/Prefs-General.png new file mode 100644 index 000000000..3179c11c8 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-General.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Graphics.png b/docs/source/img/setup/preferences/Prefs-Graphics.png new file mode 100644 index 000000000..738f9f2a8 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Graphics.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Launch.png b/docs/source/img/setup/preferences/Prefs-Launch.png new file mode 100644 index 000000000..bd9fa75e8 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Launch.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Materials.png b/docs/source/img/setup/preferences/Prefs-Materials.png new file mode 100644 index 000000000..a549c69b2 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Materials.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Simulation.png b/docs/source/img/setup/preferences/Prefs-Simulation.png new file mode 100644 index 000000000..7e3c735f0 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Simulation.png differ diff --git a/docs/source/img/setup/preferences/Prefs-Units.png b/docs/source/img/setup/preferences/Prefs-Units.png new file mode 100644 index 000000000..890e5c824 Binary files /dev/null and b/docs/source/img/setup/preferences/Prefs-Units.png differ diff --git a/docs/source/img/setup/preferences/Theme-Dark.png b/docs/source/img/setup/preferences/Theme-Dark.png new file mode 100644 index 000000000..7dad66761 Binary files /dev/null and b/docs/source/img/setup/preferences/Theme-Dark.png differ diff --git a/docs/source/img/setup/preferences/Theme-DarkContrast.png b/docs/source/img/setup/preferences/Theme-DarkContrast.png new file mode 100644 index 000000000..c1d28e6ff Binary files /dev/null and b/docs/source/img/setup/preferences/Theme-DarkContrast.png differ diff --git a/docs/source/img/setup/preferences/Theme-Light.png b/docs/source/img/setup/preferences/Theme-Light.png new file mode 100644 index 000000000..9503aff79 Binary files /dev/null and b/docs/source/img/setup/preferences/Theme-Light.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/ChoosePlotVariable.png b/docs/source/img/user_guide/advanced_flight_simulation/ChoosePlotVariable.png new file mode 100644 index 000000000..1f45abeab Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/ChoosePlotVariable.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot.png b/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot.png new file mode 100644 index 000000000..9a8c5056a Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot2.png b/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot2.png new file mode 100644 index 000000000..42ca7ae7d Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/ComplexPlot2.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationLaunchCond.png b/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationLaunchCond.png new file mode 100644 index 000000000..0ae91308a Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationLaunchCond.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationSimOpts.png b/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationSimOpts.png new file mode 100644 index 000000000..c038079b2 Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/EditSimulationSimOpts.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/ExportData.png b/docs/source/img/user_guide/advanced_flight_simulation/ExportData.png new file mode 100644 index 000000000..1f6def715 Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/ExportData.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/PlotConfigs.png b/docs/source/img/user_guide/advanced_flight_simulation/PlotConfigs.png new file mode 100644 index 000000000..f4491c295 Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/PlotConfigs.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/PlotExportButton.png b/docs/source/img/user_guide/advanced_flight_simulation/PlotExportButton.png new file mode 100644 index 000000000..a04ea6e3f Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/PlotExportButton.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/PlotExportWindow.png b/docs/source/img/user_guide/advanced_flight_simulation/PlotExportWindow.png new file mode 100644 index 000000000..c6e9dd69c Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/PlotExportWindow.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/PlotOfSimulation.png b/docs/source/img/user_guide/advanced_flight_simulation/PlotOfSimulation.png new file mode 100644 index 000000000..24b85e9c1 Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/PlotOfSimulation.png differ diff --git a/docs/source/img/user_guide/advanced_flight_simulation/YaxisTypes.png b/docs/source/img/user_guide/advanced_flight_simulation/YaxisTypes.png new file mode 100644 index 000000000..dcbe11e52 Binary files /dev/null and b/docs/source/img/user_guide/advanced_flight_simulation/YaxisTypes.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/ClusterAft.png b/docs/source/img/user_guide/advanced_rocket_design/ClusterAft.png new file mode 100644 index 000000000..b30e2de2d Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/ClusterAft.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/ClusterTab.png b/docs/source/img/user_guide/advanced_rocket_design/ClusterTab.png new file mode 100644 index 000000000..e56187a13 Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/ClusterTab.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/Featherweight.png b/docs/source/img/user_guide/advanced_rocket_design/Featherweight.png new file mode 100644 index 000000000..6a6973b12 Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/Featherweight.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/RingTail.png b/docs/source/img/user_guide/advanced_rocket_design/RingTail.png new file mode 100644 index 000000000..5f6048db6 Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/RingTail.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/TubeFins.png b/docs/source/img/user_guide/advanced_rocket_design/TubeFins.png new file mode 100644 index 000000000..e89749e4e Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/TubeFins.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/Unicon.png b/docs/source/img/user_guide/advanced_rocket_design/Unicon.png new file mode 100644 index 000000000..16ac839eb Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/Unicon.png differ diff --git a/docs/source/img/user_guide/advanced_rocket_design/Xkcd_whatif_24_model_suborbital.png b/docs/source/img/user_guide/advanced_rocket_design/Xkcd_whatif_24_model_suborbital.png new file mode 100644 index 000000000..cfd69d876 Binary files /dev/null and b/docs/source/img/user_guide/advanced_rocket_design/Xkcd_whatif_24_model_suborbital.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/NewConfiguration.png b/docs/source/img/user_guide/basic_flight_simulation/NewConfiguration.png new file mode 100644 index 000000000..cacaa09c2 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/NewConfiguration.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/OptimumDelay.png b/docs/source/img/user_guide/basic_flight_simulation/OptimumDelay.png new file mode 100644 index 000000000..5c64efdf8 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/OptimumDelay.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/RunAll.png b/docs/source/img/user_guide/basic_flight_simulation/RunAll.png new file mode 100644 index 000000000..305d8e425 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/RunAll.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/RunOne.png b/docs/source/img/user_guide/basic_flight_simulation/RunOne.png new file mode 100644 index 000000000..786ba03ad Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/RunOne.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/SelectAnyMotor.png b/docs/source/img/user_guide/basic_flight_simulation/SelectAnyMotor.png new file mode 100644 index 000000000..20b2c04dd Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/SelectAnyMotor.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/ShowDetails.png b/docs/source/img/user_guide/basic_flight_simulation/ShowDetails.png new file mode 100644 index 000000000..b879e8b19 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/ShowDetails.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/SimOverview.png b/docs/source/img/user_guide/basic_flight_simulation/SimOverview.png new file mode 100644 index 000000000..2e1014a01 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/SimOverview.png differ diff --git a/docs/source/img/user_guide/basic_flight_simulation/SimResults.png b/docs/source/img/user_guide/basic_flight_simulation/SimResults.png new file mode 100644 index 000000000..ab11f2411 Binary files /dev/null and b/docs/source/img/user_guide/basic_flight_simulation/SimResults.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/01.New_Design.png b/docs/source/img/user_guide/basic_rocket_design/01.New_Design.png new file mode 100644 index 000000000..e61e8d136 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/01.New_Design.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/02.Body_tube_configuration.png b/docs/source/img/user_guide/basic_rocket_design/02.Body_tube_configuration.png new file mode 100644 index 000000000..8c73376f1 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/02.Body_tube_configuration.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/03.Motor_tube_tab.png b/docs/source/img/user_guide/basic_rocket_design/03.Motor_tube_tab.png new file mode 100644 index 000000000..4cd8e9bdc Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/03.Motor_tube_tab.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/04.Body_tube_override_tab.png b/docs/source/img/user_guide/basic_rocket_design/04.Body_tube_override_tab.png new file mode 100644 index 000000000..a251250e2 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/04.Body_tube_override_tab.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/05.Body_tube_appearance_tab.png b/docs/source/img/user_guide/basic_rocket_design/05.Body_tube_appearance_tab.png new file mode 100644 index 000000000..aff5206db Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/05.Body_tube_appearance_tab.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/06.Body_tube_comment_tab.png b/docs/source/img/user_guide/basic_rocket_design/06.Body_tube_comment_tab.png new file mode 100644 index 000000000..a0032e9a6 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/06.Body_tube_comment_tab.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/07.Component_menu.png b/docs/source/img/user_guide/basic_rocket_design/07.Component_menu.png new file mode 100644 index 000000000..4521396ec Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/07.Component_menu.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/08.Assembly_Components_Icons.png b/docs/source/img/user_guide/basic_rocket_design/08.Assembly_Components_Icons.png new file mode 100644 index 000000000..201f0f995 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/08.Assembly_Components_Icons.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/AddedMass.png b/docs/source/img/user_guide/basic_rocket_design/AddedMass.png new file mode 100644 index 000000000..652e4ba0a Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/AddedMass.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/After_complete_design.png b/docs/source/img/user_guide/basic_rocket_design/After_complete_design.png new file mode 100644 index 000000000..619b1c027 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/After_complete_design.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/BodyComplete.png b/docs/source/img/user_guide/basic_rocket_design/BodyComplete.png new file mode 100644 index 000000000..c12608f51 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/BodyComplete.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/CenteringRings.png b/docs/source/img/user_guide/basic_rocket_design/CenteringRings.png new file mode 100644 index 000000000..3cf6c518d Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/CenteringRings.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ComponentBodyAndFins.png b/docs/source/img/user_guide/basic_rocket_design/ComponentBodyAndFins.png new file mode 100644 index 000000000..11152fd63 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ComponentBodyAndFins.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ComponentInner.png b/docs/source/img/user_guide/basic_rocket_design/ComponentInner.png new file mode 100644 index 000000000..1c2e5380b Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ComponentInner.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ComponentMasses.png b/docs/source/img/user_guide/basic_rocket_design/ComponentMasses.png new file mode 100644 index 000000000..fa0aecc2a Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ComponentMasses.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ConfigNose.png b/docs/source/img/user_guide/basic_rocket_design/ConfigNose.png new file mode 100644 index 000000000..adedc346e Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ConfigNose.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/EngineBlockCompleted.png b/docs/source/img/user_guide/basic_rocket_design/EngineBlockCompleted.png new file mode 100644 index 000000000..96f842264 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/EngineBlockCompleted.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/FinsComplete.png b/docs/source/img/user_guide/basic_rocket_design/FinsComplete.png new file mode 100644 index 000000000..ab94cba40 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/FinsComplete.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/LaunchLugAdded.png b/docs/source/img/user_guide/basic_rocket_design/LaunchLugAdded.png new file mode 100644 index 000000000..966f8f7d6 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/LaunchLugAdded.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/MotorConfigs.png b/docs/source/img/user_guide/basic_rocket_design/MotorConfigs.png new file mode 100644 index 000000000..5bf13f4c9 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/MotorConfigs.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/MotorSelection.png b/docs/source/img/user_guide/basic_rocket_design/MotorSelection.png new file mode 100644 index 000000000..ec2a842aa Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/MotorSelection.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/NoseComplete.png b/docs/source/img/user_guide/basic_rocket_design/NoseComplete.png new file mode 100644 index 000000000..18e707579 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/NoseComplete.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/OpenExample.png b/docs/source/img/user_guide/basic_rocket_design/OpenExample.png new file mode 100644 index 000000000..04a3008c4 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/OpenExample.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ParachuteAdded.png b/docs/source/img/user_guide/basic_rocket_design/ParachuteAdded.png new file mode 100644 index 000000000..884a1eb64 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ParachuteAdded.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/ShockCordComplete.png b/docs/source/img/user_guide/basic_rocket_design/ShockCordComplete.png new file mode 100644 index 000000000..90dcc3e4d Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/ShockCordComplete.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/Structure.png b/docs/source/img/user_guide/basic_rocket_design/Structure.png new file mode 100644 index 000000000..4036afce4 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/Structure.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/body_tube_config.png b/docs/source/img/user_guide/basic_rocket_design/body_tube_config.png new file mode 100644 index 000000000..8c73376f1 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/body_tube_config.png differ diff --git a/docs/source/img/user_guide/basic_rocket_design/main_window.png b/docs/source/img/user_guide/basic_rocket_design/main_window.png new file mode 100644 index 000000000..e61e8d136 Binary files /dev/null and b/docs/source/img/user_guide/basic_rocket_design/main_window.png differ diff --git a/docs/source/img/user_guide/custom_expressions/Custom_expressions.png b/docs/source/img/user_guide/custom_expressions/Custom_expressions.png new file mode 100644 index 000000000..8c4955a37 Binary files /dev/null and b/docs/source/img/user_guide/custom_expressions/Custom_expressions.png differ diff --git a/docs/source/img/user_guide/custom_expressions/Expression_builder.png b/docs/source/img/user_guide/custom_expressions/Expression_builder.png new file mode 100644 index 000000000..052762ea6 Binary files /dev/null and b/docs/source/img/user_guide/custom_expressions/Expression_builder.png differ diff --git a/docs/source/img/user_guide/simulation_extensions/Air-start-configuration.png b/docs/source/img/user_guide/simulation_extensions/Air-start-configuration.png new file mode 100644 index 000000000..35ae30a66 Binary files /dev/null and b/docs/source/img/user_guide/simulation_extensions/Air-start-configuration.png differ diff --git a/docs/source/img/user_guide/simulation_extensions/Air-start-pane.png b/docs/source/img/user_guide/simulation_extensions/Air-start-pane.png new file mode 100644 index 000000000..21a163c9d Binary files /dev/null and b/docs/source/img/user_guide/simulation_extensions/Air-start-pane.png differ diff --git a/docs/source/img/user_guide/simulation_extensions/Example_Configurator.png b/docs/source/img/user_guide/simulation_extensions/Example_Configurator.png new file mode 100644 index 000000000..96623dbae Binary files /dev/null and b/docs/source/img/user_guide/simulation_extensions/Example_Configurator.png differ diff --git a/docs/source/img/user_guide/simulation_extensions/Extension-menu.png b/docs/source/img/user_guide/simulation_extensions/Extension-menu.png new file mode 100644 index 000000000..7a884da94 Binary files /dev/null and b/docs/source/img/user_guide/simulation_extensions/Extension-menu.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..402fe17dd --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,63 @@ +Welcome to OpenRocket's documentation! +====================================== + +**OpenRocket** is a free, fully featured model rocket simulator that allows you to design and simulate your rockets before building and flying them. + +.. note:: + + This documentation is under active development. + +.. toctree:: + :maxdepth: 1 + :caption: Introduction + + introduction/overview + introduction/features + introduction/contribute + introduction/FAQ + +.. toctree:: + :maxdepth: 1 + :caption: Setup + + setup/installation + setup/getting_started + setup/preferences + +.. toctree:: + :maxdepth: 1 + :caption: User Guide + + user_guide/basic_rocket_design + user_guide/basic_flight_simulation + user_guide/advanced_rocket_design + user_guide/advanced_flight_simulation + user_guide/overrides_and_surface_finish + user_guide/rocket_analysis + user_guide/custom_expressions + user_guide/simulation_extensions + user_guide/thrust_curves + +.. toctree:: + :maxdepth: 1 + :caption: Developer Guide + + dev_guide/development_overview + dev_guide/development_setup + /dev_guide/architecture + /dev_guide/codebase_walkthrough + /dev_guide/development_guidelines + /dev_guide/testing_and_debugging + /dev_guide/api_documentation + /dev_guide/building_releasing + /dev_guide/contributing_to_translations + /dev_guide/contributing_to_the_docs + /dev_guide/contributing_to_the_website + /dev_guide/faq_troubleshooting + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/introduction/FAQ.rst b/docs/source/introduction/FAQ.rst new file mode 100644 index 000000000..a665dd284 --- /dev/null +++ b/docs/source/introduction/FAQ.rst @@ -0,0 +1,3 @@ +************************** +Frequently Asked Questions +************************** diff --git a/docs/source/introduction/contribute.rst b/docs/source/introduction/contribute.rst new file mode 100644 index 000000000..9f62616e1 --- /dev/null +++ b/docs/source/introduction/contribute.rst @@ -0,0 +1,5 @@ +********** +Contribute +********** + + diff --git a/docs/source/introduction/features.rst b/docs/source/introduction/features.rst new file mode 100644 index 000000000..6ec776206 --- /dev/null +++ b/docs/source/introduction/features.rst @@ -0,0 +1,577 @@ +******** +Features +******** + +This page lists the current features of OpenRocket and compares them to those of RockSim. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Current features (as of OpenRocket 23.09): +========================================== + +General +------- + +* Fully cross-platform, written in Java + +* `Fully documented simulation methods `__ + +* Open Source (see our `GitHub repository `), source code available under the `GNU GPL `__ + +* Export OpenRocket design file to other simulation programs (RockSim, RASAero II) + +* Export component(s) to OBJ file for 3D printing + +* Extensible with custom simulation listeners, expressions, and plugins + +User Interface +-------------- + +* **Intuitive user interface** + +* **Real-time view of CG and CP** position + +* **Real-time flight altitude, velocity and acceleration** information from a continuous simulation performed in the background + +* Zoomable schematic view of rocket from the side or rear, with rotation around the center axis + +Design +------ + +* A multitude of available components to choose from + +* **Trapezoidal, elliptical, free-form and tube fins** supported + +* Support for **canted** fins (roll stabilization) + +* **Staging** and **clustering** support + +* **Pods** support + +* Automatic calculation of component mass and CG based on shape and density + +* Ability to **override mass, CG and CD** of components or stages separately + +Simulation and Analysis +----------------------- + +* Full **six degree of freedom** simulation + +* Rocket stability computed using **extended Barrowman** method + +* **Automatic design optimization** β€” *you can optimize any number of rocket parameters for flight altitude, maximum velocity or a number of other values* + +* Realistic wind modeling + +* Analysis of the **effect of separate components** on the stability, drag and roll characteristics of the rocket + +* **Fully configurable plotting**, with various preset configurations + +* Simulation data can be **exported to CSV** files for further analysis + +* **Simulation listeners** allowing custom-made code to interact with the rocket during flight simulation + +.. raw:: html + +
+ +Planned Future Features +======================= + +.. note:: + OpenRocket is under constant work in the free time of the developers. If you want to **help improve it**, please refer to the :doc:`Contribute page `. + +Below are a few major features that are under consideration: + +* Better support for transonic and supersonic simulations (:doc:`help needed! `) + +* Monte Carlo simulation for dispersion analysis + +* Simulate fin flutter + +* Customized support for hybrid rocket motors and water rockets + +* Importing and plotting actual flight data from altimeters + +* Rocket flight animation + +* A β€œwizard” for creating new rocket designs + +* More advanced rocket optimization methods + +* Import CD and CP data from other programs (e.g. RASAero) + +For a full overview of the planned features, please refer to the `GitHub issue tracker `__. + +.. raw:: html + +
+ +Comparison to RockSim +===================== + +`RockSim `__ is a very powerful, commercial rocket design and simulation program. +It is more advanced than OpenRocket in some regards, but its price tag of $124 makes it inaccessible to many hobbyists. +OpenRocket is free, and the source code is available for modification by anyone. +To help you decide which program is right for you, we have compiled a comparison of the features of OpenRocket 23.09 and RockSim 10 below. + +While hosted on the OpenRocket documentation, we have attempted to make this an objective comparison between the functionality +of the two software products. If you think something is wrong or omitted, please `contact us `__. + +General +------- + +.. list-table:: OpenRocket vs. RockSim: General + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - License + - .. cssclass:: or-table-cell, or-table-good + + | Open Source (GPLv3) + + - .. cssclass:: or-table-cell, or-table-poor + + | Proprietary + + * - Price + - .. cssclass:: or-table-cell, or-table-good + + | Free + + - .. cssclass:: or-table-cell, or-table-poor + + | $124 + + * - Supported platforms + - .. cssclass:: or-table-cell, or-table-good + + | Windows, Mac, Linux + + - .. cssclass:: or-table-cell, or-table-okay + + | Windows, Mac + + * - Supported file formats + - .. cssclass:: or-table-cell, or-table-good + + | ORK, RKT, CDX1 + + - .. cssclass:: or-table-cell, or-table-poor + + | RKT + + * - Anti-piracy copy protection + - .. cssclass:: or-table-cell, or-table-good + + | None + + - .. cssclass:: or-table-cell, or-table-okay + + | `PACE `__ + +UI Features +----------- + +.. list-table:: OpenRocket vs. RockSim: UI Features + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - Side/back view + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - 3D view + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Photorealistic 3D rendering + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Export 3D design + - .. cssclass:: or-table-cell, or-table-good + + | Yes (OBJ) + + - .. cssclass:: or-table-cell, or-table-good + + | Yes (3DS) + + * - Design view rotation + - .. cssclass:: or-table-cell, or-table-good + + | Any angle + + - .. cssclass:: or-table-cell, or-table-poor + + | Side and top only + + * - Live CG/CP view + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Realtime simulation + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + +Design Features +--------------- + +.. list-table:: OpenRocket vs. RockSim: Design Features + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - Basic components + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Freeform fins + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Asymmetric fin configurations + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Tube fins + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Ring-tail fins + - .. cssclass:: or-table-cell, or-table-bad + + | No + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Fins attached to fins + - .. cssclass:: or-table-cell, or-table-bad + + | No + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - External pods + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Canted fins / roll stabilization + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Standard component libraries + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Decals + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Clustering support + - .. cssclass:: or-table-cell, or-table-good + + | Yes, modifiable + + - .. cssclass:: or-table-cell, or-table-okay + + | Yes, one-time wizard only + + * - Staging support + - .. cssclass:: or-table-cell, or-table-good + + | Yes, unlimited + + - .. cssclass:: or-table-cell, or-table-okay + + | Yes, 3 stages + +Simulation Features +------------------- + +.. list-table:: OpenRocket vs. RockSim: Simulation Features + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - Degrees of freedom + - .. cssclass:: or-table-cell, or-table-good + + | 6DOF + + - .. cssclass:: or-table-cell, or-table-okay + + | 3DOF + + * - Geodetic calculation (Earth coordinates, coriolis effect) + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Simulations extensible by own code + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Simulation animation + - .. cssclass:: or-table-cell, or-table-bad + + | No + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Plotting any simulated variables + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Exporting simulated data + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Computing custom variables + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + +Optimization and Analysis +------------------------- + +.. list-table:: OpenRocket vs. RockSim: Optimization and Analysis + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - General design optimization + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Mass optimization + - .. cssclass:: or-table-cell, or-table-okay + + | Yes (using general optimizer) + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Stability analysis + - .. cssclass:: or-table-cell, or-table-good + + | Yes, per component + + - .. cssclass:: or-table-cell, or-table-okay + + | Yes, per stage + + * - Drag analysis + - .. cssclass:: or-table-cell, or-table-good + + | Yes, per component + + - .. cssclass:: or-table-cell, or-table-poor + + | Yes, per stage + + * - Roll analysis + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + +Printing +-------- + +.. list-table:: OpenRocket vs. RockSim: Printing + :widths: 20 20 20 + :header-rows: 1 + :class: or-table + + * - + - OpenRocket + - RockSim + * - Schematic view + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Stability information + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Simulation results + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Parts list + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + * - Component templates + - .. cssclass:: or-table-cell, or-table-good + + | Nose cone, fin sets, centering rings + + - .. cssclass:: or-table-cell, or-table-good + + | Nose cone, fin sets, centering rings + + * - Fin placement guide + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No + + * - Export to PDF + - .. cssclass:: or-table-cell, or-table-good + + | Yes + + - .. cssclass:: or-table-cell, or-table-bad + + | No diff --git a/docs/source/introduction/overview.rst b/docs/source/introduction/overview.rst new file mode 100644 index 000000000..cd89a7b23 --- /dev/null +++ b/docs/source/introduction/overview.rst @@ -0,0 +1,54 @@ +******** +Overview +******** + +What is OpenRocket? +=================== + +.. figure:: /img/openrocket_logo_256.png + :figclass: or-figclass + :figwidth: 25 % + :align: right + + The OpenRocket Logo + +Welcome! OpenRocket is an open-source model rocket simulation software application. It was originally developed by +Sampo Niskanen in 2009 as part of his master thesis at what was then `Helsinki University of Technology `__. +If you want to have a look at his thesis you can download it from `OpenRocket's technical documentation page `__. +Written entirely in Java, OpenRocket is fully cross-platform. To install the software, please refer to the :doc:`Installation Instructions ` + +.. rst-class:: clear-both + +OpenRocket is intended to be used by rocketeers who want to test the performance of a model rocket before actually +building and flying it. The software accurately computes the aerodynamic properties of rockets and simulates their flight, +returning a wide range of technical results. + +The program can be roughly divided into two sections: + +* **Rocket design**: In this phase, you can design the model rocket you intend to build, choosing from a wide range of \ + **body components**, **trapezoidal**, **elliptical**, and **free-form fins**, **inner components**, and **mass objects**. \ + During this phase, you will see a 2D representation of the rocket you are building and various technical information, \ + *such as size, mass, apogee, max. velocity, max. acceleration, stability, center of gravity (CG), and center of pressure \ + (CP)* about your rocket. This allows you to have a good idea of its performance even before running any simulation. + +* **Flight simulation**: In this phase, you can run one or more simulations of your rocket's flight, choosing from one \ + or more **motor configurations**. Each simulation, calculated using the Runge-Kutta 4 simulator, returns a wide range \ + of data about the rocket's flight. Unfortunately, for the moment, a graphical visualization of the rocket's flight is \ + not available (`help needed `__). + + +For more information about OpenRocket's features and a few screenshots you can have a look `here `__. + +How this Documentation is Organized +=================================== + +.. attention:: + + This documentation is still a work in progress, so **some sections may be incomplete**. If you want to help us improve it, please refer to the :doc:`Contribute section `. + +This documentation is organized in 4 main sections: + +#. **Introduction**: this section contains general information about OpenRocket, such as its history, its features, and how to contribute to the project. +#. **Setup**: this section contains information about how to install and run OpenRocket on your computer. +#. **User Guide**: this section contains information about how to use OpenRocket to design and simulate your model rockets. +#. **Developer Guide**: this section contains information about how to contribute to the development of OpenRocket. diff --git a/docs/source/setup/getting_started.rst b/docs/source/setup/getting_started.rst new file mode 100644 index 000000000..cf0def8c1 --- /dev/null +++ b/docs/source/setup/getting_started.rst @@ -0,0 +1,800 @@ +*************** +Getting Started +*************** + +In this section we have a look at how OpenRocket is organized, by analyzing in detail the structure of the **user interface**. +We will also briefly mention the **Example projects** that are accessible from the *File* menu. After reading this section +you will have a thorough understanding of how OpenRocket is structured, and will be ready to start designing a rocket of +your own. If you already know how this program is organized, feel free to jump to :doc:`Basic Rocket Design `, +the next section. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +.. _the_user_interface: + +The User interface +================== + +The OpenRocket user interface is divided horizontally into four sections: + +- :guilabel:`Main Menu` (green) +- :guilabel:`Task Tabs` (black) +- :guilabel:`Rocket Design`, :guilabel:`Motors & Configuration`, and :guilabel:`Flight Simulation Pane` (red) +- :guilabel:`Rocket Views Pane` (blue) + +.. figure:: /img/setup/getting_started/2023.01.Guide.User_Interface.png + :width: 95% + :align: center + :figclass: or-image-border + + UI of OpenRocket divided into four + +Main Menu +--------- + +The **Main Menu**, sometimes referred to as the **Menu Bar** or **Application Ribbon**, is located at the top of the OpenRocket +window. On macOS, the main menu is located at the top of the screen, embedded in the native macOS menu bar. We will run through +each of the menu options in the main menu. + +File +^^^^ + +.. figure:: /img/setup/getting_started/02.04.01.File_Menu.png + :width: 35% + :align: center + :figclass: or-image-border + + The OpenRocket File Menu + +The **File Menu** is divided into five divisions by function: + +1. **File opening options**: + - :guilabel:`New`: Start a new project without closing the current one. + - :guilabel:`Open...`: Open a previously saved `*.ork` file. + - :guilabel:`Open Recent`: Open a recently opened file. + - :guilabel:`Open Example`: Select and open an example project included with OpenRocket. +2. **File saving options**: + - :guilabel:`Save`: Save changes to the current project. + - :guilabel:`Save as...`: Save the project with a different filename or location. +3. **Import and export options**: + - :guilabel:`Export as`: Export the project to a different file format, such as Rocksim 10 (`.rkt`). + - :guilabel:`Save decal image`: Save a decal image file used in the project. + - :guilabel:`Print design info...`: Print or export technical details of the rocket's components, fin set templates, or the rocket design to a `*.pdf`. +4. **Closing**: + - :guilabel:`Close design`: Exit the current project (prompts to save unsaved changes). +5. **Quitting**: + - :guilabel:`Quit`: Exit OpenRocket, saving each open project if necessary. + +Edit +^^^^ + +.. figure:: /img/setup/getting_started/OR.Guide.User_Interface.04.02.File.png + :width: 35% + :align: center + :figclass: or-image-border + + The OpenRocket Edit Menu + +The **Edit Menu** is divided into three types of operations: + +1. :guilabel:`Undo` and :guilabel:`Redo` an action +2. :guilabel:`Cut`, :guilabel:`Copy`, :guilabel:`Paste`, and :guilabel:`Delete` objects +3. :guilabel:`Scale`: scale components or the entire rocket.button +4. :guilabel:`Preferences`: access OpenRocket system preferences + +Tools +^^^^^ + +.. figure:: /img/setup/getting_started/OR.Guide.User_Interface.04.03.File.png + :width: 35% + :align: center + :figclass: or-image-border + + The OpenRocket Tools Menu + +The **Tools Menu** provides the following design tools: + +- :guilabel:`Component Analysis`: Analyze the (aerodynamic) effect of specific components +- :guilabel:`Rocket optimization`: Optimize particular rocket characteristics +- :guilabel:`Custom expressions`: Create custom expressions for specialized analysis +- :guilabel:`Photo Studio`: Display the rocket in 3D with a variety of backgrounds and effects in the photo studio + +Help +^^^^ + +.. figure:: /img/setup/getting_started/OR.Guide.User_Interface.04.04.File.png + :width: 25% + :align: center + :figclass: or-image-border + + The OpenRocket Help Menu + +The **Help Menu** is divided into three sections: + +1. :guilabel:`Guided tours`: demonstrating the use of OpenRocket +2. :guilabel:`Bug reporting` and :guilabel:`Debug log`: tools to assist users in providing feedback to the developers +3. :guilabel:`License` and :guilabel:`About`: other general information about OpenRocket + +Task Tabs +--------- + +The windows shown below utilize the *A simple model rocket* example included with OpenRocket. + +Rocket Design +^^^^^^^^^^^^^ + +.. figure:: /img/setup/getting_started/01.02.Rocket_Design.Tab.png + :width: 95% + :align: center + :figclass: or-image-border + +The **Rocket Design** tab is divided into three sections: + +- *(Left)* The :guilabel:`Component tree`: A tree view of the components that make up the rocket. +- *(Middle)* :guilabel:`Component action buttons`: Buttons to for instance edit, move, or delete the currently selected components. +- *(Right)* :guilabel:`Component addition buttons`: Buttons to add new components to the rocket. + +The components available in OpenRocket are divided into four classes based upon component function: + +1. **Assembly Components** +2. **Body Components and Fin Sets** (external components) +3. **Internal Components** +4. **Mass Components** (which include electronics and recovery components) + +Components are "greyed out" until it would be appropriate to add that component type to the currently selected component in +the component tree. For example, if you selected a fin set component in the component tree, then the nose cone component button +will be greyed out, because you can not add a nose cone to a fin set. As components are added, you will +see the component tree (on the left side of the window) grow with each component added. + +.. todo:: + For a detailed description of each component, see \:ref\:\`Component Details \`. + +Motors & Configuration +^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: /img/setup/getting_started/02.02.Motor-Configuration.Tab.png + :width: 95% + :align: center + :figclass: or-image-border + +The **Motors & Configurations** tab is where you select motors, recovery events, and stage timing. Motor configuration options include: + +- :guilabel:`New Configuration`: Create a new flight configuration +- :guilabel:`Rename Configuration`: Rename the currently selected configuration +- :guilabel:`Remove Configuration`: Remove the currently selected configuration +- :guilabel:`Copy Configuration`: Copy the currently selected configuration + +With a specific configuration selected, you may: + +- :guilabel:`Select motor`: Choose a motor from the motor database for the currently selected motor mount. +- :guilabel:`Remove motor`: Remove the currently selected motor from the motor mount. +- :guilabel:`Select ignition`: Set the motor ignition timing for the current motor. +- :guilabel:`Reset ignition`: Reset the motor ignition timing for the current motor to the default values. + +.. todo:: + For more motors and configuration utilization details, see \:ref\:\`Motors & Configuration Details \`. + +Flight Simulations +^^^^^^^^^^^^^^^^^^ + +.. figure:: /img/setup/getting_started/03.02.Flight_simulations.Tab.png + :width: 95% + :align: center + :figclass: or-image-border + +The **Flight Simulations** tab is where you manage and run flight simulations and flight simulation plots. From here, +you can add new simulations, or edit, run, or delete existing simulations. Select a single simulation, and you can +even plot and export the simulation results. + +.. todo:: + For more details on how to use these functions, see \:ref\:\`Flight Simulations Details \`. + +Rocket Views +------------ + +The windows shown below utilize the *A simple model rocket* example included with OpenRocket. + +Top/Side/Back View +^^^^^^^^^^^^^^^^^^ + +The **Top View**, **Side View**, and **Back View** are line drawings, similar to a blueprint that shows all of the rocket +components and the placement of those components. Almost all of your design work will take place in the top, side, and back views. + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.Top_View.jpg + :width: 95% + :align: center + :figclass: or-image-border + + Top view. + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.Side_View.jpg + :width: 95% + :align: center + :figclass: or-image-border + + Side view. + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.Back_View.jpg + :width: 95% + :align: center + :figclass: or-image-border + + Back view. + +3D Figure/3D Unfinished +^^^^^^^^^^^^^^^^^^^^^^^ + +The **3D Figure** and **3D Unfinished** view allow you to look through the rocket's exterior to view many of the interior +components. These views can help you more clearly see the relationship between the placement of different components +inside the airframe. + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.3D_Figure.jpg + :width: 95% + :align: center + :figclass: or-image-border + + 3D Figure view. + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.3D_Unfinished.jpg + :width: 95% + :align: center + :figclass: or-image-border + + 3D Unfinished view. + +3D Finished +^^^^^^^^^^^ + +The **3D Finished** view shows you what the rocket will look like when finished. OpenRocket allows you to select +component colors, inside and outside of outer tubes, right side or left side of fins, and even creating transparent +components, all with or without decals (transparent or opaque). + +.. figure:: /img/setup/getting_started/Getting_Started.Rocket_Views.3D_Finished.jpg + :width: 95% + :align: center + :figclass: or-image-border + + 3D Finished view. + +Become Familiar with OpenRocket +------------------------------- + +For new users of OpenRocket, before attempting to create your own custom rocket design, it is strongly recommended that +you become familiar with the OpenRocket user interface and generally accepted rocket design principles by opening and +looking at how an example is assembled, making changes to the example, and understanding how to simulate flights. + +The example designs are found here: + +.. figure:: /img/setup/getting_started/2023.01.Open_Example.png + :width: 95% + :align: center + :figclass: or-image-border + + Where to find the example design files. + +OpenRocket currently includes the following example designs: + +- "Standard" designs: + - **A simple model rocket**: A basic rocket design. This is a good starting point for new users. The design contains all + the elements of a standard rocket design, including recovery and experimentation with different motors. + - **Two-stage rocket**: A two-stage rocket design + - **Three-stage rocket**: A three-stage rocket design + - **TARC payload rocket**: Demonstrates payload and booster sections with individual recovery systems deployed by motor ejection. + TARC = Team America Rocketry Challenge + - **3D Printable Nose Cone and Fins**: A rocket design to test exporting the nose cone and fins to an OBJ file for 3D printing. +- "Advanced" designs + - **Airstart timing**: Demonstrates the effect of different airstart timings on overall altitude. + - **Base drag hack (short-wide)**: Demonstrates the application of the "base drag" hack to adjust the center of pressure + for a short-wide rocket, one with a length to diameter ratio of less than 10:1. + - **Chute release**: A simple model rocket example adapted to use an electronic chute release. + - **Dual parachute deployment**: A standard fiberglass zipperless dual deploy rocket. + - **Clustered motors**: A rocket design with clustered motors. + - **Parallel booster staging**: Demonstrates parallel booster staging. + - **Pods--airframes and winglets**: Demonstrates two uses of pods, both for the traditional "wing pods", and also + using a phantom body tube to implement "fins on fins" for the horizontal stabilizer. + - **Pods--powered with recovery deployment**: Demonstrates the use of pods for powered recovery deployment. +- Designs using advanced simulations, such as extensions and scripting + - **Simulation extensions**: Demonstrates active roll control and air-start using simulation extensions. The main fins are slightly misaligned, which causes roll to occur. + - **Simulation scripting**: Demonstrates active roll control and air-start using simulation extension written in JavaScript. + +---- + +The Basics of Using OpenRocket +============================== + +Rocket Configuration +-------------------- + +To build your first rocket, start OpenRocket, then double click the **Rocket** label at the top of the component tree to +open the **Rocket configuration** pop-up window. OpenRocket allows you to name your design, identify the designer, make +comments, and create a revision history. + +The default design name is **Rocket**, but that name can be changed, and a design name change also changes the name of +the rocket shown on the component tree. So, rename your design and enter the designer, comments, and revision history +information you desire. + +1. Double-Click **Rocket** in the component tree + + .. figure:: /img/setup/getting_started/04.01.02.Rocket_Configuration.png + :width: 95% + :align: center + :figclass: or-image-border + + Open the rocket configuration window. + +2. Rename **Rocket** + + .. figure:: /img/setup/getting_started/04.01.05.Rocket_Configuration.Rename.png + :width: 95% + :align: center + :figclass: or-image-border + + Change the name of your rocket. + +Adding External Components +-------------------------- + +Now it's time to start putting together components to build the rocket design. The generally accepted way of putting +together a rocket design is from top to bottom, from nose to tail. So, we'll add the nose cone first. + +Adding a Nose Cone +^^^^^^^^^^^^^^^^^^^^^ + +With the **Stage** selected, click on the :guilabel:`Nose Cone` button and the **Nose Cone configuration** window will pop up. +Then, click the :guilabel:`Parts Library` button on the top-right of the configuration window. This will open a new window, +the **Component preset window**. From here, you can select a nose cone from a list of built-in nose cone presets from +various manufacturers. Select the nose cone shown below, and click the :guilabel:`Close` button to close the +**Nose Cone configuration** window. + +.. figure:: /img/setup/getting_started/11.01.03.Rocket_Build.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + Adding a nose cone to the rocket. + +.. figure:: /img/setup/getting_started/Getting_Started.Components.Nose_Cone.Parts_Library.Highlighted.jpg + :width: 95% + :align: center + :figclass: or-image-border + + Click the :guilabel:`Parts Library` button (top-right in the nose cone configuration window) to select a nose cone from the parts database. + +.. figure:: /img/setup/getting_started/Getting_Started.Components.Nose_Cone.jpg + :width: 95% + :align: center + :figclass: or-image-border + + The nose cone has been added to the rocket. + +Congratulations, you've just added your first component! πŸŽ‰ + +Adding a Payload Bay +^^^^^^^^^^^^^^^^^^^^ + +Next, we will add a payload bay after the nose cone. To do this, with either the **Stage** or **Nose Cone** selected, +click on the :guilabel:`Body Tube` button and the **Body Tube configuration** window will pop up. +Like with the nose cone, click :guilabel:`Parts Library` to open the **Component preset window**. +Select the body tube shown below, and click the :guilabel:`Close` button to close the **Body Tube configuration** window. + +.. figure:: /img/setup/getting_started/11.02.01.Rocket_Build.Payload_Bay.png + :width: 95% + :align: center + :figclass: or-image-border + + Adding a payload bay to the rocket. + +.. figure:: /img/setup/getting_started/11.02.05.Rocket_Build.Payload_Bay.png + :width: 95% + :align: center + :figclass: or-image-border + + Selecting a body tube from the parts database. + +.. figure:: /img/setup/getting_started/11.02.06.Rocket_Build.Payload_Bay.png + :width: 95% + :align: center + :figclass: or-image-border + + The payload bay has been added to the rocket. + +Adding a Transition +^^^^^^^^^^^^^^^^^^^ + +Transitions are most often used to connect body tubes with different diameters. But, a transition can also be used to +connect two body tubes of the same diameter, as will be done here. + +To do this, with either the **Stage** or **Payload Bay** selected, click on the :guilabel:`Transition` button and the +**Transition configuration** window will pop up. The default **Transition Configuration** tab is the **General** tab. +On this tab, change your entries in the circled areas below to match the entries shown. Then, click the **Shoulder** tab, +and change your entries in the circled areas below to match the entries shown. Then, click the :guilabel:`Close` button. + +.. figure:: /img/setup/getting_started/11.03.01.Rocket_Build.Transition.png + :width: 95% + :align: center + :figclass: or-image-border + + Adding a transition behind the payload bay. + +.. figure:: /img/setup/getting_started/11.03.06.Rocket_Build.Transition.png + :width: 95% + :align: center + :figclass: or-image-border + + Setting the transition parameters in the :guilabel:`General` tab and :guilabel:`Shoulder` tab. + +.. figure:: /img/setup/getting_started/11.03.07.Rocket_Build.Transition.png + :width: 95% + :align: center + :figclass: or-image-border + + The transition has been added to the rocket. + +Adding a Body Tube +^^^^^^^^^^^^^^^^^^ + +Now, do what you did to add the **Payload Bay**, above, but select this body tube from the parts database: + +.. figure:: /img/setup/getting_started/11.04.01.Rocket_Build.Body_Tube.png + :width: 65% + :align: center + :figclass: or-image-border + + Add another body tube, behind the transition, and select it from the parts database. + +.. figure:: /img/setup/getting_started/11.04.02.Rocket_Build.Body_Tube.png + :width: 95% + :align: center + :figclass: or-image-border + + The body tube has been added to the rocket. + +Adding Fins +^^^^^^^^^^^ + +The bottom component are the fins. OpenRocket offers four types of fins, **Trapezoidal**, **Elliptical**, **Free Form**, +and **Tube Fins**. For this design, **Trapezoidal** fins will be used. + +With the **Body Tube** selected, click on the :guilabel:`Trapezoidal` fins button and the **Trapezoidal Fin Set configuration** +window will pop up. On your default **General** tab, change your entries match the entries shown. Then, click the +:guilabel:`Close` button. + +.. figure:: /img/setup/getting_started/11.05.01.Rocket_Build.Fins.png + :width: 95% + :align: center + :figclass: or-image-border + + Add Trapezoidal fins inside the second body tube. + +.. figure:: /img/setup/getting_started/11.05.02.Rocket_Build.Fins.png + :width: 60% + :align: center + :figclass: or-image-border + + Fin set configuration window + +Fins attach to another component, in this case the **Body Tube**. As circled below, the fins are shown underneath the +**Body Tube** on the component tree. + +.. figure:: /img/setup/getting_started/11.05.03.Rocket_Build.Fins.png + :width: 95% + :align: center + :figclass: or-image-border + + Trapezoidal fin set added to the rocket. + +Adding a Launch Guide +^^^^^^^^^^^^^^^^^^^^^ + +OpenRocket includes two styles of launch guides, **Rail Buttons** and a **Launch Lug**. Because of the diameter of the +body tube, a **Launch Lug** will be used for this design. As with fins, launch guides attach to another component, in +this case the body tube. + +You should now be able to open the **Launch Lug configuration** window without assistance. So, open your **Launch Lug configuration** +window, and change the specifications to match those shown below. + +.. figure:: /img/setup/getting_started/11.06.02.Rocket_Build.Launch_Lug.png + :width: 60% + :align: center + :figclass: or-image-border + + Launch lug configuration window. + +.. figure:: /img/setup/getting_started/11.06.03.Rocket_Build.Launch_Lug.png + :width: 95% + :align: center + :figclass: or-image-border + + Launch lug added to the body tube. + +Adding a Parachute and Shock Cord +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Next we will add a **Parachute** and **Shock Cord** to the rocket for recovery. +Select the body tube and add a **Parachute** and **Shock Cord**. The parachute and shock cord attach to the body tube. + +.. figure:: /img/setup/getting_started/11.07.03.Rocket_Build.Parachute.png + :width: 95% + :align: center + :figclass: or-image-border + + Parachute parts library (left) and configuration window (right). + +.. figure:: /img/setup/getting_started/11.08.01.Rocket_Build.Parachute.png + :width: 60% + :align: center + :figclass: or-image-border + + Shock cord configuration window. + +.. figure:: /img/setup/getting_started/11.08.02.Rocket_Build.Parachute.png + :width: 95% + :align: center + :figclass: or-image-border + + Parachute and shock cord added to the body tube. + +Adding an Engine Block +^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: /img/setup/getting_started/11.09.01.Rocket_Build.Engine_Block.png + :width: 60% + :align: center + :figclass: or-image-border + + Engine block configuration window. + +.. figure:: /img/setup/getting_started/11.09.02.Rocket_Build.Engine_Block.png + :width: 95% + :align: center + :figclass: or-image-border + + Engine block added to the body tube. + +Viewing Your Design +=================== + +With the airframe complete, you can view your design in either 2D (as above) or three 3D views. The most commonly used +of which are **3D Unfinished** and **3D Finished**. + +.. figure:: /img/setup/getting_started/11.06.03.Rocket_Build.3D_Unfinished.png + :width: 95% + :align: center + :figclass: or-image-border + + 3D Unfinished view (body tubes are semi-transparent so that the internal components become visible). + +.. figure:: /img/setup/getting_started/11.06.04.Rocket_Build.3D_Finished.png + :width: 95% + :align: center + :figclass: or-image-border + + 3D Finished view (what your final build would look like). + +---- + +Adding Appearance Settings +========================== + +If you want your OpenRocket design to visually resemble what you want to build, you can change the appearance of the components. +When changing **Appearance** settings, it is best to be in the **3D Finished** pane so that you can see the changes that +you are making. So, let's start by changing the view to **3D Finished**. + +Changing Color +-------------- + +The first change that will be made is to select the color for and change the color of the nose cone. Double-click on the +nose cone in the parts tree to open the **Nose Cone configuration** window, then select the :guilabel:`Appearance` tab. + +.. figure:: /img/setup/getting_started/12.10.01.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + Nose cone :guilabel:`Appearance` tab in the configuration window. + +Now, uncheck the **Appearance** :guilabel:`Use default` box. Then, Click on the :guilabel:`Color` box to open the +**Choose color** window. Select the color of your choice (purple will be used here). Click :guilabel:`OK` to use your +selection, then :guilabel:`Close` the **Nose Cone configuration** window. + +.. figure:: /img/setup/getting_started/12.10.05.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + Changing the nose cone color. + +.. figure:: /img/setup/getting_started/12.10.06.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + Nose cone color changed. + +Repeat those steps for the **Transition**, **Body Tube**, **Trapezoidal Fin Set**, and **Launch Lug**; body tubes, launch lugs, and fins also have a **Texture** that will need to be set to **none**. + +.. figure:: /img/setup/getting_started/12.10.07.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + All external components, except for the payload bay have now been colored. + +Now for a little magic. Open the **Payload Bay** appearance tab, uncheck the **Appearance** **Use default** box, and set +the :guilabel:`Texture` to `````. Then, click on the :guilabel:`Color` box to open the **Choose color** window. +Click on a light blue color (the box shown with the **X** below), then click :guilabel:`OK`. Now, set the :guilabel:`Opacity` +to **20%** and close the Payload Bay configuration window, and you have a transparent payload bay. + +.. figure:: /img/setup/getting_started/12.10.11.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + Change the color of the payload bay to light blue and lower the opacity to 20%. + +.. figure:: /img/setup/getting_started/12.10.12.Rocket_Build_Appearance.Nose_Cone.png + :width: 95% + :align: center + :figclass: or-image-border + + You now have a semi-transparent payload bay! + +Adding Decals +------------- + +One last bit of magic, let's apply a decal to the transparent Payload Bay. + +But, before beginning, save the following image to your device. + +.. figure:: /img/setup/getting_started/12.10.13.Rocket_Build_Appearance.Decal.png + :width: 15% + :align: center + :figclass: or-image-border + + :download:`Save this decal image on your computer `. + +With the decal saved to your device, you're ready to start. + +Select Decal from File +^^^^^^^^^^^^^^^^^^^^^^ + +Open the Payload Bay configuration window and select the :guilabel:`Appearance` tab. Click on the :guilabel:`Texture` +type to activate the selection drop-down, and select :guilabel:`From file...`. Now, navigate to where you saved the decal, +and select it. + +.. figure:: /img/setup/getting_started/12.10.16.Rocket_Build_Appearance.Payload_Bay.Decal.png + :width: 95% + :align: center + :figclass: or-image-border + +Decal Type, Size and Position +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To size and position the decal, first change the **Repeat** type to **Sticker** (you only want one symbol on the Payload Bay), +then change the :guilabel:`Scale` and :guilabel:`Offset` :guilabel:`x` and :guilabel:`y` values to those shown below. + +.. figure:: /img/setup/getting_started/12.10.19.Rocket_Build_Appearance.Payload_Bay.Decal.png + :width: 95% + :align: center + :figclass: or-image-border + + Change the :guilabel:`Repeat` type and set the x and y :guilabel:`Scale` and :guilabel:`Offset` values. + +.. figure:: /img/setup/getting_started/12.10.20.Rocket_Build_Appearance.Payload_Bay.Decal.png + :width: 95% + :align: center + :figclass: or-image-border + + The decal has been added to the payload bay and sized and positioned correctly. + +And, there you have it, a decal on a transparent payload bay! + +So, let's see what you've learned, and extend your knowledge. See if you can follow the screens below without any instructions. +Save the following image to your device. + +.. figure:: /img/setup/getting_started/12.10.21.Rocket_Build_Appearance.Fins.png + :width: 15% + :align: center + :figclass: or-image-border + + :download:`Save this decal image on your computer `. + +.. figure:: /img/setup/getting_started/12.11.03.Rocket_Build_Appearance.Fins.png + :width: 95% + :align: center + :figclass: or-image-border + + Split the Fins in the **Trapezoidal Fin Set configuration window** (left). After splitting, you'll see the separate fin + instances in the component tree (right). + +After splitting the fins, **SAVE AND REOPEN THE DESIGN FILE**, then view in **3D Finished**. + +.. figure:: /img/setup/getting_started/12.11.11.Rocket_Build_Appearance.Fins.png + :width: 95% + :align: center + :figclass: or-image-border + + Change Appearance of **Fin #2** and **Fin #3** + +.. figure:: /img/setup/getting_started/12.11.12.Rocket_Build_Appearance.Fins.png + :width: 95% + :align: center + :figclass: or-image-border + +---- + +Viewing in Photo Studio +======================= + +So, what will this bird look like in flight? For that, we can use the **Photo Studio** tool. However, to get a representative +representation, you need to add a motor first. + +Selecting a Motor +----------------- + +In the :guilabel:`Task tabs` in the UI, select the :guilabel:`Motors & Configuration` tab. Then, make sure that the correct +motor tube is selected on the left in the :guilabel:`Motor mounts` list before clicking :guilabel:`New Configuration`. + +.. figure:: /img/setup/getting_started/12.12.02.Rocket_Build.Motor.png + :width: 95% + :align: center + :figclass: or-image-border + + Adding a new flight configuration in the :guilabel:`Motors & Configuration` tab. + +When you click :guilabel:`New Configuration`, the **Motor Selection** window opens. For this example, select the Estes D-12-7, +then click :guilabel:`OK`. + +.. figure:: /img/setup/getting_started/12.12.03.Rocket_Build.Motor.png + :width: 80% + :align: center + :figclass: or-image-border + + Selecting the Estes D-12-7 rocket motor in the **Motor Selection** window. + +Now, select the D-12-7 as the **Flight Configuration**, and you're ready to go to the **Photo Studio**. + +.. figure:: /img/setup/getting_started/12.12.05.Rocket_Build.Motor.png + :width: 95% + :align: center + :figclass: or-image-border + + Select the D-12-7 as the **Flight Configuration**. + +Flying in Photo Studio +---------------------- + +Are you ready to see your rocket fly? Then, open :guilabel:`Photo Studio` from the :menuselection:`Tools` menu. + +.. figure:: /img/setup/getting_started/12.12.01.Rocket_Build.Photo_Studio.png + :width: 95% + :align: center + :figclass: or-image-border + + Open **Photo Studio**. + +You can now view your creation in 3D and interact with it. You can change the background, rocket orientation, camera settings, +and even add some cool effects. + +.. figure:: /img/setup/getting_started/12.12.02.Rocket_Build.Photo_Studio.png + :width: 85% + :align: center + :figclass: or-image-border + + The rocket inside **Photo Studio**. + +So why did you to add a motor before going to Photo Studio? Because, +**you can't activate the flame effect in Photo Studio if your rocket does not have a motor**, and the flame effect is +arguably the coolest part of Photo Studio! Go to the :guilabel:`Effects` tab and enable the :guilabel:`Flame` effect. + +.. figure:: /img/setup/getting_started/12.12.03.Rocket_Build.Photo_Studio.png + :width: 85% + :align: center + :figclass: or-image-border + +Now, play around with the settings to your heart's content! diff --git a/docs/source/setup/installation.rst b/docs/source/setup/installation.rst new file mode 100644 index 000000000..d2359e38b --- /dev/null +++ b/docs/source/setup/installation.rst @@ -0,0 +1,207 @@ +************************* +Installation Instructions +************************* + +.. contents:: Table of Contents + :depth: 1 + :local: + :backlinks: none + +---- + +Introduction +============ + +OpenRocket is released in two forms: as a *packaged application* and as a *JAR file*. +**The easiest way to get OpenRocket up and running is to download and install one of the packaged installers.** +The packaged installers come with everything needed, including the correct version of Java; +*you will not need to install, update or downgrade Java on your device to run them.* + +Download the latest version from `our downloads page `__. + +.. raw:: html + +
+ +Pre-Installation Procedures +=========================== + +Some users may experience problems with the OpenRocket installation if they don't follow the pre-installation procedures below. + +Close All Instances of OpenRocket +--------------------------------- + +If you have OpenRocket running, close it before installing a new version. By default, new OpenRocket releases +install to the same location on your device; these releases even share preferences. Because of this, if OpenRocket is +open when you attempt to install an updated release, the installation may not update all of the files needed for +OpenRocket to function correctly. + +Before installing an update, you *MUST* close all open instances of OpenRocket. + +(Optional) Uninstall Prior OpenRocket Releases +---------------------------------------------- + +As described above, by default, new releases of OpenRocket install to the same location on your device. +Although **not expressly required**, it is suggested that all previously installed OpenRocket releases be uninstalled +before installing the updated release. This is *not required*, but is suggested to ensure the proper function of OpenRocket. + +.. raw:: html + +
+ +Installing OpenRocket πŸš€ +======================== + +**Download the latest version from** `our downloads page `__. +Scroll down to download the correct installer for your platform (Windows, macOS, or Linux). + +Each platform has a different installation process. Click on the ``Show installation instructions`` header under your +platform's download button to see the installation instructions. + +.. raw:: html + +
+ +After-Installation Checks +========================= + +After installing OpenRocket, you need to verify that the installation was successful and potentially modify some settings +to ensure that OpenRocket functions correctly. + +Verify the Installed Release Number +----------------------------------- + +First, verify that you actually installed the current release of OpenRocket. You can see this in the splash screen, which +appears when you start OpenRocket. The splash screen will show the release number on the right: + +.. figure:: /img/setup/installation/splash_screen.png + :alt: OpenRocket Splash Screen + :figclass: or-figclass + :figwidth: 60 % + :align: center + + During startup, the OpenRocket Splash Screen shows the release number on the right. + +If the release number is not correct, you may have installed the wrong version of OpenRocket, or didn't follow the +`Pre-Installation Procedures`_ above. + +Another way to check the release number is to open the ``Help`` menu in the application ribbon +and select ``About``. This will open a dialog box that shows the release number: + +.. figure:: /img/setup/installation/about_dialog.png + :alt: OpenRocket About Dialog + :figclass: or-figclass, or-image-border + :figwidth: 40 % + :align: center + + The OpenRocket About Dialog (``Help`` β†’ ``About``) shows the release number. + +Check the Settings +------------------ + +For most users, OpenRocket's default settings will work fine. However, some users may need to change some settings. + +Off-screen Rendering +^^^^^^^^^^^^^^^^^^^^ + +Some users have reported that the rocket shown in the 3D design view is not full-size. This can occur if the off-screen +rendering setting is not correct for your device. Using the Three-stage rocket example packaged with OpenRocket, this is +what the problem looks like: + +.. figure:: /img/setup/installation/off_screen_rendering_wrong.png + :alt: Wrong 3D View of Three-stage Rocket + :figclass: or-figclass, or-image-border + :figwidth: 75 % + :align: center + + The 3D view of the Three-stage rocket example is too small. + +To fix this, you need to change the off-screen rendering setting. To do this, open the ``Edit`` menu in the application +ribbon and select ``Preferences``. This will open the Preferences dialog box. This window has several tabs (``General``, +``Design``, ``Simulation``, ... You need to go to the ``Graphics`` tab (just click on that tab header) and on the bottom +of the page change the ``Use off-screen rendering`` setting: + +.. figure:: /img/setup/installation/off_screen_rendering_setting.png + :alt: Off-screen Rendering Setting + :figclass: or-figclass, or-image-border + :figwidth: 50 % + :align: center + + The off-screen rendering setting is on the bottom of the ``Graphics`` tab. + +Your 3D view should now look like this: + +.. figure:: /img/setup/installation/off_screen_rendering_right.png + :alt: Correct 3D View of Three-stage Rocket + :figclass: or-figclass, or-image-border + :figwidth: 75 % + :align: center + + The 3D view of the Three-stage rocket example is now correct. + +.. note:: + + Whenever you face issues with 3D rendering in OpenRocket, it is a good idea to change the off-screen rendering setting + to see if that fixes the problem. + +.. _thrust_curves_setting: + +Thrust Curves Folder +^^^^^^^^^^^^^^^^^^^^ + +OpenRocket ships with a bunch of built-in motor thrust curves. However, it is possible to import your own thrust curves, +see :ref:`Import Custom Thrust Curves `. For this to work, you need to +**specify a folder where OpenRocket will look for thrust curves**. By default, OpenRocket will look in the ``ThrustCurves`` +folder in your application data directory. The application data directory is different for each operating system, see the +table below for the default application data directories for each operating system. + + +.. list-table:: Default Application Data Directories by Operating System + :widths: auto + :header-rows: 1 + :class: or-table-line-blocks + + * - Operating System + - Default Thrust Curves Directory + * - Windows + - | :file:`%APPDATA%\OpenRocket\ThrustCurves` (if ``APPDATA`` is available)\* + | :file:`C:\Users\[YOUR USERNAME]\OpenRocket\ThrustCurves` (fallback if ``APPDATA`` is not available) + | + | \* ``APPDATA`` is usually :file:`C:\Users\[YOUR USERNAME]\AppData\Roaming` + * - macOS + - :file:`/Users/[YOUR USERNAME]/Library/Application Support/OpenRocket/ThrustCurves/` + * - Linux + - :file:`/home/[YOUR USERNAME]/.openrocket/ThrustCurves/` (hidden directory) + +``[YOUR USERNAME]`` **is your user name on your device.** + +To view or modify the user-defined thrust curves folder(s), open the :menuselection:`Edit` menu in the application ribbon and select +:menuselection:`Preferences`. This will open the Preferences dialog box. You need to go to the :menuselection:`General` tab +(should be open by default) and change the :guilabel:`User-defined thrust curves` setting: + +.. figure:: /img/setup/installation/thrust_curves_setting.png + :alt: Thrust Curves Setting + :figclass: or-figclass, or-image-border + :figwidth: 50 % + :align: center + + The setting to change the user-defined thrust curves folder. + +You can also add multiple thrust curve folders. To do this, click on the :guilabel:`Add` button and select the folder you want to add. +You can also manually enter a new folder path. This path must be separated from other paths by a semicolon (``;``). + +Troubleshooting +=============== + +When you have issues with your installation, ensure that you have **read the installation instructions** for your platform. +When you download the installer from our `downloads page `__, you can +click on the :guilabel:`Show installation instructions` header under your platform's download button to see the +installation instructions. + +If you have further issues, please `contact us `__. + +Uninstalling +============ + +.. todo:: + Add uninstallation instructions. diff --git a/docs/source/setup/preferences.rst b/docs/source/setup/preferences.rst new file mode 100644 index 000000000..4024e360b --- /dev/null +++ b/docs/source/setup/preferences.rst @@ -0,0 +1,486 @@ +*********** +Preferences +*********** + +This page describes how you can customize OpenRocket using the Preferences dialog. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Accessing the Preferences Dialog +================================ + +The **Preferences dialog** can be opened by selecting :guilabel:`Preferences` from the :menuselection:`Edit` menu, or by +pressing :kbd:`Ctrl` + :kbd:`,` (comma) on your keyboard for Windows and Linux, or :kbd:`Cmd` + :kbd:`,` (comma) on your keyboard for macOS. + +.. figure:: /img/setup/preferences/Access-Preferences.png + :alt: Accessing the Preferences dialog from the Edit menu + :figclass: or-figclass, or-image-border + :figwidth: 45 % + :align: center + + Accessing the **Preferences dialog** from the :menuselection:`Edit` menu + +Explanation of the Available Preferences +======================================== + +.. _general_tab: + +General +------- + +The **General** tab contains general settings for the OpenRocket application. + +.. figure:: /img/setup/preferences/Prefs-General.png + :alt: General tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`General` tab in the Preferences dialog + +- :guilabel:`Interface language`: Select the language you want the OpenRocket GUI to be displayed in. + + Currently supported languages: + - ``System default`` - OpenRocket will use the language set in your operating system. + - ``English/English`` - This is the main language of OpenRocket. All other languages are translations of the English version. + - ``čeΕ‘tina/Czech`` + - ``Deutsch/German`` + - ``espaΓ±ol/Spanish`` + - ``franΓ§ais/French`` + - ``italiano/Italian`` + - ``Nederlands/Dutch`` + - ``polski/Polish`` + - ``portuguΓͺs/Portuguese`` + - ``TΓΌrkΓ§e/Turkish`` + - ``русский/Russian`` + - ``ΡƒΠΊΡ€Π°Ρ—Π½ΡΡŒΠΊΠ°/Ukrainian`` + - ``Arabic/Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ©`` + - ``δΈ­ζ–‡/Chinese`` + - ``ζ—₯本θͺž/Japanese`` + + .. note:: + You must restart OpenRocket for the language change to take effect. + + .. warning:: + Many translations are not complete or up-to-date. Missing translations texts are displayed in English. + + If you find any errors or missing translations, please let us know by creating an issue on the + `OpenRocket GitHub page `__ + or by :doc:`Contributing to the OpenRocket translations `. + +- :guilabel:`UI Theme`: Select the theme you want the OpenRocket GUI to be displayed in. + + Currently supported themes: + - ``Auto (detect)`` - OpenRocket will use the theme set in your operating system. + - ``Light (default)`` - A light theme (the "original" OpenRocket theme). + + .. figure:: /img/setup/preferences/Theme-Light.png + :alt: Light OpenRocket UI theme. + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Light OpenRocket UI theme. + + - ``Dark`` - A dark theme. + + .. figure:: /img/setup/preferences/Theme-Dark.png + :alt: Dark OpenRocket UI theme. + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Dark OpenRocket UI theme. + + - ``Dark, high-contrast`` - A dark theme, but with more contrast than the standard dark theme. + + .. figure:: /img/setup/preferences/Theme-DarkContrast.png + :alt: Dark Contrast OpenRocket UI theme. + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Dark Contrast OpenRocket UI theme. + + .. note:: + You must restart OpenRocket for the UI theme change to take effect. + +- :guilabel:`UI Font Size`: Select the font size you want the OpenRocket GUI to be displayed in. The default is 13. + The smaller the number, the smaller the font size. + + .. figure:: /img/setup/preferences/FontSize13.png + :alt: Font size 13 (default). + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Font size 13 (default). + + .. figure:: /img/setup/preferences/FontSize9.png + :alt: Font size 9 (default). + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Font size 9. + + .. figure:: /img/setup/preferences/FontSize17.png + :alt: Font size 17 (default). + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Font size 17. + + .. note:: + You must restart OpenRocket for the font size change to take effect. + +- :guilabel:`User-defined thrust curves`: You can specify a directory where you have stored your own thrust curves. + OpenRocket will scan this directory for thrust curves when you open the program. OpenRocket comes pre-installed with + thrust curves from the `ThrustCurve.org `__ database, but you can add your own using the + user-defined thrust curves. For more information, see the :doc:`Thrust Curves ` section. + + You can add multiple directories if you separate the paths with a semicolon (;). + + - :guilabel:`Add`: Add a directory where you have stored your own thrust curves. + - :guilabel:`Reset`: Reset the directories to the default directories. + +- :guilabel:`Always check for software updates at startup`: If this option is enabled, OpenRocket will check for software updates + every time you start the program. If an update is available, you will be notified. + + - :guilabel:`Check now`: Check for software updates now. + - :guilabel:`Also check for pre-releases`: If this option is enabled, OpenRocket will also check for pre-releases (so you + can test new features before they are officially released and help us fix last-minute mistakes). + +- :guilabel:`Open last design file on startup`: If this option is enabled, OpenRocket will open the last design file you were working on + when you start the program. + +- :guilabel:`Show warning when saving in RASAero format`: If this option is enabled, OpenRocket will show a warning when you export a design + in RASAero format. This is because RASAero does not support all the features of OpenRocket, so some information may be lost when you save + in RASAero format. + +- :guilabel:`Show warning when saving in RockSim format`: If this option is enabled, OpenRocket will show a warning when you export a design + in RockSim format. This is because RockSim does not support all the features of OpenRocket, so some information may be lost when you save + in RockSim format. + +- :guilabel:`Show confirmation dialog when discarding preferences`: If this option is enabled, OpenRocket will show a confirmation dialog + when you discard changes to the preferences. + +:guilabel:`Import preferences`, :guilabel:`Export preferences`, and :guilabel:`Reset all preferences` are explained in +:ref:`Importing and Exporting Preferences ` and :ref:`Resetting Preferences `. + +Design +------ + +The **Design** tab contains settings for the design of the rocket. + +.. figure:: /img/setup/preferences/Prefs-Design.png + :alt: Design tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Design` tab in the Preferences dialog + +- :guilabel:`Position to insert new body components`: Where to insert new body components in the rocket design view. + + - :guilabel:`Always ask`: OpenRocket will ask you where you want to insert new body components every time you add a new component. + - :guilabel:`Insert in middle`: Insert new body components after the currently selected component. + - :guilabel:`Add to end`: Insert new body components at the end of the parent component. + +- :guilabel:`Position to insert new stages`: Where to insert new stages in the rocket design view. + + - :guilabel:`Always ask`: OpenRocket will ask you where you want to insert new stages every time you add a new stage. + - :guilabel:`Insert in middle`: Insert new stages after the currently selected stage. + - :guilabel:`Add to end`: Insert new stages at the end of the rocket. + +- :guilabel:`Size of text in rocket design panel`: The size of the text in the rocket design view. +- :guilabel:`Default Mach Number for C.P. Estimate`: Mach value that is used for the Center of Pressure (CP) calculations + in the rocket design view. +- :guilabel:`Always open leftmost tab when opening a component edit dialog`: If enabled, if you edit a rocket component and + open the component configuration, it will always open in the leftmost tab. If disabled, the last tab you used will be opened. +- :guilabel:`Show confirmation dialog for discarding component changes`: If enabled, OpenRocket will show a confirmation + dialog when you discard changes to a component (if you click the :guilabel:`Cancel` button in the component configuration window). +- :guilabel:`Show confirmation dialog for discarding simulation changes`: If enabled, OpenRocket will show a confirmation + dialog when you discard changes to a simulation (if you click the :guilabel:`Cancel` button in the simulation configuration window). +- :guilabel:`Update estimated flight parameters in design window`: If enabled, OpenRocket will calculate and update the estimated + flight parameters in the rocket design view (in the top-left) when you make changes to the rocket design. +- :guilabel:`Only show pod set/booster markers when the pod set/booster is selected`: If enabled, OpenRocket will only show the + pod set/booster instance markers in the rocket design view when the pod set/booster is selected. The instance markers show + where pod/booster instances are located in the rocket design. + + .. figure:: /img/setup/preferences/PodAndBoosterMarker.png + :alt: Booster and Pod instance markers on a body tube in the rocket design view. + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Booster and Pod instance markers on a body tube in the rocket design view. + +Simulation +---------- + +.. figure:: /img/setup/preferences/Prefs-Simulation.png + :alt: Simulation tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Simulation` tab in the Preferences dialog + +- :guilabel:`Confirm deletion of simulations`: If enabled, OpenRocket will show a confirmation dialog when you delete a simulation. +- :guilabel:`Run out-dated simulations when you open the simulation tab`: If enabled, OpenRocket will run simulations that are out-dated + when you switch the simulation tab (in the task tabs). +- :guilabel:`Geodetic calculations`: Which calculation method to use for coordinates on the Earth. +- :guilabel:`Time step`: The smallest time step to use in the simulations. A smaller time step will give more accurate results but + will take longer to compute. + + .. note:: + OpenRocket uses optimized time steps. It will use a larger value than the set time step for parts in the simulation + that do not require a smaller time step. + + In other words, the simulation time step is not fixed, but will vary throughout the simulation. + +- :guilabel:`Reset to default`: Reset the simulator options to the default values. + +.. attention:: + The settings in the Launch tab have **no effect on existing simulations in your design**. + + Only simulations that you create after changing these settings will be affected. + +Launch +------ + +.. figure:: /img/setup/preferences/Prefs-Launch.png + :alt: Launch tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Launch` tab in the Preferences dialog + +.. hlist:: + :columns: 2 + + - Wind + - :guilabel:`Average windspeed`: The average wind speed relative to the ground. + - :guilabel:`Standard deviation`: Standard deviation of the wind speed (= a measure of the dispersion of the wind speed values). + The actual wind speed is within twice the standard deviation 95% of the time. + - :guilabel:`Turbulence intensity`: The standard deviation of the wind speed divided by the average wind speed. Typical + values range from 5% to 20%. + - :guilabel:`Wind direction`: The direction the wind is coming from. 0Β° is north, 90Β° is east, 180Β° is south, and 270Β° is west. + - Atmospheric conditions + - :guilabel:`Use International Standard Atmosphere`: If enabled, the atmospheric conditions will be set to the + International Standard Atmosphere (ISA). This model has a temperature of 15 Β°C and a pressure of 1013.25 mbar at + sea level. + + If disabled, you can set the temperature and pressure manually. + - :guilabel:`Temperature`: The temperature at the launch site. + - :guilabel:`Pressure`: The pressure at the launch site. + - Launch site + - :guilabel:`Latitude`: The latitude coordinate of the launch site. + - :guilabel:`Longitude`: The longitude coordinate of the launch site. + - :guilabel:`Altitude`: The altitude of the launch site. + - Launch rod + - :guilabel:`Length`: The length of the launch rod. + - :guilabel:`Always launch directly up-wind or down-wind`: If enabled, the launch rod will always point into the wind. + - :guilabel:`Angle`: The angle of the launch rod relative to the ground. At 0Β°, the launch rod points straight up (vertical). + If the checkbox to "Always launch directly up-wind or down-wind" is enabled, positive angles point up-wind, and negative angles + point down-wind. If the checkbox is disabled, positive angles towards the direction axis. E.g. if direction is set + to 90Β° (East of the wind), positive angles will point the launch rod East. Negative angles will point the rod West. + - :guilabel:`Direction`: Direction of the launch rod relative to the wind. 0Β° is pointing in the wind direction. + 90Β° is pointing East of the wind. + +.. attention:: + The settings in the Launch tab have **no effect on existing simulations in your design**. + + Only simulations that you create after changing these settings will be affected. + +Units +----- + +The **Units** tab allows you to set the units that OpenRocket uses throughout the program. + +.. figure:: /img/setup/preferences/Prefs-Units.png + :alt: Units tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Units` tab in the Preferences dialog + +.. hlist:: + :columns: 2 + + - :guilabel:`Rocket dimensions`: Unit for dimensions of rocket components (e.g. diameter, length). + - :guilabel:`Motor dimensions`: Unit for dimensions of rocket motors (diameter, length). + - :guilabel:`Distance`: Unit for distances (e.g. altitude). + - :guilabel:`Velocity`: Unit for velocities. + - :guilabel:`Acceleration`: Unit for accelerations. + - :guilabel:`Mass`: Unit for masses. + - :guilabel:`Force`: Unit for forces. + - :guilabel:`Total impulse`: Unit for total impulse. + - :guilabel:`Moment of inertia`: Unit for moments of inertia. + - :guilabel:`Stability`: Primary unit for stability margin/static margin. + + Possible values: + + - ``mm``, ``cm``, ``m``, ``in``: Distance between the center of gravity (CG) and the center of pressure (CP). + - ``cal``: Caliber. 1 caliber = 1 diameter of the rocket. + - ``%``: Percentage of the rocket length. + + - :guilabel:`Secondary stability`: Secondary unit for stability margin/static margin. + + Same values as the primary stability unit. + + - :guilabel:`Display secondary stability unit`: If enabled, display both the primary and secondary stability units in the rocket design view. + - :guilabel:`Line density`: Unit for line density (= one-dimensional density). + - :guilabel:`Surface density`: Unit for surface density (= two-dimensional density). + - :guilabel:`Bulk density`: Unit for bulk density (= three-dimensional density). + - :guilabel:`Surface roughness`: Unit for surface roughness. + - :guilabel:`Area`: Unit for areas. + - :guilabel:`Angle`: Unit for angles. + - :guilabel:`Roll rate`: Unit for roll rates. + - :guilabel:`Temperature`: Unit for temperatures. + - :guilabel:`Pressure`: Unit for pressures. + - :guilabel:`Wind speed`: Unit for wind speeds. + - :guilabel:`Latitude`: Unit for latitudes. + - :guilabel:`Longitude`: Unit for longitudes. + +- :guilabel:`Default metric`: Set the default unit system to metric units. +- :guilabel:`Default imperial`: Set the default unit system to imperial units. + +Materials +--------- + +The **Materials** tab shows a list of materials that are pre-installed in OpenRocket, plus custom user-defined materials that +you have added. + +.. figure:: /img/setup/preferences/Prefs-Materials.png + :alt: Materials tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Materials` tab in the Preferences dialog + +On the left are a list of all the materials in OpenRocket. Pre-installed OpenRocket materials are displayed in greyed-out text. +User-defined materials are displayed in normal text. + +- :guilabel:`New`: Add a new custom material. +- :guilabel:`Edit`: Edit the selected material. You can edit both custom materials and pre-installed OpenRocket materials. + However, editing a pre-installed material will create a new custom material with the same name, instead of modifying the + original material. +- :guilabel:`Delete`: Delete the selected material. You can only delete custom materials. +- :guilabel:`Revert all`: Delete all user-defined materials. + +.. note:: + Editing materials will not affect existing rocket designs. + + +Graphics +-------- + +The **Graphics** tab allows you to set the graphics settings for OpenRocket. + +.. figure:: /img/setup/preferences/Prefs-Graphics.png + :alt: Graphics tab in the Preferences dialog + :figclass: or-figclass, or-image-border + :figwidth: 65 % + :align: center + + :guilabel:`Graphics` tab in the Preferences dialog + +- **Graphics Editor**: Select which graphics editor you want to use to edit textures in OpenRocket (if you click the + :guilabel:`Edit` button next to the Texture dropdown in the :guilabel:`Appearance` tab of the component configuration window). + + - :guilabel:`Show Prompt`: OpenRocket will ask you which graphics editor you want to use every time you edit a texture. + - :guilabel:`Use Default Editor`: OpenRocket will use the default graphics editor you have set in your operating system. + - :guilabel:`Command Line`: You can set the command line for the graphics editor you want to use. This is useful if you have + multiple graphics editors installed and want to use a specific one. Enter the file path of the graphics editor executable + and any command line arguments you want to use in the text input field, or click the :guilabel:`Select Graphics Editor Program` + button to select the executable file. +- **3D Graphics** + + - :guilabel:`Enable 3D Graphics`: If enabled, 3D rendering is supported in OpenRocket. If disabled, you can not use any + 3D features inside OpenRocket. + - :guilabel:`Enable Anti-aliasing`: If enabled, OpenRocket will use anti-aliasing to smooth the edges of 3D graphics. + - :guilabel:`Use Off-screen Rendering`: If enabled, OpenRocket will render 3D graphics off-screen. This can improve performance + on some systems, but may cause issues on others. + + .. tip:: + If you experience issues with 3D graphics, try toggling this option (enable it if is was disabled, or vice versa). + + .. note:: + The effects will take place the next time you open a window. + +.. _resetting_prefs: + +Resetting Preferences +===================== + +To reset all preferences to their default values, click the :guilabel:`Reset all preferences` button at the bottom of the +:ref:`General tab `. + +.. _importing_exporting_prefs: + +Importing and Exporting Preferences +=================================== + +You can export the current preferences to an XML file, or import preferences from an XML file. This can be useful for +instance if you need to teach other people how to use OpenRocket and want them to have the same settings as you. + +Export Preferences +------------------ + +To export preferences, click the :guilabel:`Export preferences` button at the bottom of the :ref:`General tab `. +This will open a file dialog where you can select where to save the preferences file: + +.. figure:: /img/setup/preferences/ExportPreferences.png + :alt: Exporting preferences to an XML file + :figclass: or-figclass, or-image-border + :figwidth: 55 % + :align: center + + Exporting preferences to an XML file + +There are two options in the file dialog: + +- :guilabel:`Export user directories` If enabled, any user directories that are set in the preferences will be exported as well. + If you import the preferences on another computer, the user directories will be set to the same directories as on the original computer. + + You can disable this option if the target computer has different directories, or if you don't want to share the information + about your directories. +- :guilabel:`Export window information (position, size...)`: If enabled, cached window information (position, size, etc.) will be exported. + If you import the preferences on another computer, the windows will be opened in the same position and size as on the original computer. + + You can disable this option if you want the windows to be opened in the default position and size. + +Here is an example of the exported preferences XML file: + +.. code-block:: xml + + + + + + + + + + + + + + ... + +Import Preferences +------------------ + +To import preferences, click the :guilabel:`Import preferences` button at the bottom of the :ref:`General tab ` +and select the preferences XML file you want to import. diff --git a/docs/source/user_guide/advanced_flight_simulation.rst b/docs/source/user_guide/advanced_flight_simulation.rst new file mode 100644 index 000000000..b1f24a016 --- /dev/null +++ b/docs/source/user_guide/advanced_flight_simulation.rst @@ -0,0 +1,199 @@ +************************** +Advanced Flight Simulation +************************** + +OpenRocket offers more advanced options for simulating flight. You can plot your rocket's predicted acceleration, climb, +eject and landing, make a prediction for how far downrange and in which direction your flight will land, and even +experiment with different models of Earth's geometry, as it affects your flight. Once you're satisfied with a sim, you +can export your data for analysis and charting in other packages. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Plotting your rocket's flight +============================= + +To begin learning about OpenRocket's plotting features, first, click the **Plot / Export** button on the **Flight simulations** window. + +.. figure:: /img/user_guide/advanced_flight_simulation/PlotExportButton.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: The Plot / export Button. + +On the **Edit simulation** panel, you'll see tabs marked **Plot data** and **Export data**. + +Plotting data +------------- + +The **Plot data** tab opens first. Here you can define many parameters that will determine what values are plotted, and +what events are marked on the plot. + +.. figure:: /img/user_guide/advanced_flight_simulation/PlotExportWindow.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: The Plot / export window. + +Here you'll be able to quickly choose from a number of standard plots: + +.. figure:: /img/user_guide/advanced_flight_simulation/PlotConfigs.png + :width: 806 px + :align: center + :figclass: or-image-border + :alt: Standard plots + +You'll also be able to assign to the X and Y axes any one of over 50 parameters. If you click on the plot variable +dropdown, you'll see a search box and a list of variable categories. You can either scroll through the categories +to find the parameter you want, or type in the search box to filter the list: + +.. figure:: /img/user_guide/advanced_flight_simulation/ChoosePlotVariable.png + :width: 806 px + :align: center + :figclass: or-image-border + :alt: Select plot variable + + Select a plot variable from the variable groups (left), or search for the desired variable (right). + +The parameters are categorized in the +following groups: + +- **Time**: Variables related to time +- **Position and Motion**: Variables related to the position and motion of the rocket (e.g. altitude, position, velocity, acceleration) +- **Orientation**: Variables related to the orientation of the rocket (e.g. pitch, yaw, roll) +- **Mass and Inertia**: Variables related to the mass and inertia +- **Stability**: Variables related to the stability of the rocket (e.g. CG, CP, stability margin) +- **Thrust and Drag**: Variables related to the thrust and drag (e.g. thrust, TWR, drag) +- **Coefficients**: Variables related to the calculation coefficients (e.g. normal force coefficient, roll moment coefficient) +- **Atmospheric Conditions**: Variables related to the atmospheric conditions (e.g. air pressure, wind velocity) +- **Characteristic Numbers**: Variables related to the characteristic numbers (e.g. Mach number, Reynolds number) +- **Reference Values**: Variables related to the reference values (e.g. reference area, reference length) +- **Simulation Information**: Variables related to the simulation information (e.g. simulation time step) +- **Custom**: *(User-defined parameters)* + + + + +You can assign multiple parameters to the Y-axis, and choose whether their scales appear on the left, or the right side +of the plot. You can add Y-axis parameters with the :guilabel:`New Y-axis plot type` button, or delete parameters from the plot +with the :guilabel:`X` buttons. (*The X-axis takes only a single plotted parameter, typically* **Time**). + +Additionally, you can choose from several flight events, any or all of which can be called out on your plot, in reference +to the simulated time of occurrence. + +.. figure:: /img/user_guide/advanced_flight_simulation/YaxisTypes.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: Setting Y-axes and Events for plotting + +Plotted results +--------------- + +Below you can see a plot of *A simple model rocket*, simulation number 4, flying on a C6-5. Note that the five events +checked in the above screen have been marked on the plot (*some very close to each other, or to the edge*): +**Motor ignition**, **Motor burnout**, **Apogee**, **Recovery device deployment**, and **Ground hit**. + +You can also see that the three Y-axis parameters described above: **Altitude**, **Vertical velocity**, and +**Vertical acceleration** appear as lines of three different colors. + +.. figure:: /img/user_guide/advanced_flight_simulation/PlotOfSimulation.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: A Plot of the simulation. + +As your rockets get more complex, with features like dual-deploy, air-start and multiple stages, your plots can grow in +complexity to simulate their expected behavior. Below is a plot (*from the example rockets*) of a "High Power Airstart" +rocket, modeled after a Patriot missile. The central motor starts on the launch pad, while the surrounding motors start +while the rocket is in the air (*hence, an "airstart"*). The plot records the separate motor start events, and the +deployment of both a drogue, and a main parachute. + +.. figure:: /img/user_guide/advanced_flight_simulation/ComplexPlot.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: A Plot of Sim #5 of the "High Power Airstart" example rocket. + +Notice what's happening in the plot above: The rocket is *losing velocity* - the blue line - before the airstart occurs. +This is probably not what we want. + +However, simulation number 3 of the same rocket, below, has an earlier airstart, and looks like it should work as expected. +Looking at the slight wiggle in the velocity curve, we could also try another simulation to provide a little bit more +margin for error. + +.. figure:: /img/user_guide/advanced_flight_simulation/ComplexPlot2.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: A Plot of Sim #3 of the "High Power Airstart" example rocket. + +---- + +Launch Conditions and Simulation Options +======================================== + +From the **Plot data** window, you can click the **<< Edit** button to configure **Launch conditions**, and +**Simulation options** before you plot. + +Launch conditions +----------------- + +OpenRocket can simulate conditions at the launch site, so you can estimate how winds will direct your flight, and how +far downrange your rocket will drift. + +In the screen shown below, you can set parameters (and units) for wind, and for your **Launch site**, you can set the +**Latitude**, **Longitude** and **Altitude**, as well as **Atmospheric conditions**. Note that Atmospheric conditions +affect your rocket's ascent velocity, as well as the local `Speed of Sound `__. + +This is also the panel where you can set the length of your launch rod or rail. This length will affect whether your +simulation *passes or fails*, when it's evaluated for minimum speed off the rod. + +.. figure:: /img/user_guide/advanced_flight_simulation/EditSimulationLaunchCond.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: The Edit simulation window: Launch conditions. + +Simulation options +------------------ + +In the **Simulation options** tab, the **Simulator options** let you choose the shape of the simulated Earth in your +calculations (*doing so* **does not** *affect the Earth background in Photo Studio*), and you can choose the time-resolution +of the simulation. This is also the place where you add and set up **Simulation extensions**, which are beyond this +guide's purpose. + +.. figure:: /img/user_guide/advanced_flight_simulation/EditSimulationSimOpts.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: The Edit simulation window: Simulation options. + + The Simulation options in the simulation configuration window + +---- + +Exporting Data +============== + +Located on the **Plot / export panel**, the **Export Data tab** (shown below) helps you set up a Comma-Separated Value (.csv) +formatted file to export data from your simulations. You can export any or all of over 50 values (generally speaking, +the list of parameters above, plus **Coriolis acceleration**). Optional **Comments** sections list any flight events +(**Apogee**, for example) you selected for your simulation, as well as description and field descriptions. + +You can choose separators other than comma, if you prefer semicolon, space, or TAB-delimited data. Once you have your +data choices set up, clicking the :guilabel:`Export` button brings up a file dialog to choose a filename and location for your +exported data. + +.. figure:: /img/user_guide/advanced_flight_simulation/ExportData.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: The Export data window. + + The Export data window. + diff --git a/docs/source/user_guide/advanced_rocket_design.rst b/docs/source/user_guide/advanced_rocket_design.rst new file mode 100644 index 000000000..88734974a --- /dev/null +++ b/docs/source/user_guide/advanced_rocket_design.rst @@ -0,0 +1,638 @@ +********************** +Advanced Rocket Design +********************** + +In this section, advanced design principles and concepts are discussed, with step-by-step instructions describing how to +incorporate these techniques into designs created in OpenRocket. Implementing the techniques described in this section +may require specialized materials and electronic devices intended for use only by experienced rocketeers. + +Advanced rocket design encompasses configurations for high power rockets generally, including: + +- Recovery systems +- Through-the-wall fin construction +- Electronic and dual deployment +- Complex multi-staging (such as motor racking) and motor clustering +- Roll stabilization + +Additionally, you may find that using mass and center of gravity (CG) overrides will improve OpenRocket flight and +recovery simulation accuracy. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Recovery Systems +================ + +Recovery Techniques +------------------- + +Recovery systems are intended to return a rocket safely to the ground, without harm to people or damage to the rocket or +other objects. Though recovery mechanisms vary greatly, recovery systems generally include elements of one or more of +these techniques: + +- Featherweight +- Break-apart +- Streamer +- Parachute +- Helicopter +- Gliding + +Featherweight and Break-Apart Recovery +-------------------------------------- + +Featherweight and break-apart recovery work by creating enough drag to ensure that the terminal velocity of the rocket +is so low that it won't be damaged or do damage when it hits the ground. Featherweight designs are often minimum diameter +rockets that eject the burned-out motor casing altogether, or use the ejection charge to shift the casing position +rearward after motor burnout (within an extended motor hook), to induce instability and cause the rocket to tumble. +Break-apart recovery, aerodynamically, does the same thing, increasing drag and inducing instability by breaking the +rocket into two or more sections connected together by a shock cord. Typically, a featherweight rocket, and each section +of a break-apart rocket weighs less than one ounce. + +.. figure:: /img/user_guide/advanced_rocket_design/Featherweight.png + :width: 245 px + :align: left + :figclass: or-image-border + :alt: The Estes Astron Streak, ca 1970 - a *featherweight recovery* rocket + +Example Featherweight Design +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In earlier years, Estes sold a few rockets that featured *Featherweight Recovery*, meaning that a very light model could +spit out its used motor casing, and land directly on the ground with no damage, rather like a badminton shuttlecock. + +Ejecting burned-out motor casings is not allowed in :abbr:`NAR (National Association of Rocketry)` contests unless a streamer or parachute is attached to the +ejected casing. + +.. figure:: /img/user_guide/advanced_rocket_design/Unicon.png + :width: 200 px + :align: right + :figclass: or-image-border + :alt: The scratch Unicon, ca 1970 - a *break-apart recovery* rocket + +Example Break-Apart Design +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Another approach to bringing a lightweight rocket safely to earth is to break the airframe into several aerodynamically +unstable pieces, and "flutter" them back to earth. + +One such design: the `Unicon `__ +(for *"Unified/Consolidated"* - a stretch, I know) appeared as a plan in American Aircraft Modeler in February, 1970. +The body tube featured 3 pieces of launch lug, as did the nose cone. Into these lugs plugged one of 3 balsa sticks, each +of which held a fin, and a piece of body tube attached to the fin root and the stick, to provide a stable anchor against +the body. The entire assembly was connected with pieces of heavy-duty thread. + +When the ejection charge fired, the nose cone popped off, releasing the sticks with fins, which, tied to the body tube +and nose cone, fluttered in the air, and slowed descent of the main airframe as it landed. + +This author built one, and it worked pretty well. + +Streamer and Parachute Recovery +------------------------------- + +Streamers and parachutes add drag to slow the rocket descent rate. Generally, a larger streamer is always better. But, +streamer size is an example of the principle of diminishing marginal returns, eventually making a streamer larger will +only slightly increase drag (a rocket weighing more than 10 oz is beyond the effective use of a streamer). On the other +hand, because of their efficiency, parachutes create more drag with less cloth than any other method, and virtually all +high power rockets use parachutes. + +Example Streamer Design +^^^^^^^^^^^^^^^^^^^^^^^ + +A method of recovery favored on windier days is to attach a flame-retardant streamer to the shock cord, in place of a chute. +Using OpenRocket you can simulate streamer recovery by equipping your rocket design with a streamer from the **Mass Objects** section. + +A streamer flaps in the wind as the rocket falls, losing altitude faster than an equivalent volume of packed parachute. +Because it comes in faster, it won't drift as much in the wind. The rocket will also hit harder, potentially risking damage. +OpenRocket can help you estimate how fast your model will land. + +By using "snap swivels" - small brass clips usually found in the fishing tackle aisle - you can prepare both a parachute +and a streamer for a rocket, choose your method of recovery at the field, and clip it onto the shock cord before you launch. + +:abbr:`NAR (National Association of Rocketry)` requires 10 cm :sup:`2` of streamer area per gram of mass in contest models. + +Example Parachute Design +^^^^^^^^^^^^^^^^^^^^^^^^ + +Parachute recovery is probably the most familiar model rocket recovery mechanism. Most of the beginner kits start with +parachutes, but even high-power, edge-of-space-kissing, multi-stage, electronic deployment rockets use parachutes to +slow descent. They're basic to the hobby. + +OpenRocket gives you a number of simulation options for parachutes, including material, construction, size, number of +shroud lines, packed size and more. With OpenRocket, you can set your parachute's deployment to work just like your +real rocket's. + +One thing that you're not able to directly simulate here is the *type* of 'chute you have. Parachutes come in different +types, from the semi-ellipsoid proper Parachute - an efficient shape (by drag to weight) which cannot be laid perfectly +flat, to the "parasheet" - a 'chute that can be formed from a flat piece of material (the typical model rocket kit +contains a parasheet), to X-shaped parachutes, to 'chutes with spill-holes, to parafoils and Rogallo wings. You'll have +to experiment with these chutes, and perhaps try and adjust the Drag coefficient to compensate for difference from +OpenRocket's ideal parachute. + +:abbr:`NAR (National Association of Rocketry)` requires 5 cm :sup:`2` of parachute area per gram of mass in contest models. + +In 2022, Apogee released a "Gliding Parachute", which could be steered by remote control back to the launch pad (given +enough altitude and favorable winds). OpenRocket cannot, at this writing, simulate the behavior of the Gliding Parachute. + +Helicopter and Gliding Recovery +------------------------------- + +Helicopter Recovery +^^^^^^^^^^^^^^^^^^^^ + +Helicopter recovery relies upon rigid lift-generating blades and auto-rotation to slow terminal velocity. This design +technique is the most complicated of all, and requires that the entire rocket be designed around the recovery device. +As important, the stresses generated by rapidly spinning blades hitting the ground effectively limits the use of this +technique to low mass (model) rockets. + +Gliding Recovery +^^^^^^^^^^^^^^^^ + +A glider uses aerodynamic lift to control terminal velocity. However, because the aerodynamic requirements of vertical +flight are vastly different than gliding flight, to make this transition there must be a shift in the center of gravity +or the center of pressure. This transition can be made by reducing mass (ejecting the motor mount tube and weights) or +changing aerodynamic signature (ejection activated fin-elevators or swing-wings). Radio and other control systems are +currently being used to fly gliding recovery rockets, even high power. + +Protecting Recovery Components +------------------------------- + +Recovery components are made from lightweight materials which, while often flame retardant, aren't necessarily heat-proof, +or which may char and decay without bursting into flame. + +To protect the recovery components and ensure they work properly for a safe landing, some method of shielding the +"Laundry" (slang for the parachute and associated cords) from the heat of ejection, or of cooling the eject gasses must +be used. + +Heat Shields +------------ + +Protecting the components starts during rocket design: you can choose something durable and flame-resistant like Kevlar +cord for shock cord components that will be used in the eject area. A little later in this article, you'll see other +built-in options you can use. + +Fire Resistant Wadding and Blankets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The simplest way to protect the 'chute is to put something flameproof between the eject charge and the recovery hardware. +In small rockets, this can take the form of "Flameproof ejection wadding", as packaged with Estes motors, or flame-retardant +recycled cellulose insulation (nicknamed "Dog Barf" in the hobby community). Of the two, "Dog Barf" makes much less of a +mess on the field, and is recommended by some clubs. If you do use "Estes Flameproof ejection wadding", please try and +recover as much of the discarded paper as possible before leaving your launch site. + +When using wadding, try and put in a minimum depth of 1.5 tube diameters of wadding. Wadding may be poked gently into a +rocket with a pencil or stick, but don't pack it down. + +You can also buy a reusable 'chute protector, called a "Nomex blanket" or a "'Chute bag" (also made of Nomex). Nomex +blankets are typically square, often orange, and usually have a buttonhole sewn into the corner, to pass the shock cord +through. One wraps up the parachute and as much of the shock cord as is practical with the Nomex facing the eject charge. +This author was instructed to wrap the 'chute in Nomex "Like a burrito", but in reality there are several ways to pack a +chute protector that will work well. Ensure that the Nomex faces the eject charge, so it takes the heat of ejection, and +not your recovery device. + +Nomex can be re-packed with the 'chute immediately after a flight. Nomex is machine-washable (and you'll probably want +to wash it at some point). + +**A rule of thumb for sizing a Nomex blanket**: *The blanket should be a square, with a width that's 3 times the body diameter.* + +Piston Ejection +^^^^^^^^^^^^^^^^ + +Another way of insulating the recovery material from the heat of ejection is with a Piston Ejection system. + +In a typical piston ejection system, a piston is inserted into the body tube, and is free to slide up and down the tube's +length. The eject charge is on one side of the piston, and the recovery material on the other. The body tube, the piston +and the recovery material are all connected together, so as not to lose any parts. + +At ejection charge firing, expanding gases push the piston (and the recovery material) up the tube and out of the rocket, +without exposing the recovery material to the heat of the eject charge. The piston should leave the rocket body, in order +to vent the ejection gases. + +Pistons are often made of tube couplers, which have been sanded down a bit to smoothly slide in the body tube. One end of +the coupler is closed by a bulkhead. The closed end is called the "face" of the piston. The rounded wall of the coupler +is called the piston's "skirt". + +The attachment shock cord runs from the eject charge end of the rocket, attaches to the piston at the face (or is threaded +through it and sealed) and more shock cord runs from the other side of the piston face and to the recovery material. +The attachment cord needs to be long enough for the piston to escape the body tube so exhaust gases are vented. The +piston *must* move smoothly and without sticking; if the piston sticks, the parachute may not be deployed. + +Opinions differ on whether the "face" of the piston should face the 'chute or the ejection charge. According to one theory, +if the piston face is on the nose cone side of the piston, exhaust gases could make the piston skirt swell and cause the +piston to stick in the body tube, while if instead the piston faces the eject charge, eject gases that travel between the +piston skirt and the inside of the body tube form a "gaseous lubricant" which should prevent the piston from getting stuck. +Others beg to differ, and have had successful real world experience with the piston facing upward. + +Ejection Gas Cooling +^^^^^^^^^^^^^^^^^^^^ + +Another approach to protecting the recovery material is to cool the ejection gases before they contact the 'chute. + +Cooling Mesh +^^^^^^^^^^^^ + +Aerotech sells a metal cooling mesh for model rockets. The mesh looks like a tiny tangled slinky, or perhaps like twisted +tinsel from a Christmas tree. Installing a metal cooling mesh in the rocket body allows cooling of the exhaust gases, +which transfer much of their heat to the metal mesh as they pass. The configuration of the mesh also makes it something +of a particle filter, so chunks of burning material from the ejection charge get filtered out, instead of passing their +heat to your parachute. + +Baffles +^^^^^^^ + +Still another approach is to install a baffle in the rocket, above the eject charge, and below the recovery system. A +baffle is often made from a coupler with two bulkheads, one in each end. Designs differ, but basically there's a hole +pattern in the top, and a hole pattern in the bottom, such that ejection gas will pass through, but because the holes +don't align, it will need to make a detour through the baffle. Meanwhile, heavier burning solid material from the eject +charge has much higher inertia, and won't be able to divert to the top set of holes. Much of it will be stopped by the +top bulkhead. + +Servicing +^^^^^^^^^ + +Both baffles and cooling mesh will have limited lifespans, and need to be cleaned, serviced, or replaced. Cooling mesh in +particular can become clogged with particles from many flights, and may be placed in a difficult-to-reach position. +Baffles may burn, break, or get filled with particles. When this happens, the best service option may be to "poke out" +the cooling mesh or baffle, and go over to recovery wadding or a Nomex blanket. + +One way to avert the "poke out" problem is to use screws to attach a baffle through the wall of the body tube. Nylon +screws may be used to avoid placing "ductile metal" in the airframe. Screw attachment allows the baffle to be removed +for servicing or replacement. + +CO\ :sub:`2`\ Ejection Devices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Another approach to eject is pioneered by `Tinder Rocketry `__, who offer a CO\ :sub:`2`\ +ejection system. Because a minimal pyro device is used to trigger the CO\ :sub:`2`\ ejection, there's not a lot of hot +material flying around inside the airframe, and no need for wadding or a Nomex blanket. The CO\ :sub:`2`\ is cold as it's released. + +The CO\ :sub:`2`\ ejection system is claimed to operate more reliably than black powder at extreme altitude +(above 20,000 feet ASL), due to black powder's incomplete or non-existent burn at these altitudes. + +---- + +Tube Fins and Ring Tails +======================== + +Tube Fins +--------- + +A tube fin is just that, a fin made using a shorter section of body tube, adhered to the main body tube, with or without +other flat fins. This type of rocket is easy enough to build, and OpenRocket helps you make an accurate simulation. + +.. figure:: /img/user_guide/advanced_rocket_design/TubeFins.png + :width: 250 px + :align: right + :figclass: or-image-border + :alt: *A simple model rocket* - now with tube fins. + +Let's convert *A Simple Model Rocket* from 3 flat fins, to 4 tube fins, just because we can. + +1. From the :menuselection:`File` menu, choose :menuselection:`Open Example` and open **A simple model rocket**. +2. Left-click on the :guilabel:`Trapezoidal fin set` in the upper-left panel, and delete it. +3. Left-click on the :guilabel:`Body tube`. +4. Note that :guilabel:`Tube fins` is now enabled in :guilabel:`Body components and fin sets`. Click it. +5. The number of fins defaults to 6. These look a little long. Drag the :guilabel:`length` slider until the fins are about 7 cm long. +6. Drag the :guilabel:`plus` slider (under :guilabel:`Position relative to:``) to move the fins forward just a little. +7. Leave the **Tube fin set configuration** window open, and click on the :guilabel:`View Type` menu on the main window. + Choose the :guilabel:`Back view`. +8. Notice that OpenRocket has defaulted to an exact solution for wrapping 6 tube fins around your rocket body tube. + In the **Tube fin set configuration** window, drag the :guilabel:`Fin rotation` slider until they line up with the launch lug. + (*Passing the launch rod through one of the tube fins to reach the launch lug is simpler than arranging the tube fins + for the rod to pass between the tubes*) +9. Notice that you can adjust the Outer Diameter of the fins to create designs that are harder to build, or perhaps + impossible to build due to overlaps between tube fins. +10. Click the :guilabel:`Automatic` check box beneath :guilabel:`Outer diameter`. The tubes conform once more to the body tube and touch + each other. Because the contact surfaces are in the right place to adhere to each other, this is probably the easiest + type of fin configuration to build. +11. Reduce the :guilabel:`Number of fins` to 5, then to 4. As long as :guilabel:`Automatic` is checked and the solution makes sense, + the fins will wrap the body tube. At 4 fins, the tubes would have to dwarf the body tube to wrap it, and OpenRocket + gives up on wrapping. +12. Re-adjust the :guilabel:`Fin rotation` slider to line the 4-fin set up with the launch lug, either within, or beside a tube fin. + +Our fin conversion is complete, but before we leave the **Tube fin set configuration** window, note a few other details: + +- You can select preset tube components by clicking the :guilabel:`Parts Library` button in the upper-right. + *Note that these components represent what was available at the time this version of the OpenRocket component database was + released - some may no longer be available*. Some details of the components will fill fields of the **Tube fin set + configuration** window, but *Diameter* is not one of them - at least in OpenRocket 15.03. +- It's not possible to use the **Tube fins** component to create tube fins sliced at an angle, or to create semi-circular + fin sections (tubes cut in half, lengthwise). +- Though you might imagine lots of cool tube fin scenarios, this Tube fin tool will require your tubes to be in side-to-side + contact with a body tube. +- OpenRocket won't apply your specified color to the inside of the tube fins. They'll have the default color inside. + +Ring Tails +---------- + +It's easy to visually add a ring tail fin to an OpenRocket model using a body tube, but there's one catch: the ring tail +must start at the exact aft-end of the body tube it surrounds, and the supporting fins must trail to support it. This is +because, unlike other non-external components in OpenRocket, external airframe parts follow a strict linear pattern: +Nose cone, then a body tube, then perhaps another, and perhaps another, etc. If you don't want the ring tail fin at the +end of the model, also visually simulate a ring tail virtually at any point up or down the airframe using an inner tube. +But, as with the body tube approach, there’s a catch, inner tubes are aerodynamically ignored during the simulation. + +**If you like the "look" of ring tail models, *OpenRocket does that very, very well*. Just **BE AWARE** that +*OpenRocket WILL NOT accurately simulate ring tail fins* at this time.** + +.. figure:: /img/user_guide/advanced_rocket_design/RingTail.png + :width: 250 px + :align: right + :figclass: or-image-border + :alt: *A simple model rocket* - with added Ring Tail. + +So, if you want that ring tail "look," let's step through adding a ring tail to **A simple model rocket** to demonstrate +the body tube method. + +1. From the :menuselection:`File` menu, choose :menuselection:`Open example...` and choose **A simple model rocket**. +2. Click the :guilabel:`Body tube` component to add a new body tube. *Note that it's added at the aft end of the main body tube, + and is initially the same diameter as that tube*. +3. Increase the tube's :guilabel:`Outer diameter` to 8.6 cm, to let it just sit on the top fin. Yes, this will look strange for a moment or two. +4. Reduce the **Body tube length** to 2.5cm, so the back of the ring tail just touches the back of the fin points. +5. Set the appearance, if you'd like. Good choices for this model are White, and 50% :guilabel:`Shine`. *Note that since OpenRocket + thinks this is a regular body tube, the inside of the ring tail won't receive your selected color.* +6. Close the Body tube configuration window, and switch the :guilabel:`View Type:` menu to :guilabel:`Back view`. You should see the ring + tail surrounding and touching the fins. +7. You can look at the rocket in a **3D** View, or in **Photo studio** to see how it will look in the real world. + +Your ring tail is complete. + +In addition to not being able to accurately simulate this model, it's important to note that *the body tube ring tail +**will give you** a "Discontinuity in rocket body diameter" warning too*. + +---- + +Through-the-Wall Fin Mounting +============================= + +Model rocket fins are usually glued to the surface of an airframe. However, when higher thrust motors are used (E and +above) the increased thrust can literally rip fins off or shoot a motor up through the airframe. Instead, +"through-the-wall" (TTW) mounting refers to fins that protrude through a slot in the airframe and are glued to the motor +mount tube, one or more centering rings, and the airframe surrounding the slot. This construction technique significantly +strengthens fin joints and motor mounts. + +There are three measurements necessary to create a fin tab: tab length, tab height, and tab position. + +- **Tab length** is the distance from one side of the fin tab to the other. This is also the length of the slot that is + cut through the airframe, the distance between the inside edges of the outermost centering rings. +- **Tab height** is the distance from outside of the airframe to the outside of the motor mount tube. This is calculated + as follows: (BT OD - MMT OD) / 2, where BT is the airframe body tube and MMT is the motor mount tube diameters. +- **Tab position** is the distance from the root chord reference point to the fin tab reference point. OpenRocket features + three choices: + + Relative to: + + - **the chord root leading edge** – the tab position is the distance from the fin chord root leading edge to the fin tab leading edge. + - **the chord root midpoint** – the tab position is the distance from the fin chord root midpoint to the fin tab midpoint. + - **the chord root trailing edge** – the tab position is the distance from the fin chord root trailing edge to the fin tab trailing edge. + +OpenRocket will automatically calculate fin tab dimensions, within the following constraints: + +- If there are no centering rings beneath a fin, the trailing edge of the fin tab is the fin chord trailing edge and the leading edge of the fin tab is the fin chord leading edge. +- If only one centering ring is beneath a fin, the trailing edge of the fin tab is the fin chord trailing edge and the leading edge of the fin tab is the trailing edge of the centering ring. +- If two centering rings are beneath a fin, the trailing edge of the fin tab is the leading edge of the trailing centering ring and the leading edge of the fin tab is the trailing edge of the leading centering ring. +- If more than two centering rings are beneath a fin, referring to the centering rings in order from the trailing edge to the leading edge of the fin chord, the trailing edge of the fin tab is the leading edge of the first centering ring and the fin tab leading edge is the trailing edge of the second centering ring. OpenRocket supports only one fin tab on each fin. + +Converting a simple rocket to through-the-wall design: + +1. At the OpenRocket **main window**, left-click the :menuselection:`File` menu, then left-click :menuselection:`Open example design` + in the drop-down menu. +2. In the pop-up :menuselection:`Open example design` box, left-click the "*A simple model rocket*" selection, then left-click + the :guilabel:`Open` button. +3. In the **Rocket design** view, double left-click the :guilabel:`Trapezoidal fin set` component. +4. Left-click the :guilabel:`Fin tabs` tab. +5. Left-click the :guilabel:`Calculate automatically` button. + +And, a through-the-wall fin tab is automatically created between the two motor mount centering rings. + +---- + +Electronic and Dual Deployment +============================== + +.. todo:: + Add info on electronic and dual deployment. + +---- + +Clustering and Multi-staging +============================ + +Complex rockets fall into two basic categories, a rocket that is propelled by a cluster of motors intended to be +simultaneously ignited or multi-staged (massively-staged), propelled by a series of motors that successively ignite the +next in line when the prior motor burns out. + +.. figure:: /img/user_guide/advanced_rocket_design/xkcd_whatif_24_model_suborbital.png + :width: 392 px + :align: center + :figclass: or-image-border + + From `xkcd 'what if' #24 `__: *How many model rocket engines would it take to launch a + real rocket to space?*, a 65,000 motor staged-and-clustered rocket. Recommended reading for all rocketeers. + +Motor Clustering +---------------- + +Clustering refers to launching a rocket with more than one simultaneously-ignited rocket motor. Clustering is common in +"real" aerospace programs. Familiar American examples include: the `Gemini Titan `__ +\- a two-motor cluster, the `Saturn V `__ - a cluster of five +Rocketdyne F-1 motors driving the first stage, and the `Falcon 9 `__ +\- a cluster of 9 Merlin motors driving the main stage. + +In model and high-power rocketry, typical clusters seen are **2-motor**, always side-by-side, due to the geometry, +**3-motor**, in a triangle or straight line, **4-motor**, in a square, and **5-motor**, typically arranged with one +central motor surrounded by 4 in a square - though other arrangements are possible. There's nothing preventing much +larger ones, but 2, 3, 4 and 5 are most-often seen. + +In three- and five-motor clusters, it's not uncommon to see a larger or higher-power central motor, surrounded by +smaller or weaker motors. This may be done for effect, or due to modeling constraints, or to more closely resemble its +full-scale inspiration, or possibly for reasons of cost. Clustered motors may be "canted" - that is, pointed to the +outside of the rocket fuselage's circumference, for effect, stability, or spin. + +Designing a Rocket with Clustered Motors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +OpenRocket makes it easy to design motor clusters. To begin with, add an **Inner Tube** to your aft-most **Body Tube**. +On the **Motor** tab, check the "This component is a motor mount" box. Set its inner diameter to one of the standard +motor sizes, unless you have a unique need: 13, 18, 24, 29, 38, 54, 75 or 98mm. Next, click on the **Cluster** tab. + +.. figure:: /img/user_guide/advanced_rocket_design/ClusterTab.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: OpenRocket's **Cluster** tab + +The **Cluster** tab lets you choose a common cluster configuration, and adjust it in your model. When you make an +**Inner Tube** a cluster, you treat every tube in the cluster identically with each addition. If you add an +**Engine block** or a **Mass component**, all of the tubes in the cluster will receive one. + +First, pick a cluster configuration from the image tiles on the left side of the tab. Realize that depending upon the +sizes of your motor tube and body tube, not every cluster that you can make will fit. + +Next, adjust the **Tube separation**. This value controls how close the clustered motors are to each other. A value of +1 places the tubes in contact with each other. You can enter decimals like "1.25" in the separation field. In addition +to potentially affecting your rocket's stability, the **Tube separation** you choose may influence the difficulty of +wiring your clustered motors for ignition, and your ability to place adhesive and parts around tightly-packed tubes +during construction. + +.. figure:: /img/user_guide/advanced_rocket_design/ClusterAft.png + :width: 800 px + :align: center + :figclass: or-image-border + :alt: Clustered motor mounts, viewed from aft. + +The **Rotation** setting rotates your cluster around the major axis of your rocket (the Up <--> Down one). It's used to +line up the motors with other decorative and structural components of your rocket. This alignment may be critical if +you're creating a design that ducts eject gasses from one part of the rocket to another. + +The **Split cluster** button changes this component from a clustered motor component that can be handled as a unit, to +individual motor tubes, which may be positioned and edited independently of each other. Once you split the cluster, +items and settings you change for each tube will not automatically be added to the other tubes in the cluster. You may +want this option if you have motor mount tubes of different lengths or diameters in the cluster. *Once split, a cluster +cannot be recombined*. You must re-create the cluster as a unit if you'd like to revert to that approach. + +Igniting a Cluster +^^^^^^^^^^^^^^^^^^ + +Important to the stability of the rocket's flight is that all the motors ignite more or less simultaneously. The initial +concerns here are that all the motors' igniters are wired to take a single application of voltage from the launch +controller, and that the controller be able to provide adequate voltage and current to ignite all the motors. + +Estes Rockets used to advise that igniter wires be twisted together in either +`series or parallel configurations `__. Each has its advantages: +with a series connection, any burnt igniter will show an open circuit upon arming, while with a parallel connection, the +launch controller can use the same voltage as always, but supply more current to ignite multiple motors at once. Today, +most clusters are wired in parallel, and the rocketeer must ensure that ample current is available for launch. + +Some cluster igniter wiring schemes use a **buss bar** - a short length of regular conductive wire, typically non-insulated, +for ease of connecting to it as needed - as a way of bridging what can be complex connections in a tight space, into an +easier connection plan. For example, you can twist one end of each igniter together in a bundle, and the other end of +each to the buss bar. The launch micro-clips then connect one to the bundle, and the other to the buss bar, for a +parallel connection. + +A convenient tool for igniting a cluster is a **cluster whip** - a set of wires and micro-clips that allows the single +pair of clips at the launch pad to be easily broken into multiple sets of clips, to attach to multiple igniters, and +providing a parallel connection. The cluster whip connects to the igniters, and the launch controller's micro-clips +connect to conductors on the cluster whip. + +Igniting Clustered APCP motors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +APCP (*Ammonium Perchlorate Composite Propellant*) motors typical of Aerotech, Cesaroni, and Loki, are slower to ignite +than Black Powder motors (typical Estes motors). They may unpredictably "chuff", sit quiet for a moment and then ignite, +or even "spit" the igniter out. Because of this difference, and the unpredictability of APCP motor ignition, it's more +than a little likely that clustered APCP motors won't ignite simultaneously, if at all. When designing for an APCP +cluster (if you decide to roll these dice...), take into account what will happen to the rocket if not all motors +ignite before it pulls away from the pad. The safety of observers, and of your airframe hang in the balance. + +Using Clustering for Body Tubes With, or Without Motors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It's possible to create imaginative designs, or mimic scale rockets of yesteryear by using OpenRocket's clustering +capability. One limitation of doing so is that regular **Body tube** components have no Cluster tab. To add Clustered +tubes (which are, by OpenRocket's definition always **Inner Tubes**) using OpenRocket's clustering features, you must +first have a regular **Body tube**. + +You can use your regular **Body tube** as strapping around your clustered tubes, as a **Nose cone** mount, as an eject +gas manifold, or even create a "Vestigial" body tube. To do this, add a regular **Body tube** then set its length to +something like .0001 cm. The **Body tube** will be in the hierarchy and can have **Inner tubes**, but will barely be +seen in the renderings. + +There are some limitations, as **Inner tubes** are not meant to be used in this way. They can't take a **Nose cone** +nor some other components. They won't affect aerodynamics, even if you're trying to make them into tube-fin-like things. +And whether as a unit or as a **Split cluster**, you can't convert **Inner tubes** to **Body tubes**. + +Conventional Staging +-------------------- + +A "closed-hull" design with a separating airframe in which finned-stages holding motors are stacked up, and lower stages +holding burned-out casings separate under pressure as upper stages ignite. Conventional staging is inherently limited to +three stages because of the "Pisa Effect" which results in an increasing arcing trajectory with each stage. + +In designing multi-staged rockets, it's important to realize that the center of mass will tend to start well toward the +rear of the rocket, based on the booster stage(s) weighted with the loaded motors. As booster motors are spent and the +spent stage(s) ejected, the center of mass will tend to move forward. Careful design ensures that the center of mass +remains forward of the center of pressure throughout the flight. Weighting and weight redistribution can move the +center of mass forward, while larger fin area tends to move the center of pressure aft. Ensure at least 1.0 airframe +caliber of separation between the (forward) center of mass and (aft) center of pressure. This is a rule of thumb, not a +hard-and-fast stability solution. + +Rack Staging +------------ + +An "open-hull" design with a non-separating airframe in which motors are staked up, end-to-end, in a frame, and only the +burned-out casings are ejected under pressure as higher stages ignite, stage-after-stage. So long as high average impulse +lower stage motors are used to ensure adequate initial velocities, rack staging is not inherently limited because this +design overcomes the "Pisa Effect." + +Here's a `2007 video demonstrating rack staging `__. + +The BPS Aerospace thrust-vectoring design uses this approach to move a new motor into position for a landing burn. + +Regulatory Concerns +==================== + +Rocketry is subject to regulation by federal, state, and local governments, and most of the regulations that rocketeers +must follow are promulgated by the National Fire Protection Association (NFPA) and the Federal Aviation Administration (FAA). +The NFPA divides rockets into two major classifications, model rockets (NFPA Β§ 1122) and high power rockets (NFPA Β§ 1127), +the difference primarily being weight and power, as follows: + +- **Model Rocket**. A rocket vehicle that weighs no more than 1500 g (53 oz) with motors installed, is propelled by one + or more model rocket motors having an installed total impulse of no more than 320 N-sec (71.9 lb-sec), and contains no + more than a total of 125 g (4.4 oz) of propellant weight. (NFPA Β§ 1122, subd. 3.3.7.2.) +- **High Power Rocket**. A rocket vehicle that weighs more than 1500 g (53 oz) with motors installed and is either + propelled by one or more high power rocket motors or by a combination of model rocket motors having an installed total + impulse of more than 320 N-sec (71.9 lb-sec). (NFPA Β§1127, subd. 3.3.13.1.) + +Within the high power rocket classification, a subclassification for "complex" rockets is defined as a high power rocket +that is multi-staged or propelled by a cluster of two or more rocket motors. (NFPA Β§1127, subd. 3.3.13.1.1.) And, a +high-power rocket launched with an installed total impulse greater than 2,560 N-sec (576 lb-sec) must have an electronically +actuated recovery system. (NFPA Β§1127, subd. 4.10.2.) + +---- + +National Association of Rocketry +================================ + +National Association of Rocketry pursuits the goal of safe, fun and educative sport rocketry. It is the oldest and largest +sport rocketry organization in the world. Visit dedicated `Wiki page `__ +or `NAR official website `__ for more information. + +The major work of the :abbr:`NAR (National Association of Rocketry)` includes, but not limited to: + +- Certification of Rocketry-Related products and establishment of safety codes + + The :abbr:`NAR (National Association of Rocketry)` is a recognized authority for safety certification of consumer + rocket motors and user certification of high- power rocket fliers in the U.S. It plays a major role in establishment + of safety codes for the hobby used and accepted by manufacturers and public safety officials nationwide. + +- Certification of experienced rocketeers + + :abbr:`NAR (National Association of Rocketry)` issues three levels of High Power Rocketry (HPR) certificates, + Level 1 (L1) through Level 3 (L3). Certificates are necessary to purchase powerful rocket motor components. + +- Communication with public officials + + The :abbr:`NAR (National Association of Rocketry)` helps in communication with local public safety officials, and + government regulatory agencies such as the Department of Transportation, Federal Aviation Administration, Bureau of + Alcohol Tobacco Firearms and Explosives, and Consumer Product Safety Commission. + +- Other work + + The :abbr:`NAR (National Association of Rocketry)` publishes the bimonthly color magazine Sport Rocketry (sent to + each member and selected libraries and newsstands around the nation). The :abbr:`NAR (National Association of Rocketry)` + provides a wide range of other services to its members, including: education programs; national and local competitions; + grants to teachers and scholarships for student members; flight performance record recognition; liability insurance; and + publication of technical literature. + +---- + +Tripoli Rocketry Association +============================= + +.. todo:: + + Add information about Tripoli Rocketry Association. diff --git a/docs/source/user_guide/basic_flight_simulation.rst b/docs/source/user_guide/basic_flight_simulation.rst new file mode 100644 index 000000000..31ae81913 --- /dev/null +++ b/docs/source/user_guide/basic_flight_simulation.rst @@ -0,0 +1,285 @@ +*********************** +Basic Flight Simulation +*********************** + +In this section we'll take a quick look at running a basic **Flight Simulation**. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Why simulate? +============= + +Simulations are often used by mid- and high-power rocketeers to determine *what altitude* a rocket and motor combination +will attain, in order to keep it below the maximum launch waiver altitude, or below cloud cover, or just so it won't +disappear miles downwind on the breeze. + +They're also often used to determine how long an *ejection delay* needs to be, if you're using motor ejection. + +You may not have simulated flights on your Estes A, B and C motors, but once you start buying and assembling some of the +many motors you could choose for mid- or high-power rocketry, you'll need to simulate regularly. + +OpenRocket can do the basic simulations for altitude, velocity off the rod/rail, optimum delay with just a few clicks. +But if you'd like to get more deeply into simulation, OpenRocket can graph flight parameters, take local wind speed and +direction into account, and a *lot* more. + +If you already know how to run basic simulations, you can jump to the :doc:`Advanced Rocket Design `. + +---- + +Running a simple simulation +=========================== + +The Flight Simulations window +------------------------------ + +Below you'll see a picture of the **Flight Simulations** window. We're using the *A Simple Model Rocket* example here, +and it includes the list of simulations pictured. + +.. figure:: /img/user_guide/basic_flight_simulation/SimOverview.png + :width: 95% + :align: center + :alt: The Flight Simulations window + :figclass: or-image-border + + The *Flight Simulations* window. + +In the Flight Simulations window, you'll see the simulations listed, initially in Name order. Note that the second column +is **Configuration** - the name of the configuration used in the sim, usually named for the rocket motor used in that +configuration. The remaining values in the simulation's row are calculated by "running" the simulation. You can run +one simulation by selecting a sim and clicking the :guilabel:`Run simulations` button: + +.. figure:: /img/user_guide/basic_flight_simulation/RunOne.png + :width: 95% + :align: center + :alt: Running One Simulation + :figclass: or-image-border + + Running One Simulation. + +...or run them all at once by selecting more than one... + +.. figure:: /img/user_guide/basic_flight_simulation/RunAll.png + :width: 95% + :align: center + :alt: Running All Simulations + :figclass: or-image-border + + Running *All* Simulations. + +...or run them in any combination you choose. + +Simulation Results +------------------ + +Below you'll see the *Simulation Results*. Note that the indicator at each simulation has turned green, and that beside +every working simulation, you'll see a check mark. + +Note also that Simulation 3 has an *exclamation point* instead of a check mark. This is because the simulation reveals +that the motor delay is so short that the rocket will be moving very fast when the parachute comes out. This will +usually cause severe damage to a rocket - called a "*zipper*", where the pulled-taut shock cord cuts a rough slot in +the tube as the chute deploys while the rocket continues to move rapidly forward. + +.. figure:: /img/user_guide/basic_flight_simulation/SimResults.png + :width: 95% + :align: center + :alt: Simulation Results + :figclass: or-image-border + + Simulation Results. + +OpenRocket can detect several conditions which will mark a simulation as non-working. For example: + +- **Too slow off launch rod** - unstable launch +- **Too short a delay** - early deploy of chute, zipper, damage or separation likely +- **Too long a delay** - late deploy of chute, zipper, damage, separation or hard ground-hit likely +- **Ground-hit velocity too high** - damage, and potential danger to ground personnel + +These are common failure conditions, but are not intended to be an exhaustive list. + +.. _motors-configuration: + +---- + +Motors & Configuration +====================== + +To simulate a new motor (or motors) you'll start a **New Configuration**, by clicking the button with that name. Next to +that button are buttons that let you :guilabel:`Rename Configuration`, :guilabel:`Remove Configuration` (i.e. *delete* it from your project), +and :guilabel:`Copy Configuration`. They work about like you'd imagine, on the configuration you've selected. + +Below, you see the **Motors & Configuration** tab for *A Simple Model Rocket*, just after clicking **New Configuration**. + +.. figure:: /img/user_guide/basic_flight_simulation/NewConfiguration.png + :width: 95% + :align: center + :alt: Starting a new configuration + :figclass: or-image-border + + Starting a new configuration. + +From here, you can choose to :guilabel:`Select motor`, :guilabel:`Remove motor`, :guilabel:`Select ignition`, or :guilabel:`Reset ignition`. + +Notice that in the **Motor mounts** section of the **Motors & Configuration** panel, you can see that the **Inner Tube** +is selected as the single motor mount tube. + +More complex models with more motor mount tubes offer you the chance to fly with multiple motors in *Clusters* and *Airstarts*. +The example model rockets in the :menuselection:`File` menu illustrate these multiple motor configurations. To learn more about how +multiple motors are handled, we suggest you load one of these example models and inspect the simulation and motor mount +tube settings. + +Select motor +------------ + +Clicking :guilabel:`Select motor` brings up the **Motor Selection** panel, as shown below. + +.. figure:: /img/user_guide/basic_flight_simulation/SelectAnyMotor.png + :width: 85% + :align: center + :alt: Motor Selection panel + :figclass: or-image-border + + Motor Selection panel. + +From this panel, you can select from many different motors, from many different manufacturers. There are a BUNCH of +motors listed, but don't worry: the gadgets on this panel can help make your selection much easier. + +Ignore :guilabel:`Ejection charge delay` for now. It is one of the most important settings on the page, but we'll come back to it. + +On the left, we see a list of the motors available to OpenRocket, given the filter settings on this page. The list can be +sorted by any column, by clicking the column headers. + +Below the list of motors is a :guilabel:`Search` box, which allows you to do a free-text search against the current list of motors. + +On the right, the :guilabel:`Hide motors already used in the mount` checkbox will help you avoid creating multiple simulations +for the same motor. One is usually enough. + +In the :guilabel:`Manufacturer` section, you can filter to show only motors from particular manufacturers. This is especially +important if you're using reloadable rocket motors: if you want to fly, for example, an AeroTech reloadable motor, only +AeroTech reloads will be of use to you in this chart. + +The :guilabel:`Total Impulse` selector lets you limit the list to the range of motors you want to see. No point in listing +E- through O-impulse motors for *A simple model rocket*: they won't fit (and most of them would tear the rocket to +shreds if they did). + +The :guilabel:`Motor Dimensions` gadgets let you further filter the list to only motors that have the desired mechanical fit in +your rocket. There's no point in trying to fit a motor that is larger diameter than your motor mount tube, though it's +quite common to search for motors that are *smaller* than the maxim motor diameter for a given rocket, and use an adaptor +to bring the motor up to size for the right mechanical fit. + +The motor you select on this page has a characteristic mass, and other characteristics which affect both your simulation, +and the total weight and center of mass of your rocket as shown on the **Rocket Design** page. From that page, you can +select any of your configurations to see the effect on weight and stability. + +Ejection charge delay +--------------------- + +Finally, to :guilabel:`Ejection charge delay`. One of the very common uses for OpenRocket simulations is to determine how long +a delay a motor must have for a successful flight. Too early or too late and the rocket could try to open the chute while +it's moving quickly, causing damage. Way too late or not at all, and the rocket will crash. + +:guilabel:`Ejection charge delay` will have a list of available off-the-shelf ejection charge delays for the motors in the list, +but it's also a free-text field, where you can enter a particular delay in seconds. + +.. figure:: /img/user_guide/basic_flight_simulation/OptimumDelay.png + :width: 100% + :align: left + :alt: The Optimum Delay column + :figclass: or-image-border + + The Optimum Delay column. + +Some motors allow the flyer to pick a standard delay time, and offer tools to reduce the delay. For example, the AeroTech +RMS motors might offer a 10-second delay, but their delay drilling tool allows the flyer to remove 8, 6, 4, or 2 seconds +from this delay time. Other types of motors offer their own methods. + +In the case of adjustable delays, typically you'll set the **Ejection charge delay** iteratively: You start by selecting +a motor, then choose one of the **Ejection charge delay** choices from the menu, then run the simulation. The simulation +results will show you the **Optimum delay** in seconds. You then can return to your motor selection page, and enter that +optimum delay, or as near as you can come to it with the tools at your disposal, in the **Ejection charge delay** field. + +Even if your delay is not adjustable, you'll probably want to look at the **Optimum delay** field and pick a motor with +the delay closest to what your simulation says you'll need for success. + +Show Details +------------ + +The :guilabel:`Show Details` section gives you detailed information about the selected motor's thrust curve, its thrust and burn +parameters, and its certification. + +.. figure:: /img/user_guide/basic_flight_simulation/ShowDetails.png + :width: 35% + :align: center + :alt: The Show Details section + :figclass: or-image-border + + The **Show Details** section. + +---- + +Getting a Good Simulation +========================= + +OpenRocket simulates an *ideal* rocket flying in an *ideal* virtual world. It's a model of how a rocket interacts with +the physics of the real world. As a model, it's useful, but imperfect. OpenRocket's sim can vary from reality due to +many things, for example: + +- Local air density at launch time (a function of local temperature and barometric pressure) +- Manufacturer variations in motor components +- Imperfect match between launch angle or heading from simulation +- Local wind speed, direction, gust mismatch from simulation +- Varying wind speed at altitude, or wind shift during flight +- Performance under stress of real-world components (fin flutter, etc.) +- Imperfect match of simulated model to real model + +That, again, is not an exhaustive list, but the last item: *Imperfect match to real model* counts for a lot. + +It's probably obvious that you have to get the simulated model's weight right to get a good simulation, but what about +its weight distribution? What about its diameter, the match of its nose cone and fin profile to the actual model? Even +the texture of surface components can cause variation in drag as the rocket flies. + +Constructing an accurate digital model +-------------------------------------- + +While you can do OK with matching the weight and center of mass of your OpenRocket model to your real rocket, your best +simulations will come from building the simulated model before you build the actual rocket. To get the most accurate model, +you should weigh every component. And once components are assembled, you should weigh each section to check your work, +comparing it to OpenRocket's calculated masses (glue, filler and finishes add weight, too). + +A digital kitchen scale can be useful to weigh each part as you create a simulation of all the parts of your rocket. +You'll also need to measure thicknesses and lengths. You can obtain inexpensive digital calipers which are fine for this +measuring purpose, from suppliers like `Harbor Freight `_. + +Working in the **Rocket design window**, measure and record the weight of each component as +you model it. Try and choose the correct material to reflect the density and mass of the actual component. Often, +creating a more-correct material (using the :guilabel:`Custom` option of the **Component Material** menu) is a better choice than +using weight overrides, because the weight override may not reflect the correct center of mass of the overridden material. + +Include every component the actual rocket uses, except for the motor: motors are chosen in the +:ref:`Motors & Configuration ` tab. (You can pick a motor configuration for the Rocket design window +from the **Flight configuration** menu there). + +If a part is too light to weigh, weigh multiples of the part, and divide by the number you weighed. If you need to weigh +a short bit of shock cord, weigh 20 feet of it, divide by 20 to get the weight of 1 foot. + +Starting with a downloaded model +-------------------------------- + +If you begin a model with a downloaded OpenRocket (.ork) or RockSim (.rkt) file (*OpenRocket can open both*), check that +the downloaded file's components match your own, and that the specified weight and center of mass match those of your own +model. Often, downloaded files feature **mass overrides** to get the center of mass of an imperfect OpenRocket model to +agree with that of a real-world rocket. These overrides may get the rocket's weight distribution all wrong, so it's +important to adjust the downloaded model to match your rocket exactly. + +Expectations on simulation accuracy +----------------------------------- + +A *very good* simulated design can go a long way toward predicting the correct eject delay and altitude as-flown. + +The better your model, the better the prediction, though note that this author finds that OpenRocket predicts a bit +more altitude than you'll attain most of the time (an average of 29% more in an informal calculation of a dozen of my +logged flights - though the variance ranged from dead-on to 43% off). diff --git a/docs/source/user_guide/basic_rocket_design.rst b/docs/source/user_guide/basic_rocket_design.rst new file mode 100644 index 000000000..fd78ab8f2 --- /dev/null +++ b/docs/source/user_guide/basic_rocket_design.rst @@ -0,0 +1,620 @@ +******************* +Basic Rocket Design +******************* + +In this section we'll look at how to design a basic rocket by examining the A simple model rocket design example. +After reading this section you should have an understanding of how to start designing your own rockets. + +We will start with a brief discussion on the selection of **available components**, and then the components used in +the ``A simple model rocket`` example design file (:menuselection:`File --> Open example --> A simple model rocket`). +Then we'll build a rocket from scratch to see how it’s done. + +.. note:: + + This section assumes you have already :doc:`installed OpenRocket ` and are familiar with the + :doc:`basic layout of the program `. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Component Configuration Window +============================== + +There are several types of components available to you as a rocket designer, and you can either customize them to meet +your needs, or simply load component presets from the parts library. + +To start, let's begin a new project: :menuselection:`File --> New`. It doesn’t matter what we call it at the moment, but go ahead +and save the design straight away: :menuselection:`File --> Save`. At this point you should be presented with a blank rocket design window: + +.. figure:: /img/user_guide/basic_rocket_design/main_window.png + :align: center + :width: 95% + :figclass: or-image-border + :alt: The OpenRocket rocket design window. + + The OpenRocket rocket design window. + +When you first start a new rocket design you will see that there are four categories of components available in the **Add new component** panel +on the top-right of the rocket design window: + +* ``Assembly Components``: These are components that have **no physical meaning** of their own but are used to **group components together**. + +* ``Body Components and Fin Sets``: These are components that are used to **build the rocket's airframe**. + +* ``Inner Components``: These are components that are placed **inside the rocket's airframe**. + +* ``Mass Components``: These are components that are used to **add mass** to the rocket or serve as **recovery devices**. + +We would usually start building our rocket by selecting a nose cone but for the sake of this guide click the +:guilabel:`Body Tube` icon in the **Body Components and Fin Sets** section. This will then open up a configuration window +to edit the body tube parameters. + +The Body Tube Configuration Window +---------------------------------- + +At this point you should see a new window titled **Body tube configuration**. + +.. figure:: /img/user_guide/basic_rocket_design/body_tube_config.png + :align: center + :width: 60% + :figclass: or-image-border + :alt: The Body Tube configuration window. + + The Body Tube configuration window. + +This window allows you to either select a preset for the component type you are choosing, or make your own. Let’s start +by examining how to customize it ourselves. If you have a look at the Body tube configuration window you will see that +at the top there is a :guilabel:`Component name` field. Here we can change the name of the current component to anything we choose. +*(Note that this name will then appear in the design tree seen in the Rocket Design panel of the main program window.)* + +Just below Component name there are several tabs: + +- :guilabel:`General`: allows us to alter the basic attributes of the component. +- :guilabel:`Motor`: allows us to make the body tube into a motor mount, and also edit the properties of the motor. +- :guilabel:`Override`: allows us to manually set the mass or centre of gravity for the component. +- :guilabel:`Appearance`: allows us to select colours, textures and other finishes. +- :guilabel:`Comment`: allows us to enter any comments or notes about the component. + +.. note:: + + These tabs are specific to the component being designed. For example, a *nose cone* will not have + a :guilabel:`Motor` tab, but will instead have a :guilabel:`Shoulder` tab. + +After you learn how to navigate around one component *configuration panel*, the others should be relatively self-explanatory. + +General Tab +^^^^^^^^^^^ + +The rest of the *Body tube configuration* window lists the different parameters for the current component type. As you +can see, the :guilabel:`General` tab provides options to manually enter numbers, or you can also use the spin boxes (coarse control) +or sliders (fine control) provided to adjust the parameter values. The :guilabel:`Automatic` checkbox will adjust the dimensions +of the component automatically. Here you will also see a :guilabel:`Filled` checkbox. If this is checked you will notice that +the inner diameter goes to zero, i.e., a filled (solid) tube. Note how the Component mass changes when this box is checked. + +On the right hand side of the window you will see the :guilabel:`Component material` and :guilabel:`Component finish` drop-down menus. +If you click on these you will be presented with a list of various materials and finishes, each with their own weight and +thickness. If you are using the same finish for the entire rocket you can click the :guilabel:`Set for all` button to make each +component use the same finish. The last notable feature in this window is in the bottom left. There you will see a live +display of the **Component mass**. This will update automatically as you change parameter values. Experiment with the +sliders to see how the component changes in the *design window*. + +You may have noticed that, apart from the mass, there is no noticeable difference when either the :guilabel:`inner diameter` or +:guilabel:`wall thickness` parameters are changed. To see those changes reflected in the model you will have to switch to a +different :guilabel:`View Type`, by selecting the desired view from the drop-down list at the left of the main OpenRocket +program window. + +Motor Tab +^^^^^^^^^ + +Next to the General tab is the :guilabel:`Motor` tab. If you click on it you will see that most parameters are grayed-out, with +the exception of one checkbox. As the label mentions, this is for when you want the body tube component to also be a +**motor mount**. + +.. figure:: /img/user_guide/basic_rocket_design/03.Motor_tube_tab.png + :width: 70% + :align: center + :figclass: or-image-border + :alt: The Motor tab of the Configuration Window + + The *Motor tab* of the Configuration Window. + +Have a quick look at this if you wish, but we'll discuss changing *flight configurations* for a later section of the guide. + +Override +^^^^^^^^ + +We'll take a quick look at this tab, as it common to most components. For starting out though, you most likely will not need it. + +.. figure:: /img/user_guide/basic_rocket_design/04.Body_tube_override_tab.png + :width: 70% + :align: center + :figclass: or-image-border + :alt: The Override tab of the Configuration Window + + The *Override tab* of the Configuration Window. + +This tab would be used when you specifically wanted to override the mass and centre of gravity (CG) of the component. + +Appearance +^^^^^^^^^^ + +Everyone likes something shiny, don’t they? This tab allows you edit the appearance of the component. + +.. figure:: /img/user_guide/basic_rocket_design/05.Body_tube_appearance_tab.png + :width: 70% + :align: center + :figclass: or-image-border + :alt: The Appearance tab of the Configuration Window + + The *Appearance tab* of the Configuration Window. + +There are two sections here, the **Figure style** section and the **Appearance** section. *Figure style* changes what +the 2D figure looks like, whereas *Appearance* will change what the 3D model will look like. If you wish to use any +custom textures or images in your rocket design, you can load those through the **Texture** drop-down menu. + +Comment +^^^^^^^ + +This section does not really need much explanation. If you want to write any comments or notes about your component +(why you chose the values you did, etc.), then this is the place to do it. + +.. figure:: /img/user_guide/basic_rocket_design/06.Body_tube_comment_tab.png + :width: 70% + :align: center + :figclass: or-image-border + :alt: The Comment tab of the Configuration Window + + The *Comment tab* of the Configuration Window. + +Now that we have been through all of the tabs of the *Body Tube* component, click the :guilabel:`Close` button. You should now +notice that the rest of the components are now unlocked in the top right of the *Design window*. This is because all +component types can be added to a body tube. However, a **Nose cone** should be selected **first** if you are making +your own rocket. + +Let’s have a look at the full list of components. If you cannot click on the component type, try selecting the +*Body tube* in the design window in the top left panel of OpenRocket. + +---- + +Available Design Elements +========================= + +As previously mentioned, there are 4 categories to choose components from within OpenRocket. These are split into +four sections: + +- **Assembly Components** +- **Body Components and Fin Sets** +- **Inner Components** +- **Mass Components** + +.. figure:: /img/user_guide/basic_rocket_design/07.Component_menu.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: The Component types menu + + The *Component types* menu. + +Assembly Components +------------------- + +Although called components, Assembly Components are NOT physical parts. Rather, an Assembly Component is an attachment +point on which the framework of the rocket is built (an Assembly Component is a container for physical parts), and each +type has features unique to that attachment type. These framework elements are intended to contain physical components, +and should NOT be left empty. As you will see in the image, the framework types are: + +- **Stage**: Every rocket has at least one stage, which is the basic framework element to which the rocket's physical + components are attached. A Stage may be renamed, and has override and comment tabs. A stage should NOT be used if empty. +- **Boosters**: A booster is a framework element to which physical components are attached, and may be used to build + separate pieces of the rocket, such as a glider. Boosters may ONLY be attached to a body tube, and CAN separate during + flight from the stage to which a booster is associated. Boosters may be renamed, and have separation, general, override, + and comment tabs. A booster should NOT be used if empty. +- **Pods**: A pod is a framework element to which physical components are attached, and may be used to build connected + pieces of the rocket that are adjacent to the main airframe, such as side motors. Pods may ONLY be attached to a body + tube, and CANNOT separate from the stage to which a pod is associated. Pods may be renamed, and have general, override, + and comment tabs. A pod should NOT be used if empty. + +.. figure:: /img/user_guide/basic_rocket_design/08.Assembly_Components_Icons.png + :width: 50% + :align: center + :figclass: or-image-border + :alt: The Assembly Components submenu + + The *Assembly Components* submenu. + +Body Components and Fin Sets +---------------------------- + +Within *Body Components and Fin Sets* we have 8 component types. These components make up the external and main body of +the rocket; everything else is inside the rocket. As you will see in the image the component types are: + +- **Nose Cone**: The very tip of the rocket. Usually, you will select this component first. +- **Body Tube**: As we have seen, the body tube makes up the main section of a stage. +- **Transition**: A component that usually joins one body tube to another (normally larger) tube. +- **Trapezoidal** fin: A fin set that is in the shape of a trapezoid. +- **Elliptical** fin: A fin set that is in the shape of an ellipse. +- **Freeform** fin: This special kind of fin takes any shape you want. If you add it to your model it will open up a + design window for you to alter the shape as desired. +- **Tube Fins** Special fins, typically made from body tubes attached to the outside of the rocket body. +- **Launch Lug**: This component usually goes on the outside of a body tube and is used while the rocket is on the launch pad. + +.. figure:: /img/user_guide/basic_rocket_design/ComponentBodyAndFins.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: The Body Components and Fin Sets submenu + + The *Body Components and Fin Sets* submenu. + +Inner Components +---------------- + +Within *Inner Components* we have 5 component types, and these components are all internal. As with *Body components +and fin sets* we will now run through the list of components. + +- **Inner tube**: This component lets you add tubes to the inside of the main body tube. +- **Coupler**: Used in multi-stage rockets, a coupler joins two sections together. +- **Centering ring**: These can be used to support other components (e.g., a motor), in the centre of a larger tube. +- **Bulkhead**: This is a block of material that forms a stop or barrier between two different areas. +- **Engine block**: An engine block prevents the motor from moving forward in the motor mount tube. + +.. figure:: /img/user_guide/basic_rocket_design/ComponentInner.png + :width: 65% + :align: center + :figclass: or-image-border + :alt: The Inner Components submenu + + The *Inner Components* submenu. + +Mass Components +--------------- + +Within *Mass Components* we have 4 component types. They are: + +- **Parachute**: Like any good parachute, this component will stop your rocket from becoming scrap. +- **Streamer**: Another component for keeping your rocket safe, a streamer creates drag as your rocket falls down to earth. +- **Shock Cord**: A shock cord secures the nose cone to the body of the rocket so that it isn't lost when the nose is + blown off to deploy the parachute/streamer. +- **Mass Component**: This is a block of mass used to adjust the rocket's Center of Gravity (CG). You can name it to + whatever you want it to represent. + +.. figure:: /img/user_guide/basic_rocket_design/ComponentMasses.png + :width: 50% + :align: center + :figclass: or-image-border + :alt: The Mass Components submenu + + The *Mass Components* submenu. + +You have now had a brief run through the various components available for use in OpenRocket. The next section will deal with an example rocket. + +---- + +*A Simple Model Rocket* Example +=============================== + +In this section we will look at the components used in the *A simple model rocket* example design. To get started, start +OpenRocket and navigate to the main window. As a reminder it looks like this: + +.. figure:: /img/user_guide/basic_rocket_design/Main_window.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: The OpenRocket main window + + The OpenRocket *main window*. + +Opening Example Designs +----------------------- + +We'll begin by looking at how to find and load the example rockets within OpenRocket. Recall that this was also covered +in the *Getting Started* section of this guide, but as a refresher the steps for doing this are as follows: + +- In the main window, click on the :menuselection:`File` menu at the top left. +- Scroll down to **Open Examples...** open, and expand that menu. Here you will see a list of the available rocket design examples. + +Your screen should now look like this: + +.. figure:: /img/user_guide/basic_rocket_design/OpenExample.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: Opening an example rocket + + Opening an *example rocket* + +Click on first example, our **A simple model rocket**. A *Rocket configuration* window should appear, with the *Design Name* +(A simple model Rocket) and *Designer* (Sampo Niskanen) fields populated. The *Comments* and *Revision History* fields +will be blank. Click :guilabel:`Close`. You should now have successfully loaded the rocket and be able to see a 2D schematic +in the *Rocket Design* window. + +.. figure:: /img/user_guide/basic_rocket_design/After_complete_design.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: Bottom half of the Rocket design window + + Bottom half of the *Rocket design* window. + +Components used in *A simple model rocket* +------------------------------------------ + +Now we will have a quick look through the components used in the example rocket. If you look towards the top left of +the **Rocket Design** window you will see that there is a tree of components shown. By default they should all be fully +expanded. If not, do so now. + +.. figure:: /img/user_guide/basic_rocket_design/Structure.png + :width: 50% + :align: center + :figclass: or-image-border + :alt: Top left-hand portion of the Rocket design window + + Top left-hand portion of the *Rocket design* window. + +This image shows *A simple model rocket* at the top, followed by the **Sustainer**, which is *Stage 1* of the rocket. + +If we look at the first component in the *Sustainer* stage we see that it is the nose cone. Double click on that now. +This will bring up the *Nose cone configuration* window. + +.. figure:: /img/user_guide/basic_rocket_design/ConfigNose.png + :width: 80% + :align: center + :figclass: or-image-border + :alt: Nose Cone Configuration Window + + Nose Cone Configuration Window. + +As we have already examined the *configuration window* we will not repeat ourselves here. However, you will see that in +this example we have used an **Ogive** nose cone with a *Shape parameter* of 1.0. If you read the description of the +component to the right in the configuration window, you will discover that a value of 1.0 produces a **tangent ogive**. + +Moving down the window, you will see that the **Nose cone length** has a value of 10, the **Base diameter** has a value +of 2.5, and the **Wall thickness** has a value of 0.2. All of these parameters have been set, in this example, to use +centimeters (**cm**) as their unit. You should also see that this component is using **Polystyrene** as its material +with a **Regular paint** finish. As you can see, the material has a density of 1.05 grams per centimeter cubed, and the +paint is 60.0 micrometers thick. In the bottom left, the component *weight* is currently 13.2 grams. Go ahead and play +around with the sliders to see how the component changes, and then change them back when you are finished. + +If you move over to the *Shoulder* tab, you'll be able to see the size attributes of the shoulder. Again, you can play +around with the sliders if you want--as long as you change them back to the original settings when you are finished. +For reference these are **2.3, 2.0** and **0.2** centimeters, respectively. Also have a look through the rest of the +tabs to see what has been selected. The only other thing to note is that the appearance has been customized. If you +were to change to the **3D Finished** view type, you will see how the finished model looks. + +Moving on to the *Body tube*, you can access its various attributes by double-clicking on it in the *Rocket design* window. +Note how its various attributes have been set to create the current size. This is all fairly straightforward and as we +have already looked into the various components earlier, we will not go into great detail here. + +Note the eight other components that have been placed onto the *Body tube*. In descending order these are: + +- **Trapezoidal fin set** +- **Inner Tube** +- **Centering Ring** +- **Centering Ring** +- **Shock Cord** +- **Parachute** +- **Wadding** +- **Launch lug** + +The *Inner Tube* in this design is used as a motor mount. You will see this if you go to the **Motor** tab in the +*Inner Tube configuration* window. This means that a motor has been fitting into this piece. Upon inspection we can +see that the current motor name is displayed in the **Flight configuration** drop-down list, on the right side of the +main OpenRocket window. You can open this drop-down menu to select other motors that are available for use in this +simulation, as well as the other example simulations that you will see on the *Flight simulation* tab. + +The ninth component is place inside the *inner tube*. This is the engine block. If you look at the schematic of the +rocket you will see that this is placed in front of the grey rectangle, which is the motor. To quickly address some of +the other components, you will note that the recovery method used in this rocket is a *Parachute*: the red dashed +rounded-rectangle near the nose cone of the rocket. Along with the parachute we have a *Shock cord*, which (as was +discussed earlier) prevents loss of the nose cone upon deployment of the recovery system. This is shown as a long, black, +dashed rounded-rectangle in the same general area as the parachute. The other black, dashed rounded-rectangle box is the +*Wadding*, which is a mass component and is used here to bring the centre of gravity forward towards the nose. + +We have now looked through the components used within the simple model rocket example. If you would like to see other +available components, see **Appendix A**. Now that we are familiar with what makes up the rocket we will go ahead and +build one from scratch! + +---- + +Building *A simple model rocket* +================================ + +In this section we will build up the example model from scratch. After you have completed this process, you should be +able to apply what you've learned in order to make any basic rocket you want. So let’s begin... + +Open a new project window so that everything is blank. The following are the steps that you will follow to create the rocket. + +1. **Select the nose cone**. Change its type to **Ogive**, if that isn't already selected. Make sure that *Shape parameter*, + *Nose cone length*, *base diameter*, and *Wall thickness* values are set to **1.0**, **10.0**, **2.5** and **0.2**, respectively. + The units are centimeters by default, so we should not need to change these. Finally, change the *Component material* to **Polystyrene**. + +2. Next, while still in the *Nose cone configuration* window, move to the *Shoulder* tab. Change the diameter to **2.3**, the length to **2.0**, and the thickness to **0.2**. Also, check the **End capped** box. + +3. The last thing we have to do with the nose cone is to change its *Appearance*, so switch to that tab now. Leave the *Figure style* section unchanged but under the *Appearance* section, change the colour to one lighter than black. (Or to whatever you want, go crazy!) Then adjust the shine to 50%. That is all we need to change for now. + +You should now see this in the view area at the bottom of the main OpenRocket window: + +.. figure:: /img/user_guide/basic_rocket_design/NoseComplete.png + :width: 80% + :align: center + :figclass: or-image-border + :alt: Nose Cone + + Nose Cone + +4. Next, add the *Body tube*. The measurements for *length*, *outer diameter*, *inner diameter*, and *wall thickness* +are **30.0**, **2.5**, **2.3**, **0.1**, respectively. Note that it may be easier to enter the last two manually rather +than use the spin boxes or sliders. Leave the **Automatic** and **Filled** boxes unchecked. The material should remain +**Cardboard** and the finish should be **Regular Paint**. The only other thing you should change here is the appearance, +but we'll leave that to you as an exercise. + +You should now have this: + +.. figure:: /img/user_guide/basic_rocket_design/BodyComplete.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Nose Cone and Body + + Nose Cone and Body + +5. Moving on, we next need to add a **Fin set**. Make sure you have clicked on the *Body tube* so that it’s highlighted +then click on the :guilabel:`Trapezoidal` component type. The *Trapezoidal fin set configuration* window will have appeared. +Leave the left side of the window alone: the settings there are fine as-is. However, we will need to change some things +on the right hand side. First, change the *Fin cross section* to **Rounded**. Also, reduce the *Thickness* to **0.2**. +That’s all we need to do in this tab. Now move to the *Appearance* tab and customize to your preference. + +.. figure:: /img/user_guide/basic_rocket_design/FinsComplete.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Nose Cone, Body, and Fins + + Nose Cone, Body, and Fins + +6. The next component we need to add is the **Inner tube**. Once again highlight the body tube and then click on the +:guilabel:`Inner tube` component button. There are a couple of attributes we should change here. First, increase the *Length* value +to **7.5**. Also, increase the *Plus* value to **0.5**. Leave everything else the same. + +Now go to the *Motor* tab. There are a few things we need to add here. To start, check the *This component is a motor mount* +checkbox. This will allow us to add motors. The next few steps may seem complicated but do not be daunted by them. First, +we will deal with the easy part: Increase the *Motor overhang* to **0.3**. Now click the :guilabel:`Close` button to close the +*Inner Tube configuration* window. + +.. _motorconfig: + +Now click on the :guilabel:`Motors & Configuration` tab towards the left upper corner of the main OpenRocket window, just under +the menu bar. On the resulting page, note the *Motors* tab towards the left upper corner. Make sure the *Inner T...* box +is checked, and then click on the :guilabel:`New Configuration` button in the top center portion of the upper panel. You should see +that a new configuration has been added to the list of configuration. + +.. figure:: /img/user_guide/basic_rocket_design/MotorConfigs.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: Motors & Configurations window + + Motors & Configurations window + +Left-click in the *Inner Tube* column, and then click the :guilabel:`Select motor` button just below the open panel on the right +of the screen. The *Select a rocket motor* window now appears: + +.. figure:: /img/user_guide/basic_rocket_design/MotorSelection.png + :width: 95% + :align: center + :figclass: or-image-border + :alt: Motor Selection window + + Motor Selection window + +To make sure your window looks the same as the one above, follow these steps: + +- Make sure the *Filter Motors* tab is selected in the top right corner of the window. +- Click :guilabel:`Clear All`, then select only the **Estes** option in the *Manufacturer* list. +- Make sure that the *Total Impulse* slider is positioned over **A** (all the way to the left). +- Check both the "Limit motor diameter to mount diameter" and "Limit motor length to mount length" boxes. +- Look for the **A8** motor in list on the left side of the window. Click on it. +- In the *Ejection charge delay* field at the top left, enter the value **3**. + +Now click the :guilabel:`OK` button at the lower right corner of the window. + +If everything went to plan, you have successfully added the **Estes A8-3** motor to your rocket. Now repeat these steps +for the following motors, using a *New Configuration* for each new motor you add: + +- **Estes B6-4** +- **Estes C6-3** +- **Estes C6-5** +- **Estes C6-7** + +After you have added the rest of the motors, click back on the :guilabel:`Rocket design` tab just under the main menu. + +7. The next component we will add is the **Engine Block**. This time make sure that the *Inner tube* is highlighted and +then add an engine block component. Change the *Inner diameter* to **1.2** and the *Wall thickness* to **0.3**. Also, +change the *Position relative to:* **Top of the parent component**. The last change we will make is to increase *plus* +to **0.2**. That is all we have to do for this component. + +Your rocket should now look like this: + +.. figure:: /img/user_guide/basic_rocket_design/EngineBlockCompleted.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added the Engine Block + + Added the Engine Block + +8. We will now add two **Centering Rings**. Make sure the *Body tube* is highlighted in the list of components under + *Rocket design*, then click on the :guilabel:`Centering ring` component type. The first one is fine as-is, so we will not make + any changes. However, we will add the following line under the :guilabel:`Comment` tab: **The centering ring automatically takes + the outer diameter of the body tube and the inner diameter of the inner tube.** + +Now click :guilabel:`Close`, select the body tube again and add another *Centering ring*. This time all we have to do is to change +*plus* to **-4.5**. Also, add the same comment as for the first ring. + +.. figure:: /img/user_guide/basic_rocket_design/CenteringRings.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added Centering Rings + + Added Centering Rings + +9. The next component we will add is the **Shock cord**. As usual, make sure the *Body tube* is selected before adding +the shock cord component. After it has been added change the *Plus* value to **2**, *Packed length* to **5.2**, and +*Packed diameter* to **1.2**. Again, we will add a comment to this component. Enter the following line to the *Comment* +section: **The shock cord does not need to be attached to anything in particular, as it functions only as a mass component.**. +Click the :guilabel:`Close` button to close the window, as the shock cord has now been completed. + +.. figure:: /img/user_guide/basic_rocket_design/ShockCordComplete.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added Shock Cord + + Added Shock Cord + +10. Now we need to add the **Parachute**. With the body tube highlighted, add a parachute component. Change *Plus* to + **3.2**, *Packed length* to **4.2** and *Packed diameter* to **1.8**. That is everything we need to do to the parachute. + Click :guilabel:`Close` to close the window. You can see what your rocket should now look like below. + +.. figure:: /img/user_guide/basic_rocket_design/ParachuteAdded.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added Parachute + + Added Parachute + +11. The second-to-last component to add is a **Mass Component**. Go ahead and add one to the body tube now. Adjust the + *Mass* to **2** grams (g), the *Approximate density* to **0.16** g/cm^3, the *length* to **3.0**, the *diameter* to + **2.3** and finally the *Plus* value to **8.0**. It may be easier to enter these manually. The last thing you have + to do is to rename it from β€˜Unspecified’ to **Wadding**. Leave everything else as it is and click the :guilabel:`Close` button. + +.. figure:: /img/user_guide/basic_rocket_design/AddedMass.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added Mass + + Added Mass + +12. Almost done! One final component left to add: the **Launch lug**. Add this to the body tube now. Change the *Length* + to **3.5**, the *Outer diameter* to **0.7**, and the *inner diameter* to **0.5**. Leave the *Thickness* as it is. + Also, change the *Radial position* to **19** degrees. Click :guilabel:`Close`. + +.. figure:: /img/user_guide/basic_rocket_design/LaunchLugAdded.png + :width: 90% + :align: center + :figclass: or-image-border + :alt: Added Launch Lug + + Added Launch Lug + +And that’s all there is to it. You have just completed building your first rocket within OpenRocket! From here you can +use what you know to create more rockets, or you can proceed to the next section of the User Guide: +:doc:`Basic Flight Simulation `. Have fun! + diff --git a/docs/source/user_guide/custom_expressions.rst b/docs/source/user_guide/custom_expressions.rst new file mode 100644 index 000000000..73a9c4e63 --- /dev/null +++ b/docs/source/user_guide/custom_expressions.rst @@ -0,0 +1,159 @@ +****************** +Custom Expressions +****************** + +Since OpenRocket 12.09, you are not limited to using just the built-in simulation variables in your plots and +analysis. With the custom expression feature, you can write expressions to calculate other values of interest during the +simulation. These can then be plotted or exported just like the built-in variables. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Overview +======== + +Custom expressions are added to your rocket document from the 'Analyze' menu under custom expressions. This will open a +window showing all your custom expressions. + +.. figure:: /img/user_guide/custom_expressions/custom_expressions.png + :align: center + :width: 55% + :figclass: or-image-border + :alt: The Custom Expressions window. + + The Custom Expressions window. + +Initially, there will be no custom expressions, so you will need to add one using the *New expression* button in the +lower right. This opens the expression builder window. You can also import expressions from another .ork file. + +---- + +Building expressions +==================== + +.. figure:: /img/user_guide/custom_expressions/expression_builder.png + :align: center + :width: 45% + :figclass: or-image-border + :alt: The Expression Builder window. + + The Expression Builder window. + +You must specify a name for the expression, a short symbol, the units of the resulting value, and of course the expression +itself. After you enter a valid value in each of the fields the adjacent indicator will change from red to green. Only +when all indicators are green will you be able to add or update the expression. + +- The :guilabel:`Name` field can be arbitrary; it only must have not been used before. +- The :guilabel:`Symbol` field is intended for a short (locale-independent) symbol representing the value. It must not have been + used before, contain no numbers, whitespaces, or special characters such as brackets or operators. +- There are no restrictions on the :guilabel:`Units`; it can even be empty for dimensionless quantities. However, if you enter a + standard SI unit then you will be able to automatically convert the units when plotting or exporting. The available + SI units are: m, m^2, m/s, kg, kg m^2, kg m^3, N, Ns, s, Pa, V, A, J, W, kg m/s, Hz, K. They must match exactly. +- The :guilabel:`Expression` must only contain valid symbols, operators, and numbers and must make sense mathematically. + For convenience, the adjacent indicator updates on-the-fly. +- It is possible to nest custom expressions, i.e., you can use the symbol defined for a custom expression in another + expression. However, you must ensure that expressions are calculated in the correct order if you do this. This can be + done using the blue arrows in the custom expression pane to adjust the order of calculation. + +To see a list of the available variables and their symbols, click the :guilabel:`Insert Variable` button. This will open a window +from which you can choose a variable and insert it (at the current cursor position) in the expression box. This is +particularly useful because you may not be able to type some of the symbols on your keyboard. The :guilabel:`Insert Operator` +window is similar and shows all the available mathematical operators and functions. + +---- + +Index expressions +================= + +The custom expressions are calculated at each time step of the simulation; however, there are some cases where it is +useful to have access to earlier values of a given variable. This is possible using **index expressions**. These use a +square bracket syntax to specify the time (in seconds) for the variable you want. For example, the expression: + +.. code-block:: none + + m / m[0] + +would give the ratio of the current mass to the launch mass at time 0. Similarly, + +.. code-block:: none + + m - m[t-1] + +would give you the change in mass over the last second. + +You can specify any valid sub-expression inside the square brackets; the only restriction is that you can't nest another +index/range expression inside the square brackets. + +When indexed expressions are calculated, interpolation is used to get the value exactly at the specified time, independent +of the time steps of the simulation. + +If you specify a time smaller than 0 or greater than t then it will be clipped to 0 or t respectively. You can't access +data that has not been calculated yet. + +---- + +Range expressions +================= + +It is sometimes useful to have access to a range of values of a particular variable rather than just one point. +OpenRocket includes a number of useful operators for calculating statistics and other properties of ranges. These +operators can be identified in the operator selection box by the *\[\:\]* which will already have been filled out in place +of one or more of the parameters. + +Range expressions are defined with a square bracket syntax similar to index expressions, but with a ':' used to separate +the lower and upper bounds of a range. For example, suppose we had an accelerometer on our rocket which (as many do) +includes some low-pass filtering on the output. This can be modeled as a moving average and defined with a custom +expression such as: + +.. code-block:: none + + mean(At[t-0.5:t]) + +which will calculate a moving mean for the variable At (total acceleration) over the last 0.5 seconds of data. + +As with index expressions, the upper and lower bounds can be any valid expression. If omitted, the upper bound will +default to t and the lower bound to 0, so the above expression can also be written + +.. code-block:: none + + mean(At[t-0.5:]) + +In this particular case, we might want to make the expression more realistic by clipping accelerations above a given +threshold and perhaps returning the actual voltage from the sensor, for example: + +.. code-block:: none + + 0.2 * uclip( mean(At[t-.5:]), 10 ) + +Note that when range expressions are calculated the data is generated by interpolation over the specified range with a +fixed time step equal to the default time step set in your simulation options. This is independent of the current time step +*dt* used by the simulation engine. When generated, range expressions include the start time and step information. +This facilitates easy integration or optimization with functions such as *trapz([:])* for trapezoidal integration or +*tnear([:],x)* for finding the time value when a variable is nearest a specified value. + +For a complete list of all the operators available see the operator selection list when making a new expression. + +---- + +Troubleshooting +=============== + +While OpenRocket makes a reasonable attempt to check your expression as you enter it, it is still possible to enter +something invalid or that can't be calculated for some reason. In this case you will simply end up with no data available +to plot after running the simulation. + +If you can't figure out why your expression is not generating any data or can't be accepted by the expression builder +then you might find some useful information in the error log. This can be accessed from the help -> debug log menu. Any +relevant messages are probably under the 'USER' category. + +It should not be possible to cause a crash with an invalid expression. If you manage to, please report the bug and +include your expression. + +Custom expressions are interpreted during the simulation and are necessarily much slower than "native" datatypes. +For a few simple expressions you probably won't notice much speed difference but it can become particularly significant +if you have range expressions. If speed is an issue for you then you might want to consider implementing your expression +as a `simulation listener `_. diff --git a/docs/source/user_guide/overrides_and_surface_finish.rst b/docs/source/user_guide/overrides_and_surface_finish.rst new file mode 100644 index 000000000..5f78bfaea --- /dev/null +++ b/docs/source/user_guide/overrides_and_surface_finish.rst @@ -0,0 +1,334 @@ +**************************** +Overrides and Surface Finish +**************************** + +This page explains how to use overrides and surface finish settings to create more accurate OpenRocket simulations. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Using Overrides and Surface Finish to Create More Accurate OpenRocket Simulations +================================================================================= + +As you develop your design, OpenRocket estimates the rocket's stability and performance characteristics based on entered +and known information about the components you choose. As you accumulate parts, and build and test your rocket, you will +obtain more accurate information than what OpenRocket estimated. With this knowledge, you can override the initial +estimates and create more accurate flight simulations. + +On this page, how OpenRocket looks at the different overrides will be explained in more detail, and practical examples +of their use will be given. + +Overrides +--------- + +OpenRocket allows you to override three values that are determinative of a rocket’s flight characteristics: mass, center +of gravity (CG), and coefficient of drag (C\ :sub:`D`). All three of these values can be overridden at the stage level, +the component group level, or the single component level. In addition, while not being an override in its own right, +OpenRocket allows you to adjust the surface roughness of components so that drag estimates more accurately reflect +actual flight data. + +Override Mass +~~~~~~~~~~~~~ + +The database of parts included with OpenRocket has estimates for component masses. These estimates come from a variety +of sources, ranging from data provided by the manufacturer and measured values to calculations based on the volume of +the part and the "standard" density of the material it is made from. The accuracy of these sources varies, but nothing +is more accurate than putting the actual part on a scale and weighing it. Once a part's measured mass is known, the mass +override can be used to change the mass value, more closely reflecting the part's mass, and thereby the rocket's actual +mass. + +Override Center of Gravity +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenRocket also estimates each component's center of gravity based on its materials and geometry, and calculates the +overall center of gravity of each stage, and the entire rocket based on that. However, this really can't account for +the weight of things like glue and paint, which can be significant and can move the center of gravity forward or back. +Once you've got some components assembled, you can measure the CG (using any of the time-honored methods, like hanging +from a string or balancing on a knife edge) and override this, too. + +Override Coefficient of Drag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The drag on a rocket in flight is a function of the rocket's velocity, the density of the atmosphere, the frontal area +of the rocket, and a number called the coefficient of drag. This, in turn, is a result of the airflow over the rocket, +and is estimated based on the rocket's geometry and surface finish. Once you've actually flown the rocket and compared +your simulation to the actual flight, you can adjust the rocket's coefficient of drag to better match the flight data. + +One caution, the coefficient of drag does not remain constant through the flight, especially if the rocket gets near the +speed of sound. At low speeds the friction on the rocket's body dominates the coefficient of drag, but as the speed +increases the effect of the pressure drag (the drag caused by the pressure of the front of the rocket hitting air) and +the base drag (caused by the low pressure area left behind the rocket) becomes progressively more significant. Adjusting +the coefficient of drag based on a flight with a small motor, and using this result to estimate behavior with a larger +motor can give misleading results. How to use drag coefficient overrides to "adjust" a calculated drag coefficient will +be discussed later. + +Override for All Subcomponents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenRocket designs are structured as a tree: each component (except the rocket itself) has a parent component and may +have children (subcomponents). For instance, a single stage rocket will have that single stage as the child of the rocket, +and the stage will have (at least) a nose cone and a body tube as subcomponents. If fins are attached to the body tube, +the fin set is a subcomponent of the body tube. When applying overrides to a component, you can specify whether to apply +the override to all of its subcomponents as well. If you don't override the subcomponents, then the override applied to +the parent component is combined with that of all subcomponents. For instance, suppose a body tube has a calculated mass +of 100 grams and its fins have a calculated mass of 50 grams, the combination of body tube and fin set will have a mass +of 150 grams. If you override the body tube mass, set it to 110 grams, and don't override the subcomponents, the total +mass is now 160 grams. + +If you do override the subcomponents, then the set mass of the parent replaces the mass of the entire subtree. So, using +the same body tube and fin set as before, if you set the mass override of the body tube to 170 grams, and override the +subcomponents, the total mass is 170 grams; the fins contribute no additional mass to the assembly. + +But, why would you want to do this? Ultimately, the goal is to match the simulated mass to the measured mass after the +rocket is finished, taking into account such things as adhesives and any exterior finish (paint and decals). In the case +described above, the mass override is for the entire assembly -- the idea is that if you actually glue the fins to the +body tube and weigh the result at 170 grams, that's what you want the finished mass of the assembly to be. + +Using Overrides to Produce a More Accurate Simulation +----------------------------------------------------- + +Let's look at how you can apply overrides at different points in the design, construction, and simulation of the rocket +to improve the accuracy of your simulations. + +When Designing Your Rocket +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You start designing your rocket by selecting different components, parts that have associated mass values and calculated +values for the center of gravity and coefficient of drag. As you add parts, OpenRocket continuously updates to combined +values, calculating an estimated mass, center of gravity, and coefficient of drag for the entire rocket. Then, based on +your mass and performance goals, you select a motor. When you have, it is time to make sure the center of gravity is +forward of the center of pressure by a comfortable stability margin; assuming it is, you can order your parts and start +putting the rocket together. + +When You Have Your Parts +~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have your parts -- the nose cone, body tube, fin stock, and whatever recovery devices and other hardware you're +using -- you can weigh each component separately. You're likely to find that the parts weigh something close to the +calculated values, but are not exactly right. So, this (the individual part) is the lowest level on which you can +override a mass. After overriding the mass of each part, you can check again to be certain that the center of gravity +is still forward of the center of pressure by a comfortable stability margin, and modify your design as needed. + +As You Build Your Rocket +~~~~~~~~~~~~~~~~~~~~~~~~ + +When assembling your rocket, as you complete subassemblies, you can weigh these subassemblies and measure their centers +of gravity, applying mass and center of gravity overrides at the second (subassembly) level. When applying an override +to a subassembly, you want to check the "Override for all Subcomponents" so that you don't count a subcomponent within +the assembly twice. + +Finally, when your rocket is complete, you can again weigh and measure the center of gravity of the entire rocket, and +apply these overrides at the highest (stage) level. Once again, at this level you'll want to override subcomponents. + +**Note: you should perform this override on every rocket you ever create. This gives the most accurate possible starting +point for your simulations.** + +After Your First Test Flight +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you've flown your rocket for the first time, you can compare your simulations to your actual flight data. Since +each of your simulations was based on overridden measured mass and center of gravity values, the only thing you need to +adjust at this point is drag. You can take two approaches to this, you can adjust the friction drag by changing the +rocket's surface finish, or you can directly modify the drag coefficient. The process is much the same in both cases. + +To change the surface finish, you select external components (parts of the rocket's actual airframe) and simply select +a different surface finish. Then, rerun the simulation again, and compare the new difference between the actual flight +results and your new simulation; you continue to adjust the surface finish until you are satisfied that the simulation +results are as close as possible to the actual flight data. Even though only the airframe surface matters, for the first +few adjustments, it is easier to select a new component finish on any part and then simply click the "Apply to All Components" +button. After you have bracketed your desired simulation result, you can fine-tune the simulation by adjusting the surface +finish for individual components. + +To directly adjust the drag coefficient, you apply a drag coefficient override to the entire stage. In this case you +don't want to override the subcomponents; what you're doing is applying a constant offset to the drag coefficient +being calculated over the course of the flight. + +After applying these modifications, you will have a more accurate simulation for future flights with different motors. + +---- + +How and Why to Use Mass and Center of Gravity Overrides +======================================================= + +Background +---------- + +The β€˜β€™Stageβ€™β€˜, β€˜β€™Boostersβ€™β€˜, and β€˜β€™Podsβ€™β€˜ assembly components feature mass and center of gravity override options that +may be used to adjust the rocket’s margin of stability. Prior to the release of OpenRocket 22.02, the use of these +options overrode the mass and center of gravity of **all** of the assembly subcomponents, limiting the use of these +options to matching the rocket’s finished mass and center of gravity. + +Beginning with the release of OpenRocket 22.02, when using these options, you may choose not to override the mass +and center of gravity of the assembly subcomponents, choosing instead to add to or subtract from the values calculated +by OpenRocket. So, why is this an important change? + +.. _margin_of_stability: + +Margin of Stability +~~~~~~~~~~~~~~~~~~~ + +The recommended **stability margin for subsonic flights is not less than 1.0 caliber**, and **not less than 2.0 calibers +for transonic and supersonic flights**. However, the rocket’s stability margin changes during flight; the rocket can have +momentary marginal stability right off the launch rail with wind, or at high angles of attack at low velocity going +through apogee, but may otherwise be unstable during flight. + +Effect of Rotational Inertia +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The cause of instability during flight is often rooted in the rocket’s rotational inertia (moment of inertia), how the +rocket’s mass is distribution about the axis (center of gravity), with larger moments requiring more torque to change +the rocket’s rate of rotation. When subcomponent mass and center of gravity values are overridden, the rocket’s rotational +inertia is changed, potentially causing the rocket to simulate as stable when it is not, or as unstable when it is, at +less than or near recommended stability margins. + +Benefit of Not Overriding Subassembly Subcomponents +--------------------------------------------------- + +The rocket’s center of gravity can be viewed as the balancing point between the nose cone tip and the end of the motor +nozzle. If a large, heavy motor is used, then weight at the rocket’s tip is needed to balance that weight. And, this +creates a large rotational inertia, which may be significantly changed when the user overrides the subcomponent mass and +center of gravity values. Now, you can add mass at a specific location within the assembly component, without changing +the mass and center of gravity values of subcomponents. + +How the Mass and Center of Gravity Overrides Work +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you select "override for all subcomponents", your value is set as an aggregate Mass or Center of Gravity value. If +you don't select it, your set value is added to the calculated value of the Mass or Center of Gravity. The Coefficient of +Drag override work in the same way. + +Matching Measured Mass and Center of Gravity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In other words, it is now possible to reduce the effect that matching measured mass and center of gravity has on the +rocket’s calculated rotational inertia. The user simply checks the assembly component’s mass and center of gravity +overrides, entering the difference between the measured and calculated values, leaving the override subcomponents box +unchecked. This method is less likely to have a material effect on the rocket’s rotational inertia than overriding all +the subcomponent values. + +Adjustable Weight Systems +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using the assembly component’s mass and center of gravity overrides in this way, you can mimic adjustable weight systems +to compensate for significant changes in motor size and mass. The number of steps involved depends on the precision you +want achieve. + +The approaches described below assume that you have a completed design that you will be making changes to; The steps +below describe how to make the changes to the "A simple model rocket" example include with OpenRocket. + +Simplified Approach +~~~~~~~~~~~~~~~~~~~ + +The simplified approach has three basic steps. + +The first step is to place a *Mass Component* inside the airframe, to match the rocket’s **flight ready** measured weight +and center of gravity (without a motor); it doesn't matter which component it is put inside of because you should position +it relative to the "Tip of the nose cone", entering your measured distance from the rocket's nose cone tip to the rocket's +actual center of gravity. + +The second step, going to the *Stage configuration* pane, is to enter the distance from the tip of the nose cone to the +center of your adjustable weight as the *Override center of gravity* distance. + +The third step is really two companion steps, you select your preferred motor configuration, and, on the +*Stage configuration* pane, you adjust the mass override value until you have a comfortable margin of stability between +the center of gravity and center of pressure (see, :ref:`Margin of Stability `). Then, last of all, **don't forget to actually +add that amount of weight to your rocket's adjustable weight system**. + +After that, before you head out to the range, actually install the motor (without the igniter) and verify the margin of +stability; it's always nice to put markers on the rocket, blue for the center of gravity and red for the center of pressure. + +Precision Approach +~~~~~~~~~~~~~~~~~~ + +The highest level of precision requires that the mass overrides be used for **each component** and **each subassembly**, +and, finally, at the **stage** level. To achieve this precision, there are a few additional steps: + +1. Lay out, weigh, and enter the mass override for each of the parts. +2. Using the component tree as your reference, identify each component that has one or more subcomponents under it. + These components will be referred to as parents and the component and its subcomponents, together, will be called a + subassembly; oft times there are nested subcomponents and each component with a subcomponent is a parent. +3. While building the rocket, each time a subassembly is completed, weigh that subassembly and enter the mass override + value on the parent's configuration override tab, checking the "Override mass and CG of all subcomponents" box. This will + take into account the additional mass of adhesives, fasteners, and the like. + +From here, follow the `Simplified Approach`_ steps, above, which describes how to make the remaining changes. + +As stated before, before you head out to the range, **actually install the motor (without the igniter) and *verify the +margin of stability***; again, it's always nice to put markers on the rocket, blue for the center of gravity and red for +the center of pressure. + +---- + +How and Why to Use Surface Finish Settings and Coefficient of Drag (C\ :sub:`D`) Overrides +========================================================================================== + +When you have finished your rocket, and adjusted the mass and center of gravity overrides as described above, there are +two remaining factors affecting flight performance that can be adjusted, the rocket's coefficient of drag and surface +finish (roughness). After you have flown your rocket and collected flight data (using an altimeter or other device), +you can compare the actual flight results to the OpenRocket simulation projections and make changes to the rocket's +(C\ :sub:`D`) or surface finish to bring the simulated results in line with the actual collected fight data. + +The first step is usually bracketing the desire drag coefficient by changing the rocket's *Surface Finish*, and the +second is fine tuning the (C\ :sub:`D`) with the *Stage* level override. You can adjust the rocket's (C\ :sub:`D`) by +changing its surface roughness or by overriding its overall (C\ :sub:`D`), or a combination of both, depending upon the +precision you desire. + +Using Surface Finish (Roughness) Settings +----------------------------------------- + +The surface finish that you use for your rocket affects how air flows over the airframe (the smoother the surface, the +less the resistance; the rougher the surface, the greater the resistance). And, another word for this resistance is drag. +So, an adjustment to surface roughness changes the rocket's (C\ :sub:`D`). + +As with other component specific characteristics, each component has its own *Surface Finish* setting, although you can +change the *Surface Finish* of every component by left-clicking the *Set for all* button on any *Appearance* tab. This +is similar to the override subcomponents feature, but only changes the components that exist at the time it us used; +parts added after using the *Set for all* feature will have the default roughness. OpenRocket allows you to select one +of five roughness settings, *Rough*, *Unfinished*, *Regular paint*, *Smooth paint*, and *Polished*, each with a +decreasing (C\ :sub:`D`) from rough to polished. + +Using your actual collected flight data, by making the exterior of your rocket's surface rougher or smoother, you are +changing the rocket's overall (C\ :sub:`D`) without overriding the (C\ :sub:`D`) of any components. This method retains +all of the component (C\ :sub:`D`) values and does not affect the simulation's ability to calculate the natural +(C\ :sub:`D`) variations caused by changes in velocity and atmospheric density during flight. + +When making changes using this method, a change is made to the *Surface Finish* setting, the simulation is rerun, and +the results compared. You then repeat this until you have bracketed the comparison between the actual collected flight +results and the simulation results. Then, out of the two bracketing simulations, set the *Surface Finish* to the setting +used in the simulation with the lowest results. If you want even more precision, adjust the Rocket's (C\ :sub:`D`) as +described below. + +Using Coefficient of Drag (C\ :sub:`D`) Overrides +------------------------------------------------- + +How the Stage Coefficient of Drag Override Works +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you select "override for all subcomponents", your value is set as an aggregate (C\ :sub:`D`) value. If you don't +select it, your set value is added to the calculated value. This is consistent with how the mass and CG overrides work. + +Using the Stage Coefficient of Drag Override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The coefficient of drag relates to a thing's resistance to airflow, and changes with velocity and the density of the +atmosphere, especially if the rocket gets near the speed of sound. Only the rocket's exterior components that comprise +the airframe of the rocket are exposed to the flow of air over the rocket and have a (C\ :sub:`D`) value that affects +flight performance. And adjusting the coefficient of drag for the entire rocket based on a flight with a small motor, +then using those results to estimate behavior with a larger motor can give misleading results. Because of this, and the +practical impossibility for most users to measure the drag of each component, or the finished rocket for that matter, +*overriding the (*C\ :sub:`D`*) at the component and subassembly levels is* **NOT recommended**. + +However, armed with actual collected flight data, you can add or subtract from the rocket's overall (C\ :sub:`D`) at the +"Stage" level by NOT overriding the (C\ :sub:`D`) of subcomponents. Practically speaking, this method retains all of the +individual component (C\ :sub:`D`) values, but nudges the (C\ :sub:`D`) of the entire rocket just a bit more. And, +OpenRocket uses this nudge to more closely match actual flight and simulation results, *without affecting the simulation's +ability to calculate the natural (*C\ :sub:`D`*) variations caused by changes in velocity and atmospheric density during +flight*. + +When making changes using this method, a change is made to the (C\ :sub:`D`), the simulation is rerun, and the results +compared. You then repeat this until you are satisfied with the comparison between the actual collected flight results +and the simulation results. diff --git a/docs/source/user_guide/rocket_analysis.rst b/docs/source/user_guide/rocket_analysis.rst new file mode 100644 index 000000000..f91419b50 --- /dev/null +++ b/docs/source/user_guide/rocket_analysis.rst @@ -0,0 +1,16 @@ +*************** +Rocket Analysis +*************** + +.. attention:: + + This chapter is a work in progress. + +.. todo:: + + - *add a section on the component analysis dialog* + - *add a section on the plottable variables* + - *add a section on exporting simulation data* + - *add a section on print / pdf export* + - *check overlap with the Advanced Flight Simulation section* + diff --git a/docs/source/user_guide/simulation_extensions.rst b/docs/source/user_guide/simulation_extensions.rst new file mode 100644 index 000000000..1caa9f274 --- /dev/null +++ b/docs/source/user_guide/simulation_extensions.rst @@ -0,0 +1,459 @@ +********************* +Simulation Extensions +********************* + +By using OpenRocket's extension and listener mechanism, it's possible to modify the program itself to add features that +are not supported by the program as distributed; some extensions that have been created already provide the ability to +air-start a rocket, to add active roll control, and to calculate and save extra flight data. + +This page will discuss extensions and simulations. We'll start by showing how a simulation is executed +(so you can get a taste of what's possible), and then document the process of creating the extension. + +.. warning:: + + Writing an extension inserts new code into the program. It is entirely possible to disrupt a simulation in a way that + invalidates simulation results, or can even crash the program. Be careful! + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +---- + +Adding an Existing Extension to a Simulation +============================================ + +Extensions are added to a simulation through a menu in the "Simulation Options" tab. + +1. Open a .ork file and go to the **Flight Simulations** tab. +2. Click the **Edit simulation** button to open the **Edit simulation** dialog. +3. Go to the **Simulation options** tab. +4. Click the **Add extension** button. + +This will open a menu similar to the one in the following screenshot: + +.. figure:: /img/user_guide/simulation_extensions/Extension-menu.png + :align: center + :width: 35% + :figclass: or-image-border + :alt: Extension menu + + Extension menu. + +Clicking on the name of an extension will add it to the simulation; if it has a configuration dialog the dialog will be opened: + +.. figure:: /img/user_guide/simulation_extensions/Air-start-configuration.png + :align: center + :width: 45% + :figclass: or-image-border + :alt: Air-start configuration dialog + + Air-start configuration dialog. + +In the case of the air-start extension, the configuration dialog allows you to set the altitude and velocity at which +your simulation will begin. After you close the configuration dialog (if any), a new panel will be added to the +**Simulation options** pane, showing the new extension with buttons to reconfigure it, obtain information about it, or +remove it from the simulation: + +.. figure:: /img/user_guide/simulation_extensions/Air-start-pane.png + :align: center + :width: 35% + :figclass: or-image-border + :alt: Air-start extension pane + + Air-start extension pane. + +---- + +Creating a New OpenRocket Extension +=================================== + +The remainder of this page will describe how a new simulation extension is created. + +Preliminary Concepts +-------------------- + +Before we can discuss writing an extension, we need to briefly discuss some of the internals of OpenRocket. In particular, +we need to talk about the simulation status, flight data, and simulation listeners. + +Simulation Status +~~~~~~~~~~~~~~~~~ + +As a simulation proceeds, it maintains its state in a `SimulationStatus`. The `SimulationStatus` object contains +information about the rocket's current position, orientation, velocity, and simulation state. It also contains a +reference to a copy of the rocket design and its configuration. Any simulation listener method may modify the state of +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 +rocket's current position is returned by calling `getRocketPosition()`; the rocket's position can be changed by calling +`setRocketPosition`. 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 +this way, it is not as complete as that found in `FlightData` and `FlightDataBranch` objects. + +Flight Data +~~~~~~~~~~~ + +OpenRocket refers to simulation variables as `FlightDataType`s, which are `List` 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 +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 +`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)`. + +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. + +Finally, the collection of all of the `FlightDataBranch`es and some summary data for the simulation is stored in a +`FlightData` object. + +Flight Conditions +~~~~~~~~~~~~~~~~~ + +Current data regarding the aerodynamics of the flight itself are stored in a ``FlightConditions`` object. This includes +things like the velocity, angle of attack, and roll and pitch angle and rates. It also contains a reference to the +current ``AtmosphericConditions``. + +Simulation Listeners +~~~~~~~~~~~~~~~~~~~~ + +Simulation listeners are methods that OpenRocket calls at specified points in the computation to either record +information or modify the simulation state. These are divided into three interface classes, named ``SimulationListener``, +``SimulationComputationListener``, and ``SimulationEventListener``. + +All of these interfaces are implemented by the abstract class ``AbstractSimulationListener``. This class provides empty +methods for all of the methods defined in the three interfaces, which are overridden as needed when writing a listener. +A typical listener method (which is actually in the Air-start listener), would be: + +.. code-block:: java + + public void startSimulation(SimulationStatus status) throws SimulationException { + status.setRocketPosition(new Coordinate(0, 0, getLaunchAltitude())); + status.setRocketVelocity(status.getRocketOrientationQuaternion().rotate(new Coordinate(0, 0, getLaunchVelocity()))); + } + +This method is called when the simulation is first started. It obtains the desired launch altitude and velocity from its +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 +:file:`core/src/net/sf/openrocket/simulation/listeners/AbstractSimulationListener.java`. + +The listener methods can have three return value types: + +* The ``startSimulation()``, ``endSimulation()``, and ``postStep()`` are called at a specific point of the simulation. They are + void methods and do not return any value. +* The ``preStep()`` and event-related hook methods return a boolean value indicating whether the associated action should + be taken or not. A return value of ``true`` indicates that the action should be taken as normally would be (default), + ``false`` will inhibit the action. +* The pre- and post-computation methods may return the computed value, either as an object or a double value. The + pre-computation methods allow pre-empting the entire computation, while the post-computation methods allow augmenting + the computed values. These methods may return ``null`` or ``Double.NaN`` to use the original values (default), or return + an overriding value. + +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), +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. + +If a simulation listener wants to stop a simulation prematurely without an error condition, it needs to add a flight +event of type ``FlightEvent.SIMULATION_END`` to the simulation event queue: + +.. code-block:: java + + status.getEventQueue().add(new FlightEvent(FlightEvent.Type.SIMULATION_END, status.getSimulationTime(), null)); + +This will cause the simulation to be terminated normally. + +Creating a New Simulation Extension +----------------------------------- + +Creating an extension for OpenRocket requires writing three classes: + +* A listener, which extends ``AbstractSimulationListener``. This will be the bulk of your extension, and performs all the real work. +* An extension, which extends ``AbstractSimulationExtension``. This inserts your listener into the simulation. Your listener + can (and ordinarily will) be private to your extension. +* A provider, which extends ``AbstractSimulationExtensionProvider``. This puts your extension into the menu described above. + +In addition, if your extension will have a configuration GUI, you will need to write: + +* A configurator, which extends ``AbstractSwingSimulationExtensionConfigurator`` + +You can either create your extension outside the source tree and make sure it is in a directory that is in your Java +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 +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: + +.. code-block:: java + + core/src/net/sf/openrocket/simulation/extension/example/ + +This is where the extension examples provided with OpenRocket are located. Your configurator, if any, will logically go in: + +.. code-block:: java + + swing/src/net/sf/openrocket/simulation/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. +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 +start velocity. + +.. code-block:: java + + package net.sf.openrocket.simulation.extension.example; + + import net.sf.openrocket.simulation.SimulationStatus; + import net.sf.openrocket.simulation.exception.SimulationException; + import net.sf.openrocket.simulation.extension.AbstractSimulationExtension; + import net.sf.openrocket.simulation.listeners.AbstractSimulationListener; + import net.sf.openrocket.util.Coordinate; + + /** + * Simulation extension that launches a rocket from a specific altitude. + */ + public class AirStartExample extends AbstractSimulationExtension { + + public void initialize(SimulationConditions conditions) throws SimulationException { + conditions.getSimulationListenerList().add(new AirStartListener()); + } + + @Override + public String getName() { + return "Air-Start Example"; + } + + @Override + public String getDescription() { + return "Simple extension example for air-start"; + } + + private class AirStartListener extends AbstractSimulationListener { + + @Override + public void startSimulation(SimulationStatus status) throws SimulationException { + status.setRocketPosition(new Coordinate(0, 0, 1000.0)); + } + } + } + +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 + only method that is required to be defined in your extension. +* The ``getName()`` method in lines 19-21, 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 + ``"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. + 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 + 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 +actually use it, we need a provider, like this: + +.. code-block:: java + + package net.sf.openrocket.simulation.extension.example; + + import net.sf.openrocket.plugin.Plugin; + import net.sf.openrocket.simulation.extension.AbstractSimulationExtensionProvider; + + @Plugin + public class AirStartExampleProvider extends AbstractSimulationExtensionProvider { + 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 +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` +and the provider in :file:`core/src/net/sf/openrocket/simulation/extensions/example/AirStartExampleProvider.java`, compiling, +and running 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. + +Adding a Configurator +--------------------- + +To be able to configure the extension at runtime, we need to write a configurator and provide it with a way to +communicate with the extension. First, we'll modify the extension as follows: + +.. code-block:: java + + package net.sf.openrocket.simulation.extension.example; + + import net.sf.openrocket.simulation.SimulationStatus; + import net.sf.openrocket.simulation.exception.SimulationException; + import net.sf.openrocket.simulation.extension.AbstractSimulationExtension; + import net.sf.openrocket.simulation.listeners.AbstractSimulationListener; + import net.sf.openrocket.util.Coordinate; + + /** + * Simulation extension that launches a rocket from a specific altitude. + */ + public class AirStartExample extends AbstractSimulationExtension { + + public void initialize(SimulationConditions conditions) throws SimulationException { + conditions.getSimulationListenerList().add(new AirStartListener()); + } + + @Override + public String getName() { + return "Air-Start Example"; + } + + @Override + public String getDescription() { + return "Simple extension example for air-start"; + } + + public double getLaunchAltitude() { + return config.getDouble("launchAltitude", 1000.0); + } + + public void setLaunchAltitude(double launchAltitude) { + config.put("launchAltitude", launchAltitude); + fireChangeEvent(); + } + + private class AirStartListener extends AbstractSimulationListener { + + @Override + public void startSimulation(SimulationStatus status) throws SimulationException { + status.setRocketPosition(new Coordinate(0, 0, 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 +``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 +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"``. + +The ``getLaunchAltitude()`` method obtains the air-start altitude for the simulation from the configuration, and sets a +default air-start altitude of 1000 meters. Our ``startSimulation()`` method has been modified to make use of this to obtain +the user's requested air-start altitude from the configurator, in place of the original hard-coded value. + +The ``setLaunchAltitude()`` method places a new launch altitude in the configuration. While our extension doesn't make +use of this method directly, it will be necessary for our configurator. The call to ``fireChangeEvent()`` in this method +assures that the changes we make to the air-start altitude are propagated throughout the simulation. + +The configurator itself looks like this: + +.. code-block:: java + + package net.sf.openrocket.simulation.extension.example; + + import javax.swing.JComponent; + import javax.swing.JLabel; + import javax.swing.JPanel; + import javax.swing.JSpinner; + + import net.sf.openrocket.document.Simulation; + import net.sf.openrocket.gui.SpinnerEditor; + import net.sf.openrocket.gui.adaptors.DoubleModel; + import net.sf.openrocket.gui.components.BasicSlider; + import net.sf.openrocket.gui.components.UnitSelector; + import net.sf.openrocket.plugin.Plugin; + import net.sf.openrocket.simulation.extension.AbstractSwingSimulationExtensionConfigurator; + import net.sf.openrocket.unit.UnitGroup; + + @Plugin + public class AirStartConfigurator extends AbstractSwingSimulationExtensionConfigurator { + + public AirStartConfigurator() { + super(AirStart.class); + } + + @Override + protected JComponent getConfigurationComponent(AirStart extension, Simulation simulation, JPanel panel) { + panel.add(new JLabel("Launch altitude:")); + + DoubleModel m = new DoubleModel(extension, "LaunchAltitude", UnitGroup.UNITS_DISTANCE, 0); + + JSpinner spin = new JSpinner(m.getSpinnerModel()); + spin.setEditor(new SpinnerEditor(spin)); + panel.add(spin, "w 65lp!"); + + UnitSelector unit = new UnitSelector(m); + panel.add(unit, "w 25"); + + BasicSlider slider = new BasicSlider(m.getSliderModel(0, 5000)); + panel.add(slider, "w 75lp, wrap"); + + return panel; + } + } + +After some boilerplate, this class creates a new ``DoubleModel`` to manage the air-start altitude. The most important things +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()`` + methods mentioned earlier. 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. +* ``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 + and unit displays for the interface. The available ``UnitGroup`` options are defined in :file:`core/src/net/sf/openrocket/unit/UnitGroup.java`. + +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: + +.. figure:: /img/user_guide/simulation_extensions/Example_Configurator.png + :align: center + :width: 45% + :figclass: or-image-border + :alt: Example configurator + + Example configurator. + +The surrounding Dialog window and the **Close** button are provided by the system. + +---- + +Example User Extensions Provided With OpenRocket +================================================ + +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 +in :file:`swing/src/net/sf/openrocket/simulation/extension/example`. Also recall that every extension has a corresponding +provider. + +.. list-table:: + :header-rows: 1 + + * - Purpose + - Extension + - Configurator + * - Set air-start altitude and velocity + - `AirStart.java` + - `AirStartConfigurator.java` + * - Save some simulation values as a CSV file + - `CSVSave.java` + - *(none)* + * - Calculate damping moment coefficient after every simulation step + - `DampingMoment.java` + - *(none)* + * - Print summary of simulation progress after each step + - `PrintSimulation.java` + - *(none)* + * - Active roll control + - `RollControl.java` + - `RollControlConfigurator.java` + * - Stop simulation at specified time or number of steps + - `StopSimulation` + - `StopSimulationConfigurator` + +.. note:: + Documentation for adding user-created simulation listeners, without making use of the full extension mechanism, is also + available at ``Simulation Listeners``. diff --git a/docs/source/user_guide/thrust_curves.rst b/docs/source/user_guide/thrust_curves.rst new file mode 100644 index 000000000..8d3a765d8 --- /dev/null +++ b/docs/source/user_guide/thrust_curves.rst @@ -0,0 +1,10 @@ +************* +Thrust Curves +************* + +.. _importing_thrust_curves: + +Import Custom Thrust Curves +=========================== + +To set up the thrust curves folder(s), please see the :ref:`Thrust Curves Folder Settings ` section. diff --git a/install4j/23.09/.gitignore b/install4j/23.09/.gitignore index 60eadae4b..e5557ddcd 100644 --- a/install4j/23.09/.gitignore +++ b/install4j/23.09/.gitignore @@ -20,3 +20,5 @@ media/ .DS_Store code_signing/ + +macOS_resources/template_dmg_rw.dmg