Bundle example snippets to create visualizable objects

[clangguth]

Contrary to the "core" scalismo project, this project currently does not have any unit tests. The reason is that it's notoriously hard to write such tests for User Interfaces, as they almost entirely depend on user interaction.

However, in order to properly test how the UI presents scalismo objects, and their visualization properties, an easy way to set them up in the first place is needed.

I therefore propose that this project should contain "somewhere" code which produces usable base objects, for each of the supported renderable objects. That can really be absolutely minimal "mock" objects -- for instance a TriangleMesh that is a pyramid, or landmarks/pointclouds consisting of just 3 points, etc. The idea is simply that there would be some code somewhere which
a) can be used quickly and easily when needed, and
b) is concise and simple enough to facilitate understanding for newcomers.

As to where "somewhere" should be, I'm not entirely sure. The easiest way would be to include it in src/main, but that feels kind of wrong, because the stuff would end up in the distribution. src/test seems to make sense, but I fear that most people associate it with build-time tests only. Maybe src/example? ... But anyway, that's a detail for further discussion.

Here's a very basic sketch, to give a more concrete idea of what I mean:

object Examples {

  // example of points which form a "distorted" pyramid (i.e., a tetrahedron)
  lazy val PointCloudExample: IndexedSeq[Point3D] = {
    List((0,0,0), (80,10,20), (30,50,25), (40,20,70)).map{
      case (x,y,z) => Point3D(x,y,z)
    }.toIndexedSeq
  }

  // triangle mesh formed from the point cloud example
  lazy val TriangleMeshExample: TriangleMesh3D = {
    val triangleCells: List[TriangleCell] = List((0,1,2),(0,1,3),(0,2,3),(1,2,3))
      .map{p => TriangleCell(PointId(p._1), PointId(p._2), PointId(p._3))}
    TriangleMesh3D(PointCloudExample, TriangleList(triangleCells.toIndexedSeq))
  }

  // trivial scalar mesh field formed from the triangle mesh example
  lazy val ScalarMeshFieldExample: ScalarMeshField[Int] = {
    // scalar values of points assigned from the index of the point in the mesh,
    // scaled by an arbitrary factor.
    val scalars = TriangleMeshExample.pointSet.pointSequence.zipWithIndex.map(_._2 * 42)
    ScalarMeshField(TriangleMeshExample, scalars)
  }

  // example for creating a UI and adding example objects, using the API.
  def main(args: Array[String]): Unit = {
    val ui = ScalismoUI()
    val group = ui.createGroup("Group Example")
    ui.show(group, PointCloudExample, "Point Cloud Example")
    //ui.show(group, TriangleMeshExample, "TriangleMesh Example")
    ui.show(group, ScalarMeshFieldExample, "ScalarMeshField Example")
  }
}

As said, this is just a first draft, incomplete and probably not organized the way it should be. But IMO it's concise, reusable (so it can be leveraged in tests), and understandable (so it could also double as a simple hands-on example to get started).

What do you guys think about this matter?

[marcelluethi]

I think this is a very good idea and we should include that.
Do you think it would be beneficial to use real datasets or is it sufficient to create them as in your example?

[clangguth]

I guess that ultimately it makes more sense to include real datasets, especially for the more complicated things like 3D images, statistical shape models, tetrahedral meshes etc. That would be more useful, and creating them "manually" (in code) probably becomes prohibitively complicated anyway...