DOCS.md

Wrap Module Definition

Important

The python wrapper supports keyword arguments for functions/methods. Hence, the argument names matter. An implementation restriction is that in overloaded methods or functions, arguments of different types have to have different names.

Requirements

• Classes must start with an uppercase letter.

  • The wrapper can wrap a typedef, e.g. typedef TemplatedClass<Arg> EasyName;.

• Only one Method/Constructor per line, though methods/constructors can extend across multiple lines.

• Methods can return

  • Eigen types: gtsam::Matrix, gtsam::Vector.
  • C/C++ basic types: string, bool, size_t, int, double, char, unsigned char.
  • void
  • Any class with which be copied with std::make_shared().
  • std::shared_ptr of any object type.

• Constructors

  • Overloads are supported, but arguments of different types have to have different names.
  • A class with no constructors can be returned from other functions but not allocated directly in MATLAB.

• Methods

  • Constness has no effect.
  • Specify by-value (not reference) return types, even if C++ method returns reference.
  • Must start with a letter (upper or lowercase).
  • Overloads are supported.

• Static methods

  • Must start with a letter (upper or lowercase) and use the "static" keyword, e.g. static void func().
  • The first letter will be made uppercase in the generated MATLAB interface.
  • Overloads are supported, but arguments of different types have to have different names.

• Arguments to functions can be any of

  • Eigen types: gtsam::Matrix, gtsam::Vector.
  • Eigen types and classes as an optionally const reference.
  • C/C++ basic types: string, bool, size_t, size_t, double, char, unsigned char.
  • Any class with which be copied with std::make_shared() (except Eigen).
  • std::shared_ptr of any object type (except Eigen).

• Properties or Variables

  • You can specify class variables in the interface file as long as they are in the public scope, e.g.

  class Sample {
      double seed;
  };

  • Class variables are read-write so they can be updated directly in Python.
  • For the Matlab wrapper, specifying the full property type (including namespaces) is required.

  class TriangulationResult {
    gtsam::SharedNoiseModel noiseModel;
  };

  • If the property is part of an enum within the class, the type should be specified as gtsam::Class::Enum. Similarly for templated types where This is used, e.g. gtsam::This::Enum.

  class TriangulationResult {
    enum Status { VALID, DEGENERATE, BEHIND_CAMERA, OUTLIER, FAR_POINT };
    gtsam::TriangulationResult::Status status;
  };
  
  template<PARAMS>
  virtual class GncParams {
    enum Verbosity {
      SILENT,
      SUMMARY,
      VALUES
    };
    gtsam::This::Verbosity verbosity;
  };

• Operator Overloading (Python only)

  • You can overload operators just like in C++.

  class Overload {
      Overload operator*(const Overload& other) const;
  };

  • Supported operators are the intersection of those supported in C++ and in Python.
  • Operator overloading definitions have to be marked as const methods.

• Pointer types

  • To declare a simple/raw pointer, simply add an @ to the class name, e.g.Pose3@.
  • To declare a shared pointer (e.g. gtsam::noiseModel::Base::shared_ptr), use an asterisk (i.e. *). E.g. gtsam::noiseModel::Base* to define the wrapping for the Base noise model shared pointer.

• Comments can use either C++ or C style, with multiple lines.

• Namespace definitions

  • Names of namespaces must start with a lowercase letter.
  • Start a namespace with namespace example_ns {, where example_ns is the namespace name.
  • End a namespace with exactly }
  • Namespaces can be nested.

• Namespace usage

  • Namespaces can be specified for classes in arguments and return values.
  • In each case, the namespace must be fully specified, e.g., namespace1::namespace2::ClassName.

• Includes in C++ wrappers

  • All includes will be collected and added in a single file.
  • All namespaces must have angle brackets, e.g. #include <path>.
  • No default includes will be added.

• Global/Namespace functions

  • Functions specified outside of a class are global.
  • Can be overloaded with different arguments.
  • Can have multiple functions of the same name in different namespaces.
  • Functions can be templated and have multiple template arguments, e.g.

    template<T, R, S>

• Global variables

  • Similar to global functions, the wrapper supports global variables as well.
  • Currently we only support primitive types, such as double, int, string, etc.
  • E.g.

    const double kGravity = -9.81;

• Using classes defined in other modules

  • If you are using a class OtherClass not wrapped in an interface file, add class OtherClass; as a forward declaration to avoid a dependency error.
  • OtherClass may not be in the same project. If this is the case, include the header for the appropriate project #include <other_project/OtherClass.h>.

• Virtual inheritance

  • Specify fully-qualified base classes, i.e. virtual class Derived : ns::Base { where ns is the namespace.

  • Mark with virtual keyword, e.g. virtual class Base {, and also virtual class Derived : ns::Base {.

  • Base classes can be templated, e.g. virtual class Dog: ns::Animal<Pet> {};. This is useful when you want to inherit from specialized classes.

  • Forward declarations must also be marked virtual, e.g. virtual class ns::Base; and also virtual class ns::Derived;.

  • Pure virtual (abstract) classes should list no constructors in the interface file.

  • Virtual classes must have a clone() function in C++ (though it does not have to be included in the interface file). clone() will be called whenever an object copy is needed, instead of using the copy constructor (which is used for non-virtual objects).

  • Signature of clone function - clone() will be called virtually, so must appear at least at the top of the inheritance tree

    virtual std::shared_ptr<CLASS_NAME> clone() const;

• Templates

  • Basic templates are supported either with an explicit list of types to instantiate, e.g.

    template<T = {gtsam::Pose2, gtsam::Rot2, gtsam::Point3}> class Class1 { ... };

    or with typedefs, e.g.

    template<T, U> class Class2 { ... };
    typedef Class2<Type1, Type2> MyInstantiatedClass;

  • Templates can also be defined for constructors, methods, properties and static methods.

  • In the class definition, appearances of the template argument(s) will be replaced with their instantiated types, e.g. void setValue(const T& value);.

  • Values scoped within templates are supported. E.g. one can use the form T::Value where T is a template, as an argument to a method.

  • To refer to the instantiation of the template class itself, use This, i.e. static This Create();.

  • To create new instantiations in other modules, you must copy-and-paste the whole class definition into the new module, but use only your new instantiation types.

  • When forward-declaring template instantiations, use the generated/typedef'd name, e.g.

    class gtsam::Class1Pose2;
    class gtsam::MyInstantiatedClass;

  • Template arguments can be templates themselves, e.g.

    // Typedef'd PinholeCamera
    template<CALIBRATION>
    class PinholeCamera { ... };
    typedef gtsam::PinholeCamera<gtsam::Cal3_S2> PinholeCameraCal3_S2;
    
    template<CAMERA>
    class SfmFactor { ... };
    // This is valid.
    typedef gtsam::SfmFactor<gtsam::PinholeCamera<gtsam::Cal3_S2>> BasicSfmFactor;

• Boost.serialization within the wrapper:

  • You need to mark classes as being serializable in the markup file (see gtsam.i for examples).
  • There are two options currently, depending on the class. To "mark" a class as serializable, add a function with a particular signature so that wrap will catch it.

    • Add void serialize() to a class to create serialization functions for a class. Adding this flag subsumes the serializable() flag below.

      Requirements:

      • A default constructor must be publicly accessible.
      • Must not be an abstract base class.
      • The class must have an actual boost.serialization serialize() function.

    • Add void serializable() to a class if you only want the class to be serialized as a part of a container (such as noiseModel). This version does not require a publicly accessible default constructor.

• Forward declarations and class definitions for Pybind:

  • Need to specify the base class (both this forward class and base class are declared in an external Pybind header)

  • This is so that Pybind can generate proper inheritance.

  • Example for when wrapping a gtsam-based project:

     // forward declarations
     virtual class gtsam::NonlinearFactor
     virtual class gtsam::NoiseModelFactor : gtsam::NonlinearFactor
     // class definition
     #include <MyFactor.h>
     virtual class MyFactor : gtsam::NoiseModelFactor {...};

  • DO NOT re-define an overriden function already declared in the external (forward-declared) base class. This will cause an ambiguity problem in the Pybind header file.

• Splitting wrapper over multiple files

  • The Pybind11 wrapper supports splitting the wrapping code over multiple files.
  • To be able to use classes from another module, simply import the C++ header file in that wrapper file.
  • Unfortunately, this means that aliases can no longer be used.
  • Similarly, there can be multiple preamble.h and specializations.h files. Each of these should match the module file name.

TODO

• Handle gtsam::Rot3M conversions to quaternions.
• Parse return of const ref arguments.
• Parse std::string variants and convert directly to special string.
• Add generalized serialization support via boost.serialization with hooks to MATLAB save/load.