Commits

Ian Chen  committed 3f43227

Documentation part 1

  • Participants
  • Parent commits 52633ed
  • Branches ian-building

Comments (0)

Files changed (8)

File gazebo/gui/model_editor/BuildingEditorPalette.hh

       Q_OBJECT
 
       /// \brief Constructor
+      /// \param[in] _parent Parent QWidget.
       public: BuildingEditorPalette(QWidget *_parent = 0);
 
       /// \brief Destructor
       public: ~BuildingEditorPalette();
 
-      /// \brief On draw wall callback.
+      /// \brief Qt callback when the draw wall mode is chosen.
       private slots: void OnDrawWall();
 
-      /// \brief On import image callback.
-      private slots: void OnImportImage();
+      //private slots: void OnImportImage();
 
-      /// \brief On add window callback.
+      /// \brief Qt callback when the draw window button is pressed.
       private slots: void OnAddWindow();
 
-      /// \brief On add door callback.
+      /// \brief Qt callback when the draw door butotn is pressed.
       private slots: void OnAddDoor();
 
-      /// \brief On add stairs callback.
+      /// \brief Qt callback when the draw stairs button is pressed.
       private slots: void OnAddStairs();
 
-      /// \brief On discard callback.
+      /// \brief Qt callback when the discard button pressed.
       private slots: void OnDiscard();
 
-      /// \brief On save callback.
+      /// \brief Qt callback when the save button is pressed.
       private slots: void OnSave();
 
-      /// \brief On done callback.
+      /// \brief Qt callback when the done button is pressed.
       private slots: void OnDone();
 
-      /// \brief On save model event.
+      /// \brief Callback when user has provided information on where
+      /// to save the model to.
+      /// \param[in] _saveName Name of model.
+      /// \param[in] _saveLocation Location to save the model to.
       private: void OnSaveModel(std::string _saveName,
           std::string _saveLocation);
 
-      /// \brief On discard model event.
+      /// \brief Callback when user confirms to discard model.
       private: void OnDiscardModel();
 
+      /// \brief A label that displays the name of the model.
       private: QLabel *modelNameLabel;
 
+      /// \brief Save button.
       private: QPushButton *saveButton;
 
+      /// \brief Name of model.
       private: std::string modelName;
 
+      /// \brief Save location.
       private: std::string saveLocation;
 
+      /// \brief A list of gui editor events.
       private: std::vector<event::ConnectionPtr> connections;
     };
   }

File gazebo/gui/model_editor/BuildingEditorWidget.hh

 
     class BuildingEditorWidget : public QWidget
     {
+      /// \brief Types of models supported in building editor
       public: enum modelTypes {None, Wall, Window, Door, Stairs};
 
+      /// \brief Constructor
+      /// \param[in] _parent Parent QWidget.
       public: BuildingEditorWidget(QWidget *_parent = 0);
 
+      /// \brief Destructor
       public: ~BuildingEditorWidget();
 
+      /// \brief Qt event received when the widget is being resized
+      /// \param[in] _event Resize event.
+      private: void resizeEvent(QResizeEvent *_event);
+
+      /// \brief Custom rotation cursor
       public: static QCursor rotateCursor;
 
-      private: void resizeEvent(QResizeEvent *_event);
-
+      /// \brief A widget to display and change building levels.
       private: LevelWidget *levelWidget;
 
+      /// \brief A widget to display the scale of the 2D editor view.
       private: ScaleWidget *scaleWidget;
     };
   }

File gazebo/gui/model_editor/BuildingItem.hh

   {
     class BuildingItem
     {
+        /// \brief Constructor
         public: BuildingItem();
 
+        /// \brief Destructor
         public: ~BuildingItem();
 
+        /// \brief Get the level in which this building item is located
         public: int GetLevel() const;
 
+        /// \brief Set the level of this building item
+        /// \param[in] _level level number
         public: void SetLevel(int _level);
 
+        /// \brief Get the base height of this level relative to ground plane
         public: double GetLevelBaseHeight() const;
 
+        /// \brief Set the base height of this level relative to gound plan
+        /// \param[in] _height base height
         public: void SetLevelBaseHeight(double _height);
 
+        /// \brief Level of this building item
         protected: int level;
 
+        /// \brief Base height of the level
         protected: double levelBaseHeight;
     };
   }

File gazebo/gui/model_editor/BuildingMaker.cc

 /////////////////////////////////////////////////
 void BuildingMaker::SaveToSDF(const std::string &_savePath)
 {
-  this->savePath = _savePath;
+  this->saveLocation = _savePath;
   std::ofstream savefile;
-  std::string saveFilePath = this->savePath + "/" + this->modelName + ".sdf";
+  std::string saveFilePath = this->saveLocation + "/" + this->modelName
+      + ".sdf";
   savefile.open(saveFilePath.c_str());
   savefile << this->modelSDF->ToString();
   savefile.close();

File gazebo/gui/model_editor/BuildingMaker.hh

 
     class BuildingMaker : public EntityMaker
     {
+      /// \brief Constructor
       public: BuildingMaker();
 
+      /// \brief Destructor
       public: virtual ~BuildingMaker();
 
+      /// \brief Set the name of this model.
+      /// \param[in] _topicName Name of the model to set to.
       public: void SetModelName(const std::string &_modelName);
 
+      /// \brief Finish the model and create the entity on the gzserver.
       public: void FinishModel();
 
+      /// \brief Add a building part to the model.
+      /// \param[in] _type Type of the building part.
+      /// \param[in] _size Size of the building part.
+      /// \param[in] _pos Position of the building part in world coordinates.
+      /// \param[in] _angle Yaw rotation of the building part in radians.
+      /// \return The name of the 3D building part that was added.
       public: std::string AddPart(const std::string &_type,
           const QVector3D &_size, const QVector3D &_pos, double _angle);
 
+      /// \brief Add a wall to the model.
+      /// \param[in] _size Size of the wall.
+      /// \param[in] _pos Position of the wall in world coordinates.
+      /// \param[in] _angle Yaw rotation of the wall in radians.
+      /// \return The name of the 3D wall that was added.
       public: std::string AddWall(const QVector3D &_size, const QVector3D &_pos,
           double _angle);
 
+      /// \brief Add a window to the model.
+      /// \param[in] _size Size of the window.
+      /// \param[in] _pos Position of the window in world coordinates.
+      /// \param[in] _angle Yaw rotation of the window in radians.
+      /// \return The name of the 3D window that was added
       public: std::string AddWindow(const QVector3D &_size,
           const QVector3D &_pos, double _angle);
 
+      /// \brief Add a door to the model.
+      /// \param[in] _size Size of the window.
+      /// \param[in] _pos Position of the door in world coordinates.
+      /// \param[in] _angle Yaw rotation of the door in radians.
       public: std::string AddDoor(const QVector3D &_size, const QVector3D &_pos,
           double _angle);
 
+      /// \brief Add a staircase to the model.
+      /// \param[in] _size Size of the staircase.
+      /// \param[in] _pos Position of the staircase in world coordinates.
+      /// \param[in] _angle Yaw rotation of the staircase in radians.
+      /// \param[in] _steps Number of steps in the staircase.
+      /// \return The name of the 3D staircase that was added
       public: std::string AddStairs(const QVector3D &_size,
           const QVector3D &_pos, double _angle, int _steps);
 
+      /// \brief Add a floor to the model.
+      /// \param[in] _size Size of the floor.
+      /// \param[in] _pos Position of the floor in world coordinates.
+      /// \param[in] _angle Yaw rotation of the floor in radians.
+      /// \return The name of the 3D floor that was added.
       public: std::string AddFloor(const QVector3D &_size,
           const QVector3D &_pos, double _angle);
 
+      /// \brief Remove a building part from the model.
+      /// \param[in] _partName Name of the building part to remove
       public: void RemovePart(const std::string &_partName);
 
+      /// \brief Remove a wall from the model.
+      /// \param[in] _partName Name of the wall to remove
       public: void RemoveWall(const std::string &_wallName);
 
+      /// \brief Connect the 2D editor item Qt signals to the 3D visuals
+      /// \param[in] _partName Name of the 3D building part to connect to
+      /// \param[in] _item 2D Editor item which emits Qt signals
       public: void ConnectItem(const std::string &_partName,
           const EditorItem *_item);
 
+      /// \brief Attach a building part to another, this is currently used for
+      /// making holes in walls and floors.
+      /// \param[in] _child Child Item to be attached.
+      /// \param[in] _child Parent item to attach to.
       public: void AttachObject(const std::string &_child,
           const std::string &_parent);
 
+      /// \brief Detach a building part from another.
+      /// \param[in] _child Child Item to be detached.
+      /// \param[in] _child Parent item to detach from.
       public: void DetachObject(const std::string &_child,
           const std::string &_parent);
 
+      /// \brief Helper method to convert size from 2D editor coordinate system
+      /// to Gazebo coordinate system
+      /// \param[in] _size Qt vector data structure.
+      /// \return Size in metric units.
       public: static math::Vector3 ConvertSize(const QVector3D &_size);
 
+      /// \brief Helper method to convert size from 2D editor coordinate system
+      /// to Gazebo coordinate system
+      /// \param[in] _width width in pixels.
+      /// \param[in] _width depth in pixels.
+      /// \param[in] _height height in pixels.
+      /// \return Size in metric units.
       public: static math::Vector3 ConvertSize(double _width, double _depth,
           double _height);
 
+      /// \brief Helper method to convert pose from 2D editor coordinate system
+      /// to Gazebo coordinate system
+      /// \param[in] _pos Position in pixels.
+      /// \param[in] _pos Rotation in pixels.
+      /// \return Pose in metric units.
       public: static math::Pose ConvertPose(const QVector3D &_pos,
           const QVector3D &_rot);
 
+      /// \brief Helper method to convert pose from 2D editor coordinate system
+      /// to Gazebo coordinate system
+      /// \param[in] _x X position in pixels.
+      /// \param[in] _y Y position in pixels.
+      /// \param[in] _y Z position in pixels.
+      /// \param[in] _roll Roll rotation in degrees.
+      /// \param[in] _pitch Pitch rotation in degrees.
+      /// \param[in] _yaw Yaw rotation in degrees.
+      /// \return Pose in metric units.
       public: static math::Pose ConvertPose(double _x, double _y, double _z,
           double _roll, double _pitch, double _yaw);
 
+      /// \param[in] _value Convert value from pixels to metric units
+      /// \param[in] _value Value in pixels.
+      /// \return Value in metric units.
       public: static double Convert(double _value);
 
+      /// \brief Convert angle from 2D editor unit (degrees) to radians
+      /// \param[in] _angle Angle in degrees.
+      /// \return Angle in radians.
       public: static double ConvertAngle(double _angle);
 
+      /// \brief Save model to SDF format.
+      /// \param[in] _savePath Path to save the SDF to.
       public: void SaveToSDF(const std::string &_savePath);
 
-      /// \brief
+      /// \brief Reset the building maker and the SDF
       public: void Reset();
 
-      /// \brief
+      // Documentation inherited
       public: virtual void Start(const rendering::UserCameraPtr _camera);
 
-      /// \brief
+      // Documentation inherited
       public: virtual void Stop();
 
+      /// \brief Generate the SDF from visuals
       public: void GenerateSDF();
 
-      /// \brief Checks if entity is active
+      // Documentation inherited
       public: virtual bool IsActive() const;
 
+      // Documentation inherited
       private: virtual void CreateTheEntity();
 
       /// \brief Internal init function.
       private: bool Init();
 
+      /// \brief Create an empty model.
       private: std::string CreateModel();
 
+      /// \brief Generate SDF with CSG support.
       private: void GenerateSDFWithCSG();
 
+      /// \brief Get a template SDF string of a simple model.
       private: std::string GetTemplateSDFString();
 
+      /// \brief Internal helper function for QPointF comparison
       private: static bool PointCompareY(const QPointF &_a, const QPointF &_b);
 
+      /// \brief Internal helper function for QRectF comparison
       private: static bool RectCompareX(const QRectF &_a, const QRectF &_b);
 
+      /// \brief Internal helper function for QRectF comparison
       private: static bool RectCompareY(const QRectF &_a, const QRectF &_b);
 
+      /// \brief Subdivide A rectangular surface with holes into multiple
+      /// rectangles
+      /// \param[in] _surface Parent rectangular surface.
+      /// \param[in] _holes A list of rectangular holes on the surface.
+      /// \param[in] _subdivisions The resulting smaller rectangles representing
+      /// the surface with holes.
       private: void SubdivideRectSurface(const QRectF &_surface,
         const std::vector<QRectF> &_holes, std::vector<QRectF> &_subdivisions);
 
+      /// \brief Callback for the save event.
       private: void OnSave();
 
+      /// \brief Callback for the discard event.
       private: void OnDiscard();
 
+      /// \brief Callback for the done event.
       private: void OnDone();
 
+      /// \brief Callback for the exit.
       private: void OnExit();
 
+      /// \brief Conversion the used by the helper Convert functions.
       public: static double conversionScale;
 
+      /// \brief A map of the building part names to the 3D model manip objects.
       private: std::map<std::string, ModelManip *> allItems;
 
+      /// \brief The model in SDF format.
       private: sdf::SDFPtr modelSDF;
 
+      /// \brief A template SDF of a simple model.
       private: sdf::SDFPtr modelTemplateSDF;
 
+      /// \brief Name of the model.
       private: std::string modelName;
 
-      private: std::string savePath;
-
+      /// \brief The root visual of the model
       private: rendering::VisualPtr modelVisual;
 
+      /// \brief The pose of the model
       private: math::Pose modelPose;
 
+      /// \brief Counter for the number of walls in the model.
       private: int wallCounter;
 
+      /// \brief Counter for the number of windows in the model.
       private: int windowCounter;
 
+      /// \brief Counter for the number of doors in the model.
       private: int doorCounter;
 
+      /// \brief Counter for the number of stairs in the model.
       private: int stairsCounter;
 
+      /// \brief Counter for the number of floors in the model.
       private: int floorCounter;
 
+      /// \brief Indicate whether the model has been saved before or not.
       private: bool saved;
 
+      /// \brief Path to where the model is saved.
       private: std::string saveLocation;
 
+      /// \brief A list of gui editor events.
       private: std::vector<event::ConnectionPtr> connections;
     };
   }

File gazebo/gui/model_editor/DoorItem.hh

 
     class DoorItem : public RectItem, public BuildingItem
     {
-        Q_OBJECT
+      Q_OBJECT
 
-        public: DoorItem();
+      /// \brief Constructor
+      public: DoorItem();
 
-        public: ~DoorItem();
+      /// \brief Destructor
+      public: ~DoorItem();
 
-        public: virtual QVector3D GetSize() const;
+      // Documentation inherited
+      public: virtual QVector3D GetSize() const;
 
-        public: virtual QVector3D GetScenePosition() const;
+      // Documentation inherited
+      public: virtual QVector3D GetScenePosition() const;
 
-        public: virtual double GetSceneRotation() const;
+      // Documentation inherited
+      public: virtual double GetSceneRotation() const;
 
-        private: virtual void paint(QPainter *_painter,
-            const QStyleOptionGraphicsItem *_option, QWidget *_widget);
+      // Documentation inherited
+      private: virtual void paint(QPainter *_painter,
+          const QStyleOptionGraphicsItem *_option, QWidget *_widget);
 
-        private: void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *_event);
+      // Documentation inherited
+      private: void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *_event);
 
-        private slots: void OnApply();
+      /// \brief Qt callback when the changes are to be applied
+      private slots: void OnApply();
 
-        private slots: void OnOpenInspector();
+      /// \brief Qt callback to open the door inspector
+      private slots: void OnOpenInspector();
 
-        private slots: void OnDeleteItem();
+      /// \brief Qt callback to delete this door item
+      private slots: void OnDeleteItem();
 
-        private: void DoorChanged();
+      /// \brief Emit door changed signals
+      private: void DoorChanged();
 
-        private: void SizeChanged();
+      /// \brief Emit size changed signals
+      private: void SizeChanged();
 
-        private: double doorDepth;
+      /// \brief Door depth in pixels
+      private: double doorDepth;
 
-        private: double doorHeight;
+      /// \brief Door height in pixels
+      private: double doorHeight;
 
-        private: double doorWidth;
+      /// \brief Door width in pixels
+      private: double doorWidth;
 
-        private: double doorElevation;
+      /// \brief Door elevation in pixels
+      private: double doorElevation;
 
-        private: QPointF doorPos;
+      /// \brief Door scene position in pixels
+      private: QPointF doorPos;
 
-        private: double scale;
+      /// \brief Scale for converting to metric units
+      private: double scale;
 
-        private: WindowDoorInspectorDialog *inspector;
+      /// \brief Door inspector
+      private: WindowDoorInspectorDialog *inspector;
     };
   }
 }

File gazebo/gui/model_editor/EditorEvents.hh

     {
       class Events
       {
-        //////////////////////////////////////////////////////////////////////
         /// \brief Connect a boost::slot the the create editor item signal
         /// \param[in] _subscriber the subscriber to this event
         /// \return a connection
         /// \brief An editor item is to be created
         public: static event::EventT<void (std::string)> createEditorItem;
 
-        /// \brief A model is to be saved with a name and location
+        /// \brief A model has been saved with a name and a location
         public: static event::EventT<void (std::string, std::string)>
             saveModel;
 
-        /// \brief A model is to be created
+        /// \brief A model has been created
         public: static event::EventT<void ()> finishModel;
 
-        /// \brief A model is to be created
+        /// \brief A model has been discarded
         public: static event::EventT<void ()> discardModel;
 
         /// \brief The current level has been changed

File gazebo/gui/model_editor/EditorItem.hh

     {
       Q_OBJECT
 
+      /// \brief Constructor
       public: EditorItem();
 
+      /// \brief Destructor
       public: ~EditorItem();
 
+      /// \brief Get the size of item in pixels.
+      /// \return The item size in pixels.
       public: virtual QVector3D GetSize() const;
 
+      /// \brief Get the scene position of item in pixels.
+      /// \return The scene position in pixels.
       public: virtual QVector3D GetScenePosition() const;
 
+      /// \brief Get the scene rotation of item in degrees.
+      /// \return The scene rotation in degrees.
       public: virtual double GetSceneRotation() const;
 
+      /// \brief Get the type of this editor item.
+      /// \return The type of the item.
       public: virtual std::string GetType() const;
 
+      /// \brief Get the name of this editor item.
+      /// \return The name of the item.
       public: virtual std::string GetName() const;
 
+      /// \brief Set the name of this editor item.
+      /// \param[in] _name Name to set the editor item to.
       public: virtual void SetName(const std::string &_name);
 
+      /// \brief Qt signal to emit when the editor item size has changed.
+      /// \param[in] _width Width of item in pixels.
+      /// \param[in] _depth Depth of item in pixels.
+      /// \param[in] _height Height of item in pixels.
       Q_SIGNALS: void sizeChanged(double _width, double _depth,
           double _height);
 
+      /// \brief Qt signal to emit when the editor item pose has changed.
+      /// \param[in] _x X position of item in pixels.
+      /// \param[in] _y Y position of item in pixels.
+      /// \param[in] _z Z position of item in pixels.
+      /// \param[in] _roll Roll rotation of item in degrees.
+      /// \param[in] _pitch Pitch rotation of item in degrees.
+      /// \param[in] _yaw Yaw rotation of item in degrees.
       Q_SIGNALS: void poseChanged(double _x, double _y, double _z,
           double _roll, double _pitch, double _yaw);
 
+      /// \brief Qt signal to emit when the editor item pose origin has changed.
+      /// \param[in] _x X position of item in pixels.
+      /// \param[in] _y Y position of item in pixels.
+      /// \param[in] _z Z position of item in pixels.
+      /// \param[in] _roll Roll rotation of item in degrees.
+      /// \param[in] _pitch Pitch rotation of item in degrees.
+      /// \param[in] _yaw Yaw rotation of item in degrees.
       Q_SIGNALS: void poseOriginTransformed(double _x, double _y, double _z,
           double _roll, double _pitch, double _yaw);
 
+      /// \brief Qt signal to emit when the editor item position has changed.
+      /// \param[in] _x X position of item in pixels.
+      /// \param[in] _y Y position of item in pixels.
+      /// \param[in] _z Z position of item in pixels.
       Q_SIGNALS: void positionChanged(double _x, double _y, double _z);
 
+      /// \brief Qt signal to emit when the editor item rotation has changed.
+      /// \param[in] _roll Roll rotation of item in degrees.
+      /// \param[in] _pitch Pitch rotation of item in degrees.
+      /// \param[in] _yaw Yaw rotation of item in degrees.
       Q_SIGNALS: void rotationChanged(double _roll, double _pitch, double _yaw);
 
+      /// \brief Qt signal to emit when the editor item width has changed.
+      /// \param[in] _width Width of item in pixels.
       Q_SIGNALS: void widthChanged(double _width);
 
+      /// \brief Qt signal to emit when the editor item depth has changed.
+      /// \param[in] _depth Depth of item in pixels.
       Q_SIGNALS: void depthChanged(double _depth);
 
+      /// \brief Qt signal to emit when the editor item height has changed.
+      /// \param[in] _height Height of item in pixels.
       Q_SIGNALS: void heightChanged(double _height);
 
+      /// \brief Qt signal to emit when the editor item X position has changed.
+      /// \param[in] _x X position of item in pixels.
       Q_SIGNALS: void posXChanged(double _posX);
 
+      /// \brief Qt signal to emit when the editor item Y position has changed.
+      /// \param[in] _y Y position of item in pixels.
       Q_SIGNALS: void posYChanged(double _posY);
 
-      Q_SIGNALS: void posZChanged(double _posX);
+      /// \brief Qt signal to emit when the editor item Z position has changed.
+      /// \param[in] _z Z position of item in pixels.
+      Q_SIGNALS: void posZChanged(double _posZ);
 
+      /// \brief Qt signal to emit when the editor item yaw rotation has
+      /// changed.
+      /// \param[in] _yaw Yaw rotation of item in degrees.
       Q_SIGNALS: void yawChanged(double _yaw);
 
-      Q_SIGNALS: void originChanged(double _xRatio, double _yRatio,
-          double _zRatio);
-
+      /// \brief Qt signal to emit when the editor item is being deleted
       Q_SIGNALS: void itemDeleted();
 
+      /// \brief Type of editor item
       protected: std::string editorType;
 
+      /// \brief Name of editor item
       protected: std::string name;
     };
   }