Merge pull request #87 from inverted-ai/add-doc-cpp

Add documentation for cpp

invertedai_cpp/invertedai/api.h

@@ -12,12 +12,48 @@
 
 namespace invertedai {
 
+/**
+ * Wrap the REST API "location_info".
+ * Provides static information about a given location.
+ *
+ * @param location_info_request the location_info request to send to the API
+ * @param session the shared session connected with the host
+ * @return the location_info response receive from the API
+ * @see invertedai::initialize
+ * @see invertedai::drive
+ */
 LocationInfoResponse location_info(LocationInfoRequest &location_info_request,
                                    Session *session);
 
+/**
+ * Wrap the REST API "initialize".
+ * Initializes a simulation in a given location. Either agent_count or both
+ * agent_attributes and states_history need to be provided. In the latter case,
+ * the simulation is initialized with the specific history, and if traffic
+ * lights are present then traffic_light_state_history should also be provided.
+ * If only agent_count is specified, a new initial state is generated with the
+ * requested total number of agents. Every simulation needs to start with a call
+ * to this function in order to obtain correct recurrent states for drive().
+ *
+ * @param initialize_request the initialize request to send to the API
+ * @param session the shared session connected with the host
+ * @return the initialize response receive from the API
+ * @see invertedai::location_info
+ * @see invertedai::drive
+ */
 InitializeResponse initialize(InitializeRequest &initialize_request,
                               Session *session);
 
+/**
+ * Wrap the REST API "drive".
+ * Drive the agents based on given situations.
+ *
+ * @param drive_request the initialize request to send to the API
+ * @param session the shared session connected with the host
+ * @return the initialize response receive from the API
+ * @see invertedai::location_info
+ * @see invertedai::initialize
+*/
 DriveResponse drive(DriveRequest &drive_request, Session *session);
 
 } // namespace invertedai

invertedai_cpp/invertedai/data_utils.h

@@ -10,32 +10,112 @@ const std::map<std::string, int> kControlType = {
     {"traffic-light", 0},       {"yield", 1},       {"stop-sign", 2},
     {"traffic-light-actor", 3}, {"yield-actor", 4}, {"stop-sign-actor", 5}};
 
+/**
+ * 2D coordinates of a point in a given location. Each location comes with a
+ * canonical coordinate system, where the distance units are meters.
+ */
 struct Point2d {
   double x, y;
 };
 
+/**
+ * The current or predicted state of a given agent at a given point.
+ */
 struct AgentState {
-  double x, y, orientation, speed;
+  /**
+   * The center point of the agent’s bounding box.
+   */
+  double x, y;
+  /**
+   * The direction the agent is facing, in radians with 0 pointing along x and
+   * pi/2 pointing along y.
+   */
+  double orientation;
+  /**
+   * In meters per second, negative if the agent is reversing.
+   */
+  double speed;
 };
 
+/**
+ * Static attributes of the agent, which don’t change over the course of a
+ * simulation. We assume every agent is a rectangle obeying a kinematic bicycle
+ * model.
+ */
 struct AgentAttributes {
-  double length, width, rear_axis_offset;
+  /**
+   * Longitudinal, lateral extent of the agent in meters.
+   */
+  double length, width;
+  /**
+   * Distance from the agent’s center to its rear axis in meters. Determines
+   * motion constraints.
+   */
+  double rear_axis_offset;
 };
 
+/**
+ * Dynamic state of a traffic light.
+ */
 struct TrafficLightState {
-  std::string id, value;
+  std::string id;
+  std::string value;
 };
 
+/**
+ * Infractions committed by a given agent, as returned from invertedai::drive().
+ */
 struct InfractionIndicator {
-  bool collisions, offroad, wrong_way;
+  /**
+   * True if the agent’s bounding box overlaps with another agent’s bounding
+   * box.
+   */
+  bool collisions;
+  /**
+   * True if the agent is outside the designated driveable area specified by the
+   * map.
+   */
+  bool offroad;
+  /**
+   * True if the cross product of the agent’s and its lanelet’s directions is
+   * negative.
+   */
+  bool wrong_way;
 };
 
+/**
+ * Specifies a traffic light placement. We represent traffic lights as
+ * rectangular bounding boxes of the associated stop lines, with orientation
+ * matching the direction of traffic going through it.
+ */
 struct StaticMapActor {
-  int actor_id, agent_type;
-  double x, y, orientation, length, width;
+  /**
+   * ID as used in invertedai::initialize() and invertedai::drive().
+   */
+  int actor_id;
+  /**
+   * Not currently used, there may be more traffic signals in the future.
+   */
+  int agent_type;
+  /**
+   * The position of the stop line.
+   */
+  double x, y;
+  /**
+   * Natural direction of traffic going through the stop line, in radians like
+   * in AgentState.
+   */
+  double orientation;
+  /**
+   * Size of the stop line, in meters, along its orientation.
+   */
+  double length, width;
   int dependant;
 };
 
+/**
+ * Read file from the path, return the content as a string.
+ */
 std::string read_file(const char *path);
 
 } // namespace invertedai

invertedai_cpp/invertedai/drive_request.h

@@ -30,29 +30,104 @@ class DriveRequest {
 
 public:
   DriveRequest(const std::string &body_str);
+  /**
+   * Serialize all the fields into a string.
+   */
   std::string body_str();
+
+  /**
+   * Update the drive request with the information(agent_states,
+   * agent_attributes, recurrent_states) in the initialize response.
+   */
   void update(const InitializeResponse &init_res);
+  /**
+   * Update the drive request with the information(agent_states,
+   * recurrent_states) in the drive response.
+   */
   void update(const DriveResponse &drive_res);
 
+  // getters
+  /**
+   * Get location string in IAI format.
+   */
   std::string location() const;
+  /**
+   * Get current states of all agents.
+   * x: [float], y: [float] corrdinate in meters;
+   * orientation: [float] in radians with 0 pointing along x
+   * and pi/2 pointing along y;
+   * speed: [float] in m/s.
+   */
   std::vector<AgentState> agent_states() const;
+  /**
+   * Get static attributes for all agents.
+   */
   std::vector<AgentAttributes> agent_attributes() const;
+  /**
+   * Get the states of traffic lights.
+   */
   std::vector<TrafficLightState> traffic_lights_states() const;
+  /**
+   * Get the recurrent states for all agents.
+   */
   std::vector<std::vector<double>> recurrent_states() const;
+  /**
+   * Check whether to return an image visualizing the simulation state.
+   */
   bool get_birdview() const;
+  /**
+   * Check whether to check predicted agent states for infractions.
+   */
   bool get_infractions() const;
+  /**
+   * Get random_seed.
+   */
   int random_seed() const;
 
+  // setters
+  /**
+   * Set location string in IAI format.
+   */
   void set_location(const std::string &location);
+  /**
+   * Set current states of all agents. The state must include x:
+   * [float], y: [float] corrdinate in meters orientation: [float] in radians
+   * with 0 pointing along x and pi/2 pointing along y and speed: [float] in
+   * m/s.
+   */
   void set_agent_states(const std::vector<AgentState> &agent_states);
+  /**
+   * Set static attributes for all agents.
+   */
   void
   set_agent_attributes(const std::vector<AgentAttributes> &agent_attributes);
+  /**
+   * Set the states of traffic lights. If the location contains traffic lights
+   * within the supported area, their current state should be provided here. Any
+   * traffic light for which no state is provided will be ignored by the agents.
+   */
   void set_traffic_lights_states(
       const std::vector<TrafficLightState> &traffic_lights_states);
+  /**
+   * Set the recurrent states for all agents, obtained from the
+   * previous call to drive() or initialize().
+   */
   void set_recurrent_states(
       const std::vector<std::vector<double>> &recurrent_states);
+  /**
+   * Set whether to return an image visualizing the simulation state.
+   * This is very slow and should only be used for debugging.
+   */
   void set_get_birdview(bool get_birdview);
+  /**
+   * Set whether to check predicted agent states for infractions.
+   * This introduces some overhead, but it should be relatively small.
+   */
   void set_get_infractions(bool get_infractions);
+  /**
+   * Set random_seed, which controls the stochastic aspects of agent behavior
+   * for reproducibility.
+   */
   void set_random_seed(int random_seed);
 };
 

invertedai_cpp/invertedai/drive_response.h

@@ -24,20 +24,62 @@ class DriveResponse {
 
 public:
   DriveResponse(const std::string &body_str);
+  /**
+   * Serialize all the fields into a string.
+   */
   std::string body_str();
 
+  // getters
+  /**
+   * Get current states of all agents.
+   * x: [float], y: [float] corrdinate in meters;
+   * orientation: [float] in radians with 0 pointing along x
+   * and pi/2 pointing along y;
+   * speed: [float] in m/s.
+   */
   std::vector<AgentState> agent_states() const;
+  /**
+   * For each agent, get whether the predicted state is inside supported area.
+   */
   std::vector<bool> is_inside_supported_area() const;
+  /**
+   * Get the recurrent states for all agents.
+   */
   std::vector<std::vector<double>> recurrent_states() const;
+  /**
+   * If get_birdview was set, this contains the resulting image.
+   */
   std::vector<unsigned char> birdview() const;
+  /**
+   * If get_infractions was set, they are returned here.
+   */
   std::vector<InfractionIndicator> infraction_indicators() const;
 
+  // setters
+  /**
+   * Set current states of all agents. The state must include x:
+   * [float], y: [float] corrdinate in meters orientation: [float] in radians
+   * with 0 pointing along x and pi/2 pointing along y and speed: [float] in
+   * m/s.
+   */
   void set_agent_states(const std::vector<AgentState> &agent_states);
+  /**
+   * For each agent, set whether the predicted state is inside supported area.
+   */
   void set_is_inside_supported_area(
       const std::vector<bool> &is_inside_supported_area);
+  /**
+   * Set the recurrent states for all agents.
+   */
   void set_recurrent_states(
       const std::vector<std::vector<double>> &recurrent_states);
+  /**
+   * Set birdview.
+   */
   void set_birdview(const std::vector<unsigned char> &birdview);
+  /**
+   * Set infraction_indicators.
+   */
   void set_infraction_indicators(
       const std::vector<InfractionIndicator> &infraction_indicators);
 };