Clarify dimensions of matrix inputs

[Andlon]

Hi Zach and others! I thought I'd give the ipc-toolkit a spin for integrating contact with some deformable sims. Thanks for releasing the toolkit to the public!

I'm still getting used to the API, but one immediate point of confusion is that the matrix conventions are not so obvious to me. A number of functions take, for example, MatrixXd or MatrixXi, for example for describing a collision mesh. Of course, given the context, the options are limited: Edges for example are either 2xN or Nx2. However, since this doesn't appear to be documented (or is it? Maybe I missed it), working with the otherwise intuitive-looking APIs become a bit of guess work and/or detective work to reverse-engineer the conventions from the code. It would be great if this could be more clearly documented!

EDIT: In retrospect, I suppose that the library uses libigl conventions? I guess if you're not coming from the geometry processing community, these conventions may not be so familiar...

[Andlon]

Beyond matrix dimensions, it might also be good to explicitly state other assumptions. For example, when describing faces, am I correct in assuming that they should be oriented so that the normal - as determined by a counter-clockwise winding order - are pointing outwards?

[zfergus]

Hi Andreas! Thanks for pointing out this issue. I thought it was better documented, but recent changes must have removed this information.

Throughout the toolkit, the vertex position and velocity matrices are expected to be $|V| \times d$ where $|V|$ is the number of vertices and $d$ is the dimension (2 or 3). The edge and face matrices should be $|E| \times 2$ and $|F| \times 3$, respectively, where $|E|$ is the number of edges and $|F|$ is the number of faces. (This is the same format that libigl uses, but if you're not coming from the geometry processing community it can definitely be confusing.)

The orientation of the faces does not matter because we never use the concept of inside/outside or normal vectors in the toolkit (or in the IPC algorithm in general).

I will update the documentation (code and website) to make both of these points clear. Let me know if you find any other undocumented assumptions.

[Andlon]

Thanks for the swift response, and the clarifications. figured that the conventions would be like this - just thought I'd note that it would make the initial onboarding experience a little better if these were spelled out explicitly. One less thing to wonder about!

Good to know about the orientation. I know it's not necessary for the IPC algorithm in general but it was not clear to me if it was, for example, important for the CCD, with which I have much less familiarity!

I'm happy to say that I very swiftly was able to get things up and running, i.e. assembly of the potential, gradient and Hessian, as well as determining the maximal step size. Great job in making IPC so accessible! I have yet to integrate it into my actual simulator, and there are some things I don't fully understand just yet, but I'd like to play around with it a bit more before I potentially come back with more questions :-)