Skip to content

Adding doxygen-compliant documentation. #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mmmarinho merged 1 commit into from
Sep 4, 2026
Merged

Adding doxygen-compliant documentation. #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 122 additions & 102 deletions src/DQ_py.cpp
View file
Open in desktop

Large diffs are not rendered by default.

69 changes: 40 additions & 29 deletions src/dqrobotics_module.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ This file is part of DQ Robotics.

#include "dqrobotics_module.h"

/**
* @brief Defines the `_dqrobotics` Python extension module and registers all
* of its classes, functions, enumerations, and submodules.
*/
PYBIND11_MODULE(_dqrobotics, m) {

//DQ Class
Expand All @@ -31,7 +35,7 @@ PYBIND11_MODULE(_dqrobotics, m) {
* Utils
* **************************************************/
//dqrobotics/utils/
py::module utils_py = m.def_submodule("_utils","A submodule of dqrobotics");
py::module utils_py = m.def_submodule("_utils","Linear-algebra, geometric, and mathematical utilities used throughout dqrobotics.");

//DQ_LinearAlgebra
init_DQ_LinearAlgebra_py(utils_py);
Expand All @@ -45,7 +49,7 @@ PYBIND11_MODULE(_dqrobotics, m) {
/*****************************************************
* Robot Modeling <dqrobotics/robot_modeling/...>
* **************************************************/
py::module robot_modeling = m.def_submodule("_robot_modeling", "The robot_modeling submodule of dqrobotics");
py::module robot_modeling = m.def_submodule("_robot_modeling", "Kinematic models of serial, mobile, cooperative dual-arm, and whole-body robots.");

//DQ_Kinematics
init_DQ_Kinematics_py(robot_modeling);
Expand Down Expand Up @@ -83,54 +87,61 @@ PYBIND11_MODULE(_dqrobotics, m) {
/*****************************************************
* Robots Kinematic Models
* **************************************************/
py::module robots_py = m.def_submodule("_robots", "A submodule of dqrobotics");
py::module robots_py = m.def_submodule("_robots", "Ready-to-use kinematic models of well-known commercial robot manipulators.");

//#include <dqrobotics/robots/Ax18ManipulatorRobot.h>
py::class_<Ax18ManipulatorRobot> ax18manipulatorrobot_py(robots_py, "Ax18ManipulatorRobot");
ax18manipulatorrobot_py.def_static("kinematics",&Ax18ManipulatorRobot::kinematics,"Returns the kinematics of the Ax18ManipulatorRobot");
py::class_<Ax18ManipulatorRobot> ax18manipulatorrobot_py(robots_py, "Ax18ManipulatorRobot",
"Provides the kinematic model of the AX-18 manipulator arm.");
ax18manipulatorrobot_py.def_static("kinematics",&Ax18ManipulatorRobot::kinematics,"Returns the kinematic model of the AX-18 manipulator arm.");

//#include <dqrobotics/robots/BarrettWamArmRobot.h>
py::class_<BarrettWamArmRobot> barrettwamarmrobot_py(robots_py, "BarrettWamArmRobot");
barrettwamarmrobot_py.def_static("kinematics",&BarrettWamArmRobot::kinematics,"Returns the kinematics of the BarrettWamArmRobot");
py::class_<BarrettWamArmRobot> barrettwamarmrobot_py(robots_py, "BarrettWamArmRobot",
"Provides the kinematic model of the Barrett WAM arm robot manipulator.");
barrettwamarmrobot_py.def_static("kinematics",&BarrettWamArmRobot::kinematics,"Returns the kinematic model of the Barrett WAM arm robot manipulator.");

//#include <dqrobotics/robots/ComauSmartSixRobot.h>
py::class_<ComauSmartSixRobot> comausmartsixrobot_py(robots_py, "ComauSmartSixRobot");
comausmartsixrobot_py.def_static("kinematics",&ComauSmartSixRobot::kinematics,"Returns the kinematics of the ComauSmartSixRobot");
py::class_<ComauSmartSixRobot> comausmartsixrobot_py(robots_py, "ComauSmartSixRobot",
"Provides the kinematic model of the COMAU SmartSiX robot manipulator.");
comausmartsixrobot_py.def_static("kinematics",&ComauSmartSixRobot::kinematics,"Returns the kinematic model of the COMAU SmartSiX robot manipulator.");

//#include <dqrobotics/robots/KukaLw4Robot.h>
py::class_<KukaLw4Robot> kukalw4robot_py(robots_py, "KukaLw4Robot");
kukalw4robot_py.def_static("kinematics",&KukaLw4Robot::kinematics,"Returns the kinematics of the KukaLw4Robot");
py::class_<KukaLw4Robot> kukalw4robot_py(robots_py, "KukaLw4Robot",
"Provides the kinematic model of the KUKA LWR4 robot manipulator.");
kukalw4robot_py.def_static("kinematics",&KukaLw4Robot::kinematics,"Returns the kinematic model of the KUKA LWR4 robot manipulator.");

//#include <dqrobotics/robots/KukaYoubotRobot.h>
py::class_<KukaYoubotRobot> kukayoubotrobot_py(robots_py, "KukaYoubotRobot");
kukayoubotrobot_py.def_static("kinematics",&KukaYoubotRobot::kinematics,"Returns the kinematics of the KukaYoubotRobot");
py::class_<KukaYoubotRobot> kukayoubotrobot_py(robots_py, "KukaYoubotRobot",
"Provides the whole-body kinematic model of the KUKA youBot mobile manipulator.");
kukayoubotrobot_py.def_static("kinematics",&KukaYoubotRobot::kinematics,"Returns the whole-body kinematic model of the KUKA youBot mobile manipulator.");

//#include <dqrobotics/robots/FrankaEmikaPandaRobot.h>
py::class_<FrankaEmikaPandaRobot> frankaemikapandarobot_py(robots_py, "FrankaEmikaPandaRobot");
frankaemikapandarobot_py.def_static("kinematics",&FrankaEmikaPandaRobot::kinematics,"Returns the kinematics of the FrankaEmikaPandaRobot");
py::class_<FrankaEmikaPandaRobot> frankaemikapandarobot_py(robots_py, "FrankaEmikaPandaRobot",
"Provides the kinematic model of the Franka Emika Panda robot manipulator.");
frankaemikapandarobot_py.def_static("kinematics",&FrankaEmikaPandaRobot::kinematics,"Returns the kinematic model of the Franka Emika Panda robot, as calibrated by the manufacturer.");

/*****************************************************
* Solvers <dqrobotics/solvers/...>
* **************************************************/
py::module solvers = m.def_submodule("_solvers", "The solvers submodule of dqrobotics");
py::module solvers = m.def_submodule("_solvers", "Quadratic-programming solver interfaces used by the QP-based kinematic controllers.");

//DQ_QuadraticProgrammingSolver
init_DQ_QuadraticProgrammingSolver_py(solvers);

/*****************************************************
* Robot Control <dqrobotics/robot_control/...>
* **************************************************/
py::module robot_control = m.def_submodule("_robot_control", "The robot_control submodule of dqrobotics");

py::enum_<ControlObjective>(robot_control, "ControlObjective")
.value("Line", ControlObjective::Line)
.value("None", ControlObjective::None)
.value("Pose", ControlObjective::Pose)
.value("Plane", ControlObjective::Plane)
.value("Distance", ControlObjective::Distance)
.value("DistanceToPlane",ControlObjective::DistanceToPlane)
.value("Rotation", ControlObjective::Rotation)
.value("Translation", ControlObjective::Translation)
py::module robot_control = m.def_submodule("_robot_control", "Kinematic controllers that drive a robot's task-space error to zero.");

py::enum_<ControlObjective>(robot_control, "ControlObjective",
"Enumerates the task-space objectives supported by DQ_KinematicController.")
.value("Line", ControlObjective::Line, "Control a line primitive attached to the end-effector.")
.value("None", ControlObjective::None, "No control objective has been selected yet.")
.value("Pose", ControlObjective::Pose, "Control the full end-effector pose.")
.value("Plane", ControlObjective::Plane, "Control a plane primitive attached to the end-effector.")
.value("Distance", ControlObjective::Distance, "Control the squared distance between the end-effector translation and the origin.")
.value("DistanceToPlane",ControlObjective::DistanceToPlane,"Control the signed distance from the end-effector point to a target plane.")
.value("Rotation", ControlObjective::Rotation, "Control only the end-effector orientation.")
.value("Translation", ControlObjective::Translation, "Control only the end-effector translation.")
.export_values();

//DQ_KinematicController
Expand All @@ -154,12 +165,12 @@ PYBIND11_MODULE(_dqrobotics, m) {
/*****************************************************
* Interfaces Submodule
* **************************************************/
py::module interfaces_py = m.def_submodule("_interfaces", "A submodule of dqrobotics");
py::module interfaces_py = m.def_submodule("_interfaces", "Interfaces to third-party simulators and data formats.");

/*****************************************************
* Json11 submodule
* **************************************************/
py::module json11_py = interfaces_py.def_submodule("_json11", "A submodule of dqrobotics");
py::module json11_py = interfaces_py.def_submodule("_json11", "Reads dqrobotics objects (DQ, robot models) serialized as JSON using the json11 library.");

//DQ_JsonReader
init_DQ_JsonReader_py(json11_py);
Expand Down
26 changes: 21 additions & 5 deletions src/interfaces/json11/DQ_JsonReader_py.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,28 @@ This file is part of DQ Robotics.

#include "../../dqrobotics_module.h"

/**
* @brief Binds `DQ_JsonReader`, which reads supported robot-description JSON
* files and constructs serial manipulator objects from them, to the Python
* module @p m.
*/
void init_DQ_JsonReader_py(py::module& m)
{
py::class_<DQ_JsonReader> jsonreader_py(m,"DQ_JsonReader");
jsonreader_py.def(py::init<>());

jsonreader_py.def_static("get_serial_manipulator_dh_from_json",&DQ_JsonReader::get_from_json<DQ_SerialManipulatorDH>,"Gets a DQ_KinematicsDH instance from a .json file");
jsonreader_py.def_static("get_serial_manipulator_denso_from_json",&DQ_JsonReader::get_from_json<DQ_SerialManipulatorDenso>,"Gets a DQ_KinematicsDenso instance from a .json file");
py::class_<DQ_JsonReader> jsonreader_py(
m,
"DQ_JsonReader",
"Reads supported robot-description JSON files and constructs serial manipulator objects from them.");
jsonreader_py.def(py::init<>(), "Constructs a JSON reader instance.");

jsonreader_py.def_static(
"get_serial_manipulator_dh_from_json",
&DQ_JsonReader::get_from_json<DQ_SerialManipulatorDH>,
py::arg("file"),
"Reads a JSON file describing a DQ_SerialManipulatorDH, converts angle fields according to the file's angle mode, initializes the common serial-manipulator properties, and returns the resulting model.");
jsonreader_py.def_static(
"get_serial_manipulator_denso_from_json",
&DQ_JsonReader::get_from_json<DQ_SerialManipulatorDenso>,
py::arg("file"),
"Reads a JSON file describing a DQ_SerialManipulatorDenso, converts angle fields according to the file's angle mode, initializes the common serial-manipulator properties, and returns the resulting model.");
//This might be relevant in the future https://github.com/pybind/pybind11/issues/199
}
42 changes: 34 additions & 8 deletions src/interfaces/vrep/DQ_SerialVrepRobot_py.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ This file is part of DQ Robotics.

#include "../../dqrobotics_module.h"

/**
* @brief Binds `DQ_SerialVrepRobot`, a serial-robot wrapper that exposes joint
* names, target commands, velocities, and torques in CoppeliaSim, to the
* Python module @p m.
*/
void init_DQ_SerialVrepRobot_py(py::module& m)
{
/*****************************************************
Expand All @@ -31,19 +36,40 @@ void init_DQ_SerialVrepRobot_py(py::module& m)
DQ_SerialVrepRobot,
std::shared_ptr<DQ_SerialVrepRobot>,
DQ_VrepRobot
> dqsv_robot(m,"DQ_SerialVrepRobot");
> dqsv_robot(
m,
"DQ_SerialVrepRobot",
"Serial robot wrapper for exchanging joint names, target commands, velocities, and torques with CoppeliaSim.");


dqsv_robot.def("get_joint_names", &DQ_SerialVrepRobot::get_joint_names, "Gets the joint names used in CoppeliaSim.");
dqsv_robot.def("get_joint_names",
&DQ_SerialVrepRobot::get_joint_names,
"Gets the joint names used in CoppeliaSim.");

dqsv_robot.def("set_target_configuration_space_positions", &DQ_SerialVrepRobot::set_target_configuration_space_positions, "Sets the target configuration space positions in CoppeliaSim.");
dqsv_robot.def("set_target_configuration_space_positions",
&DQ_SerialVrepRobot::set_target_configuration_space_positions,
py::arg("q"),
"Sets the target configuration-space positions in CoppeliaSim.");

dqsv_robot.def("get_configuration_space_velocities", &DQ_SerialVrepRobot::get_configuration_space_velocities, "Sets the target configuration space velocities in CoppeliaSim.");
dqsv_robot.def("set_target_configuration_space_velocities", &DQ_SerialVrepRobot::set_target_configuration_space_velocities, "Gets the configuration space velocities in CoppeliaSim.");
dqsv_robot.def("get_configuration_space_velocities",
&DQ_SerialVrepRobot::get_configuration_space_velocities,
"Gets the configuration-space velocities from CoppeliaSim.");
dqsv_robot.def("set_target_configuration_space_velocities",
&DQ_SerialVrepRobot::set_target_configuration_space_velocities,
py::arg("q_dot"),
"Sets the target configuration-space velocities in CoppeliaSim.");

dqsv_robot.def("set_configuration_space_torques", &DQ_SerialVrepRobot::set_configuration_space_torques, "Sets the configuration space torques in CoppeliaSim.");
dqsv_robot.def("get_configuration_space_torques", &DQ_SerialVrepRobot::get_configuration_space_torques, "Gets the configuration space torques in CoppeliaSim.");
dqsv_robot.def("set_configuration_space_torques",
&DQ_SerialVrepRobot::set_configuration_space_torques,
py::arg("torques"),
"Sets the configuration-space torques in CoppeliaSim.");
dqsv_robot.def("get_configuration_space_torques",
&DQ_SerialVrepRobot::get_configuration_space_torques,
"Gets the configuration-space torques from CoppeliaSim.");

//Deprecated
dqsv_robot.def("send_q_target_to_vrep", &DQ_SerialVrepRobot::send_q_target_to_vrep, "Send target joint values to CoppeliaSim.");
dqsv_robot.def("send_q_target_to_vrep",
&DQ_SerialVrepRobot::send_q_target_to_vrep,
py::arg("q"),
"Deprecated alias for setting the target configuration-space positions in CoppeliaSim.");
}
Loading
Loading