Hi Everybody,
I use Eigen for about three month every now and then (e.g. when working with the point cloud library) and while the API showcase definitely looks "clean and expressive", I constantly have problems looking up things that should be easy. I dislike to copy and paste my programs together, and rather use the documentation to see how to call methods and what is given back.
However, most often it takes me a long time to look up something like how to do the cross product. I know it is in the tutorial, but when I looked it up in the API i stumbled across the return type "MatrixBase< Derived >::template cross_product_return_type< OtherDerived >::type". I don't even recognize the syntax. cross3 has MatrixBase< Derived >::PlainObject, which doesn't tell me much (clicking it takes me to Matrix< _Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols >) but at least seems syntactically familiar. So I guess it is some typedef. However it is not listed on http://eigen.tuxfamily.org/dox/group__m ... edefs.html - a very helpful page once found, it is perfectly hidden - at least I found it only through google. So where would I find out what the return value is? I can guess, but a wrong guess might produce a subtle bug.
Similarly I wanted to use AngleAxis::toRotationMatrix(), but the return type is "AngleAxis< Scalar >::Matrix3". When I click on Matrix3, again the page of Matrix< _Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols > opens. Again the typedef declaration is not to be found.

This is not meant to be a rant. Please don't tell me that I need to approach this differently. I do know that, I just don't know how. Besides, this is not about the specific examples mentioned - I solved the problems above with Qt classes of which the documentation is crystal clear. But in general I'd rather work with the types I get from the libraries I work with.

tl;dr: Looking up method in the docs, confuses the hell out of me w.r.t. the types of arguments and return value. Any suggestions?

Perhaps you should have a look at this page, it explains the hierarchy a bit: http://eigen.tuxfamily.org/dox/TopicClassHierarchy.html

It's a bit complicated because Eigen uses template programming. It takes a while to get familiar with, but actually you don't need to worry about it, as long as you don't aim to extend Eigen.

About your example. Which information is missing? cross returns a MatrixBase derived type, meaning its a matrix. toRotationMatrix returns a Matrix3 type, meaning its a 3x3 matrix. Clicking them leads you to the description of the classes, showing you all methods and so on. What's missing? Or is it just the template information that seems a bit confusing?

Thank you, that's an interesting read. So in general I don't know what exactly the thing (return value or parameter) is, I just know some superclass and need to trust the documentation (or common sense) to know what types and template arguments to use, right?
Reminds me of dynamically typed languages, except there I really don't need to know, because I don't need to declare the type of variables.

What's still missing is where you got the information that Matrix3 is 3x3 Matrix.

I don't know if its in the Docs, but its a convenience typedef of the Geometry module: https://bitbucket.org/eigen/eigen/src/4 ... ngleAxis.h

I just wanted to sympathize with the troubles of the original poster. This is one of the areas where the documentation needs to be improved. Many return types are typedefs that are not explained in the documentation, so I often find myself having to look into the source code if I need to know precise details.

The return types are actually often a bit more complicated than they appear. From reading the source code, it seems that the return type of the cross() member function takes into account that you can take the cross product of a real vector with a complex vector, as in:

Code: Select all

   Vector3f vecReal;
   Vector3cf vecComplex;
   // initialize vecReal and vecComplex
   Vector3cf vecResult = vecComplex.cross(vecReal);


In this case, the result type should be a complex vector. Of course this should ideally have been documented ...

Another complication is that many functions do not return a matrix even though they seem to return one. For instance, you can write

Code: Select all

  MatrixXf matrix1, matrix2;
  // initialize matrix1 and matrix2
  MatrixXf matrixSum = matrix1 + matrix2;


However, the result returned by the expression matrix1 + matrix2 is not a matrix, but a temporary object which can be assigned to a matrix. This is partially explained in http://eigen.tuxfamily.org/dox/TopicLazyEvaluation.html and in more detail in http://eigen.tuxfamily.org/dox/TopicIns ... ample.html . In this case, you don't need to know the type of the expression matrix1 + matrix2, and it's perhaps even better that you don't know. What you do however need to know (and what should be explained) is that the result behaves like a MatrixXf.