Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

How to Add a Command to GMAT
Linda Jun, GSFC, Code 583
January 20, 2015
Table of Contents
Introduction
Overview
Required Methods
Required First Steps
General Requirements
Recommended Practices
Adding a New Command
Base Code modifications:
GUI Code modifications:
System Test Readiness Criteria
Appendix A: Example
Appendix B: Example Code
Display.hpp
Display.cpp
Introduction1
Overview2
Required Methods4
Required First Steps4
General Requirements5
Recommended Practices5
Adding a New Command5
Base Code modifications:5
GUI Code modifications:6
System Test Readiness Criteria6
Appendix A: Example7
Appendix B: Example Code11
Display.hpp11
Display.cpp12cpp 

Anchor
_Toc410915583
_Toc410915583
Introduction


A Command represents sets of instruction(s) to perform a certain task in GMAT. A Command is associated with one or more Resources and describes how associated Resources will be utilized and evolved over time. Commands are sequential and they run in sequential order, which is called the Mission Control Sequence. Commands in GMAT are created in order, via script or GUI, for running a mission.
The following shows sample scripting of mission sequence:


The following shows the mission sequence of the above script in GUI mode.



There are many types of built-in Commands for use in spacecraft missions. However, new Commands can be created to extend GMAT and perform a new desired task.
This document will describe a general procedure how to add a new Command to the baseline GMAT code. If you would prefer to add your new Command as a plugin, please see instead the document "Building a GMAT Plug-in: A Walkthrough Using Visual Studio 2010".

Anchor
_Toc410915584
_Toc410915584
Overview

...

  1. If you want to show customized icon for a new Command from the Mission tree, insert your new Command type to MissionIconType in /src/gui/app/GuiTreeItem.hpp. The new Command type must to be inserted between MISSION_ICON_OPENFOLDER and MISSION_ICON_DEFAULT. Add a statement to load the new Command icon file at the same position where new Type was inserted to MissionIconType in MissionTree.cpp in /src/gui/mission/MissionTree::AddIcons() since bitmaps index should match with the position in MissionIconType.
  2. If you want to specially handle the new Command type, for example creating different popup menu, add your new type in ItemType in /src/gui/app/GuiTreeItem.hpp and implement appropriately in MissionTree.cpp.
  3. Check CreateNewCommand() in /src/gui/app/GmatMainFrame.cpp to see if you need to add or modify the list (i.e. look in the switch statement), to match the modifications to GmatTreeItemData.
  4. Decide whether you can use the GmatCommandPanel which is a generic panel for a Command, or if you will need a custom GUI panel for your new Command. See "How to Create GMAT panels" for further instructions on creating a new GUI panel.
  5. Add your new class(es) to the MakeGui.eclipse file to make sure it is compiled
  6. Add your new Command class(es) to Microsoft Visual C++ 2010 Express GMAT_wxGui project if you prefer to build GMAT using MS Visual Studio.

 

Anchor
_Toc410915592
_Toc410915592
System Test Readiness Criteria

...

  1. Run unit-tests with the new code – these unit-tests must be thorough and should use input test data obtained from GMAT engineers when available
  2. Coordinate with GMAT team members to deliver code modifications

 

Anchor
_Toc410915593
_Toc410915593
Appendix A: Example

...

Anchor
_Toc410915595
_Toc410915595
Display.hpp

 

Code Block
languagecpp
//$Id$
 //------------------------------------------------------------------------------
 // Display
 //------------------------------------------------------------------------------
 // GMAT: General Mission Analysis Tool.
 //
 // Copyright (c) 2002-2014 United States Government as represented by the
 // Administrator of The National Aeronautics and Space Administration.
 // All Other Rights Reserved.
 //
 // Author: Linda Jun (NASA/GSFC)
 // Created: 2014/10/16
 //
 // Developed jointly by NASA/GSFC and Thinking Systems, Inc. under contract
 // number S-67573-G
 //
 /**Class declaration for the Display command
 */
 //------------------------------------------------------------------------------
 #ifndef Display_hpp
 #define Display_hpp 
 #include "GmatCommand.hpp"
 #include "ElementWrapper.hpp" 
 /**
Command used to write data to Message Window.
 */
 class GMAT_API Display : public GmatCommand
 {
 public:
 Display();
 virtual ~Display();
 Display(const Display& display);
 Display& operator=(const Display& display); 
 // inherited from GmatCommand
 virtual bool Execute();
 virtual bool InterpretAction();
 virtual bool SetElementWrapper(ElementWrapper* toWrapper,
 const std::string &withName);
 virtual void ClearWrappers(); 
 // inherited from GmatBase
 virtual bool Initialize();
 virtual GmatBase* Clone(void) const;
 virtual bool RenameRefObject(const Gmat::ObjectType type,
 const std::string &oldName,
 const std::string &newName);
 virtual const StringArray&
 GetWrapperObjectNameArray(bool completeSet = false); 
 // Parameter accessors
 virtual std::string GetParameterText(const Integer id) const;
 virtual Integer GetParameterID(const std::string &str) const;
 virtual Gmat::ParameterType
 GetParameterType(const Integer id) const;
 virtual std::string GetParameterTypeString(const Integer id) const; 
 virtual std::string GetStringParameter(const Integer id) const;
 virtual std::string GetStringParameter(const std::string &label) const;
 virtual bool SetStringParameter(const Integer id, 
 const std::string &value);
 virtual bool SetStringParameter(const std::string &label, 
 const std::string &value); 
 // for generating string
 virtual const std::string&
 GetGeneratingString(
 Gmat::WriteMode mode = Gmat::SCRIPTING,
 const std::string &prefix = "",
 const std::string &useName = ""); 
 DEFAULT_TO_NO_CLONES 
 protected:
 // Parameter IDs
 enum 
 {
 PARAM_NAME = GmatCommandParamCount,
 DisplayParamCount
 }; 
 std::string paramName;
 ElementWrapper *paramWrapper; 
 static const std::string
 PARAMETER_TEXT[DisplayParamCount - GmatCommandParamCount];
 static const Gmat::ParameterType
 PARAMETER_TYPE[DisplayParamCount - GmatCommandParamCount];
 }; 
 #endif // Display_hpp 
 

...

  • Anchor
    _Toc410915596
    _Toc410915596
    Display.cpp

    Code Block
    languagecpp
    //$Id$

    
     //------------------------------------------------------------------------------

    
     // Display

    
     //------------------------------------------------------------------------------

    
     // GMAT: General Mission Analysis Tool.

    
     //

    
     // Copyright (c) 2002-2014 United States Government as represented by the

    
     // Administrator of The National Aeronautics and Space Administration.

    
     // All Other Rights Reserved.

    
     //

    
     // Author: Linda Jun (NASA/GSFC)

    
     // Created: 2014/10/16

    
     //

    
     // Developed jointly by NASA/GSFC and Thinking Systems, Inc. under contract

    
     // number S-67573-G

    
     //

    
     /**
    
    
    Class implementation for the Display command

    
     */

    
     //------------------------------------------------------------------------------

     
     #include "Display.hpp"

    
     #include "CommandException.hpp"

    
     #include "StringUtil.hpp" // for ToString()

    
     #include "MessageInterface.hpp" // for ShowMessage()

     
     //#define DEBUG_DISPLAY_IA

    
     //#define DEBUG_DISPLAY_INIT

    
     //#define DEBUG_DISPLAY_EXE

     
     //---------------------------------

    
     // static data

    
     //---------------------------------

    
     const std::string

    
     Display::PARAMETER_TEXT[DisplayParamCount - GmatCommandParamCount] =

    {
     
     {
     "Parameter",

    
     };

     
     const Gmat::ParameterType

    
     Display::PARAMETER_TYPE[DisplayParamCount - GmatCommandParamCount] =

    
     {

    
     Gmat::OBJECT_TYPE, // "Parameter",

    
     };

     
     
     //------------------------------------------------------------------------------

    
     // Display()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Constructs the Display command (default constructor).

    
     */

    
     //------------------------------------------------------------------------------

    
     Display::Display() :

    
     GmatCommand("Display"),

    
     paramWrapper(NULL)

    
     {

    
     parameterCount = DisplayParamCount;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // ~Display()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Destroys the Display command (default constructor).

    
     */

    
     //------------------------------------------------------------------------------

    
     Display::~Display()

    
     {

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // Display(const Display& display)

    
     //------------------------------------------------------------------------------

    
     /**
    
    Makes a copy of the Display command (copy constructor).

    
     *
    
    @param display The original used to set parameters for this one.

    
     */

    
     //------------------------------------------------------------------------------

    
     Display::Display(const Display& display) :

    
     GmatCommand (display),

    
     paramName(display.paramName),

    
     paramWrapper(NULL)

    
     {

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // Display& operator=(const Display& display)

    
     //------------------------------------------------------------------------------

    
     /**
    
    Sets this Display to match another one (assignment operator).
    
    @param display The original used to set parameters for this one.

    
     *
    
    @return this instance.

    
     */

    
     //------------------------------------------------------------------------------

    
     Display& Display::operator=(const Display& display)

    
     {

    
     if (this != &display)

    
     {

    
     paramName = display.paramName;

    
     paramWrapper = NULL;

    }
    return
    
     } 
     return *this;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // bool Execute()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Executes the Display command
    
    @return true always.

    
     */

    
     //------------------------------------------------------------------------------

    
     bool Display::Execute()

    
     {

    
     Gmat::WrapperDataType wrapperType = paramWrapper->GetWrapperType();

    
     std::string result = "Unknown";

    
     Integer precision = 16;

    
     bool zeroFill = false;

     
     switch (wrapperType)

    
     {

    
     case Gmat::VARIABLE_WT:

    
     case Gmat::ARRAY_ELEMENT_WT:

    
     case Gmat::OBJECT_PROPERTY_WT:

    
     {

    
     Real rval = paramWrapper->EvaluateReal();

    
     result = GmatStringUtil::ToString(rval, precision, zeroFill);

    
     break;

    
     }

    
     case Gmat::PARAMETER_WT:

    
     {

    
     Gmat::ParameterType dataType = paramWrapper->GetDataType();

    
     switch (dataType)

    
     {

    
     case Gmat::REAL_TYPE:

    
     {

    
     Real rval = paramWrapper->EvaluateReal();

    
     result = GmatStringUtil::ToString(rval, precision, zeroFill);

    
     break;

    
     }

    
     case Gmat::RMATRIX_TYPE:

    
     {

    
     Rmatrix rmat = paramWrapper->EvaluateArray();

    
     result = rmat.ToString();

    
     break;

    
     }

    
     case Gmat::RVECTOR_TYPE:

    
     {

    
     Rvector rvec = paramWrapper->EvaluateRvector();

    
     result = rvec.ToString();

    
     break;

    
     }

    
     case Gmat::STRING_TYPE:

    
     {

    
     result = paramWrapper->EvaluateString();

    
     break;

    
     }

    
     default:

    
     throw CommandException

    
     ("Display cannot write \"" + paramName + "\" due to unimplemented "

    
     "Parameter data type");

    
     }

    
     break;

    
     }

    
     case Gmat::ARRAY_WT:

    
     {

    
     Rmatrix rmat = paramWrapper->EvaluateArray();

    
     result = rmat.ToString(precision, 1, false, "", false);

    
     break;

    
     }

    
     case Gmat::STRING_OBJECT_WT:

    
     {

    
     result = paramWrapper->EvaluateString();

    
     break;

    
     }

    
     default:

    
     break;

    }
    
     } 
     MessageInterface::ShowMessage("%s = \n%s\n\n", paramName.c_str(), result.c_str());

     
     BuildCommandSummary(true);

     
     return true;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // void InterpretAction()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Parses the command string and builds the corresponding command structures.

    
     *
    
    The Display command has the following syntax:

    
     *
    
    Display ParameterName

    
     */

    
     //------------------------------------------------------------------------------

    
     bool Display::InterpretAction()

    
     {

    
     StringArray chunks = InterpretPreface();

     
     if (chunks.size() < 2)

    
     throw CommandException("Missing information for MissionSave command.\n");

     
     paramName = chunks[1];

     
     return true;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // bool SetElementWrapper(ElementWrapper *toWrapper, const std::string &withName)

    
     //------------------------------------------------------------------------------

    
     /**
    
    Sets an element wrapper for a given object name

    
     */

    
     //------------------------------------------------------------------------------

    
     bool Display::SetElementWrapper(ElementWrapper *toWrapper,

    
     const std::string &withName)

    
     {

    
     if (toWrapper == NULL)

    
     return false;

     
     bool retval = false;

    
     ElementWrapper *oldWrapper = paramWrapper;

     
     if (paramName == withName)

    
     {

    
     paramWrapper = toWrapper;

    
     retval = true;

    }
    if
    
     } 
     if (oldWrapper)

    
     delete oldWrapper;

     
     return retval;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // const StringArray& GetWrapperObjectNameArray(bool completeSet = false)

    
     //------------------------------------------------------------------------------

    
     const StringArray& Display::GetWrapperObjectNameArray(bool completeSet)

    
     {

    
     wrapperObjectNames.clear();

    
     wrapperObjectNames.push_back(paramName);

    
     return wrapperObjectNames;

    }
    
     } 
     //------------------------------------------------------------------------------

    
     // void ClearWrappers()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Clears wrappers and set to NULL.

    
     */

    
     //------------------------------------------------------------------------------

    
     void Display::ClearWrappers()

    
     {

    
     ElementWrapper *wrapper = paramWrapper;

    
     paramWrapper = NULL;

     
     if (wrapper)

    
     delete wrapper;

    }
    
     } 
     //------------------------------------------------------------------------------

    
     // bool Initialize()

    
     //------------------------------------------------------------------------------

    
     /**
    
    Performs the initialization needed to run the Display command.

    
     *
    
    @return true if the Display is initialized, false if an error occurs.

    
     */

    
     //------------------------------------------------------------------------------

    
     bool Display::Initialize()

    {
    bool retval = true;
    if
    
     { 
     bool retval = true; 
     if (GmatCommand::Initialize() == false)

    
     retval = false;

     
     if (retval)

    
     {

    
     // Set wrapper reference

    
     if (SetWrapperReferences(*paramWrapper) == false)

    
     retval = false;

    }
    return retval;
    }
     
     } 
     return retval;
     } 
     
     //------------------------------------------------------------------------------

    
     // GmatBase* Clone(void) const

    
     //------------------------------------------------------------------------------

    
     /**
    
    This method returns a clone of the Display.

    
     *
    
    @return clone of the Display.

    
     */

    
     //------------------------------------------------------------------------------

    
     GmatBase* Display::Clone() const

    
     {

    
     return (new Display(*this));

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // bool RenameRefObject(const Gmat::ObjectType type,

    
     // const std::string &oldName, const std::string &newName)

    
     //------------------------------------------------------------------------------

    
     /**
    
    @see GmatBase

    
     */

    
     //------------------------------------------------------------------------------

    
     bool Display::RenameRefObject(const Gmat::ObjectType type,

    
     const std::string &oldName,

    
     const std::string &newName)

    
     {

    
     // Change Parameter name

    
     if (paramName.find(oldName) != oldName.npos)

    
     {

    
     paramName = GmatStringUtil::ReplaceName(paramName, oldName, newName);

    }
    
     } 
     // Go through wrapper

    
     std::string desc = paramWrapper->GetDescription();

    
     if (desc.find(oldName) != oldName.npos)

    
     {

    
     paramWrapper->RenameObject(oldName, newName);

    }
    
     } 
     // Go through generating string

    
     generatingString = GmatStringUtil::ReplaceName(generatingString, oldName, newName);

     
     return true;

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // std::string GetParameterText(const Integer id) const

    
     //------------------------------------------------------------------------------

    
     std::string Display::GetParameterText(const Integer id) const

    
     {

    
     if (id >= GmatCommandParamCount && id < DisplayParamCount)

    
     return PARAMETER_TEXT[id - GmatCommandParamCount];

    
     else

    
     return GmatCommand::GetParameterText(id);

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // Integer GetParameterID(const std::string &str) const

    
     //------------------------------------------------------------------------------

    
     Integer Display::GetParameterID(const std::string &str) const

    
     {

    
     for (int i=GmatCommandParamCount; i<DisplayParamCount; i++)

    
     {

    
     if (str == PARAMETER_TEXT[i - GmatCommandParamCount])

    
     return i;

    }
    return
    
     } 
     return GmatCommand::GetParameterID(str);

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // Gmat::ParameterType GetParameterType(const Integer id) const

    
     //------------------------------------------------------------------------------

    
     Gmat::ParameterType Display::GetParameterType(const Integer id) const

    
     {

    
     if (id >= GmatCommandParamCount && id < DisplayParamCount)

    
     return PARAMETER_TYPE[id - GmatCommandParamCount];

    
     else

    
     return GmatCommand::GetParameterType(id);

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // std::string GetParameterTypeString(const Integer id) const

    
     //------------------------------------------------------------------------------

    
     std::string Display::GetParameterTypeString(const Integer id) const

    
     {

    
     if (id >= GmatCommandParamCount && id < DisplayParamCount)

    
     return GmatBase::PARAM_TYPE_STRING[GetParameterType(id)];

    
     else

    
     return GmatCommand::GetParameterTypeString(id);

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // std::string GetStringParameter(const Integer id) const

    
     //------------------------------------------------------------------------------

    
     std::string Display::GetStringParameter(const Integer id) const

    
     {

    
     switch (id)

    
     {

    
     case PARAM_NAME:

    
     return paramName;

    
     default:

    
     return GmatCommand::GetStringParameter(id);

    
     }

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // std::string GetStringParameter(const std::string &label) const

    
     //------------------------------------------------------------------------------

    
     std::string Display::GetStringParameter(const std::string &label) const

    
     {

    
     return GetStringParameter(GetParameterID(label));

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // bool SetStringParameter(const Integer id, const std::string value)

    
     //------------------------------------------------------------------------------

    
     bool Display::SetStringParameter(const Integer id, const std::string &value)

    
     {

    
     switch (id)

    
     {

    
     case PARAM_NAME:

    
     paramName = value;

    
     return true;

    
     default:

    
     return GmatCommand::SetStringParameter(id, value);

    
     }

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // bool SetStringParameter(const std::string &label, const std::string &value)

    
     //------------------------------------------------------------------------------

    
     bool Display::SetStringParameter(const std::string &label, const std::string &value)

    
     {

    
     return SetStringParameter(GetParameterID(label), value);

    }
    
     } 
     
     //------------------------------------------------------------------------------

    
     // const std::string& GetGeneratingString(Gmat::WriteMode mode = Gmat::SCRIPTING,

    
     // const std::string &prefix = "",

    
     // const std::string &useName = "");

    
     //------------------------------------------------------------------------------

    
     const std::string& Display::GetGeneratingString(Gmat::WriteMode mode,

    
     const std::string &prefix,

    
     const std::string &useName)

    
     {

    
     // Build the local string

    
     generatingString = prefix + "Display ";

    
     generatingString += paramName;

     
     // Then call the base class method for comments

    
     return GmatCommand::GetGeneratingString(mode, prefix, useName);

    
     }