Tutorial Assignment 1: Getting started

Welcome to the blog for the tutorial [Übung] for MathVisWS 2012.  Your work in this course will be project-oriented, based on the themes of the lectures.  Students will work in groups of two or three on programming assignments, including the final project.  For this work we will use the software tools:

  1. Java, an object-oriented programming language,
  2. Eclipse, a freely available IDE (integrated development environment) for writing Java applications, and
  3. jReality, an open-source, Java-based 3D scene graph created and maintained by the math department at TU-Berlin.

You may work on your own laptop rather than the institute machines in MA 316.  Please bring your laptop to class on Thursdays. Report technical problems to Dr. Gunn.

Getting started

For the first week, students are expected to familiarize themselves with the software:

  • Visit the jReality Wiki and explore the on-line Developer’s Tutorial, in order to gain an impression of jReality.
  • Get a login: Whether you are working with your own laptop or not, register with Dr. Gunn for an institute computer account (You’ll need this login to access the SVN repository and to post comments on this blog — whether you use the institute computers or not).
  • To login in to the institute machines, you can access the machines in MA 316 at any time — [I will send the key-code in an e-mail when it has been entered into the doorlock].  You should run a specific version of eclipse on these machines, which includes SVN plugin:
    • ln -s /net/MathVis/eclipse64-subversive/eclipse eclipse
    • ./eclipse
  • Download jReality: Follow the directions on the jReality Wiki to download jReality into eclipse as a Java project.
  • Setup Javadoc for the jReality project.
    • Select Project->Properties
    • On the popup window, select Javadoc Location.
    • Enter http://www3.math.tu-berlin.de/jreality/api.
    • Now, in the Java editor, you can read the Javadoc for a selected class or method by choosing the menu item Navigate->Open External Javadoc
  • Run the tutorial examples: In the Java Package Explorer of eclipse, navigate to the src-tutorialfolder, and run the tutorial examples:
    • Right-click in the Package Explorer on the class name, and
    • Choose “Run as Java Application” from pull-down menu.
    • The most important folders, in order of importance, for our work now are:  intro, geom, app, tform, and viewer.
  • Check out the course SVN project: into your Eclipse workspace 
    • In the SVN repository browser in eclipse, use right click to add the svn repository http://fs.math.tu-berlin.de:8000/svn/MathVis/WS12.  Use your  course login as the login to access this repository (e. g., mvws0123).
      • The password for the svn access has been sent in a separate email to your course account; if you haven’t yet logged into that account, do so now.
      • Read your email in a shell using the command Mail.
    •  In the SVN Repository browser, select  “Check out…” from the right-mouse menu.
    • Back in the Java Package Explorer, you should see another Java project entitled WS12.  Create a single package in the src folder for your group, using right-click then “New->Package“.  Name it so that all last names of group members are present, for example, hoffmannmueller.  You will do all your work for the tutorial within this package.
    • Each time you login to Eclipse, make a habit of updating from  the SVN repository for both jReality and WS12:
      • Select a project, then right-click and select Team->Synchronize with Repository.  
      • This should bring you into the Team Synchronizing perspective.
      • Select the project name, then right-click and select Update. Or if you have made changes to your own work and want to check it in, select Commit.  For finer control, navigate to specific resources and select Update or Commit for each resource.
  • Do the assignment (see below).

A description of the jReality scene graph can be found here.  This is roughly the same material, but more detailed, as what Dr. Gunn presented in the tutorial on Thursday. Email questions to me: gunn at math.tu-berlin.de


  1. Choose with your team members a favorite topic in mathematics.  Choose one topic which lends itself to being visualized using the capabilities you’ve discovered in your exploration of jReality.  For example, a favorite surface, structure, graph, function, map, polyhedron, or curve.  Restrict your attention to one aspect of this topic which can be implemented in one or two hours.  Choose the tutorial example which is most similar to your choice of topic.  Make a copy of the tutorial class and paste it into your group package in the WS12 project, renaming it Assignment1.java.
  2. Edit it to do what you want it to do.  At the top of the .java file add documentation describing what you did.  See the example in the package gunn.  Make sure your code runs, then use Team synchronizing perspective to check in your work.  Please, check in only the file Assignment1.java, not derived folders such as bin or build which you might have created.
  3.  Finally, after you’re satisfied with the result, reflect on the experience of writing this class.  Post a comment (see below) to this post in which you describe the programming experience.  (Comments are individual, not group-based.) What was harder than you expected?  What was easier?  Were there things which you couldn’t do which you had intended to do?  Was the documentation adequate?   (See note above regarding posting comments here).

Posting comments:

Some assignments, as the one above, ask you to post a comment to a post on this blog.  You have a choice of how to identify yourself when you make this comment.  You may either use your real name, or, if you choose to remain anonymous, you may use the login name you received for the course (e. g., mvws1223).  In any case, please provide as e-mail address the address you gave me on the sign-up sheet for the course.  The e-mail address will NOT be published with your comment, it is for verification purposes only.

Notice that you may use LaTeX commands in your comments, but they will only be evaluated when the comment is posted; the comment preview plugin doesn’t handle LaTeX.


18 thoughts on “Tutorial Assignment 1: Getting started

  1. Hi!

    As I’m interested in Algebraic Geometry, I would like to implement the Clebsch Cubic with its 27 lines in jReality, like this one: http://www.algebraicsurface.net/models/images/clebsch_27lines_gray_big.jpg
    The problem: the surface is always given as a variety and I couldnt find a parameterization. Is there a way to either find a nice one or to plug in implicit plots?
    By the way, the Clebsch Surface is given by $V(x_{0}^{3}+x_{1}^{3}+x_{2}^{3}+x_{3}^{3}+x_{4}^{3}, x_{0}+x_{1}+x_{2}+x_{3}+x_{4})$


    • Oh and another thing would be a nice and symmetric picture of the $K_{7}$ embedded on a Torus. I couldnt find one on google. So we have to find a good way to set lines and points on tori.

      • I think you should think of the torus in this case as a unit square $Q$ with identifications on the edges (if you don’t understand what this means, this will form a theme of later lectures in this course). Then, calculate the $K_7$ imbedding for this square (where edges of the graph will cross over the sides via the identifications). If $\theta: Q \rightarrow \mathbb{R}^3$ is an embedding of this torus in 3-space, to draw a picture of $K_7$ on the torus $\theta(Q)$, write a helper class in Java which applies $\theta$ to all geometric primitives in a scene graph, and then apply it to the scene graph representing the flat $K_7$ on $Q$. This is an appropriate starting point for a semester project.

        • Thanks for your comment!
          I’m quite familiar with the “take-a-square-and-glue-the-edges-together” story (since I took a topology and discrete topology class). I just didnt now that this works in jReality as well. What is the best tutorial to start with? I found a cylinder. Is this one constructed this way?
          Also with the $K_{7 }$ we would get the nice seven coloring of the torus. I’m looking forward to this project!

      • Thanks for your comment!
        I found the same reference, but couldnt figure out the best way to get a parametrization (yet?). I will think about it again.

  2. Today, Robert and I started working on the $K_{7}$ on the torus story. We figured out two main problems:

    1. How to calculate a nice symmetric drawing of the $K_{7}$ into the square.
    and more importantly:
    2. How to get from the square to the torus. We could figure out the transformation to apply on the square. Furterhmore there’s an issue with the modeling: We build the square out of vertices and then faces, but we also could have done it by a cube with zero height. What’s the better way to achieve our goals?

    With the vertices and faces, we build a seven vertex triangulation of the torus (without the identification) today. See the SVN loewesieg

    See you tomorrow!

        • Here is the correct parametrization :
          Assuming that we start from a unit square for parameters u,v (u,v \in [0,1]), and have a
          big radius R and a small radius r for the torus parameters, the correct parametrization reads
          x(u,v) = R cos(u2pi) + r cos(u2pi) cos(v2pi)
          y(u,v) = R sin(u2pi) + r sin(u2pi) cos(v2pi)
          z(u,v) = r sin(v2pi)
          This gives a torus centered at the origin and the z-axis going through the torus hole.
          Rewriting the ParametricSurfaceExample from the Geometry-Tutorials is a quick way to verify the above formula.

          • I’ve added a class AbstractDeformation to the util package in the SVN repository WS12. It allows you to transform all geometry in a scene graph according to an arbitrary map $R^3 \rightarrow R^3$. It has a main() method which you should run to see how this works for a concrete example (the torus, naturally).

  3. Our idea was it to visualize a fractal, i.e. the snowflake fractal.
    Therefor we created an equilateral triangle and iteratively we add at the middle third of each edge another equilateral triangle.
    In the 8th step we added in this way over 15.000 triangles and in the 9th step over 60.000 🙂

    By programming we had to major problems:
    First, we had to calculate the third point of each triangle. Because we don’t want to restrict the possible starting-triangle a simple calculation wasn’t possible. But then we calculated the normal vector of the triangle and rotate the edge about 90°. That – and that all triangles are equilateral – allowed us to find the last point.
    The second problem was, that we had thousands of points that want to be connected. So we had to find out, how we can enumerate the vertices in a way to find them later. In the end we inserted new points in the right order, such that the points are sorted in the boundary. The faces uses then three neighboring points, let one free and so on. In the next level the take the every fourth point…

    Finally here are some pictures from the fractal from level 8&9, level 10 with more than 260k triangles my pc don’t compute any more;)


    • Thanks for this nice example! Fractals belong in every mathematical visualization course, I think. Another approach for this same fractal uses just one triangle and then applies different transformations to transform it into the positions required. See the book Iterated Function Systems by Michael Barnsley.

      There are some classes in jReality which can help you out in some of the calculations you are making. The main class is called de.jreality.math.Rn (in the src-core folder of jReality) and, as the name implies, it deals with operations on euclidean vectors. I’ve edited your code to use methods from Rn whenever possible, renamed it Assignment1UsingRn, and checked it back in. I encourage other students reading this comment to take a look at this helper class Rn when doing vector calculations.

      • Aah, ok, I don’t know this class. It is much shorter so and certainly it will be useful in later assignments.
        I’m not sure if I completely understand how this works with matrices but it looks quite elegant although it doesn’t work for the 8th step of iteration (Java heap space). Do you know, why this method fails earlier than the method with Rn?

        • It probably fails earlier because it builds a scene graph node for each triangle (then at the end it collects all the triangles into a single IndexedFaceSet for each level, to improve performance). To avoid heap space problems, you can direct the Java Virtual Machine to allocate more space when it starts up. To allocate 2 GByte initially and as final limit use the arguments -Xms2048m -Xmx2048m. You can set this just for this application in Eclipse using the menu item Run configurations…->Arguments->VM arguments, or globally using Eclipse->Preferences…->Java->Installed JRE’s->Edit->Default VM Arguments.

  4. Hi,

    this is going to be my thoughts about my first steps in Jreality for the assignment sheet 1. As project to start with, we chose a visualization of the (magic) Rubic’s Cube. More interesting than the geometry of an axis-parallel cube appeared the possibility to explore jreality user interaction features.
    In the end, we pasted three of the tutorials together (IndexedFaceSetFactory, SliderExample, and some Transformation example) to enable us to rotate one (predefined) layer almost freely around.
    This work could be, of course, extended to a working cube, for which the user can choose the next layer to proceed with. Besides, the whole application would be essentially more interesting if the cube were not solved right after the Viewer pops up.
    The work with JReality so far was quite comfortable. I appreciate the design of the tutorials, although I had troubles trying to change the cube’s appearance (I think this was because I just took the appearance from a sceneGraphComponent instead of constructing a new one, so I basically got a null-pointer exception, which was, however, encrypted behind a different exception).
    I think, in general we could have some more introductory material about setting up whole scenes in the tutorial, where an initially introduced problem is visualized in a step-by-step fashion during the tutorial, also discussing different ideas of how to get the final result, and comparing them, say, with respect to computational costs for the rendering process.
    Furthermore, I have the impression that an introduction to SVN during 15 minutes of the tutorial time will save hundreds of hours of hard labour for those who aren’t used to a version control system yet.

    • Thanks for this nice example showing how to build up a hierarchical scene graph allowing relative motion of one part with respect to another. I’m looking forward to seeing if you develop it further to include arbitrary Rubik cube motions. You’ve put together a lot of tutorial examples in this one program. I’ve edited it (and checked it in) to force the cube factory to generate face normals, so that the lighting appears brighter and more realistic.

      I’m also grateful for your observations on the process of doing the assignment. It’s important to hear what didn’t go as well as it could! I’ll try to use the next tutorial on Nov. 1 to address whatever deficits there are in regard to jReality scene graph construction, and in SVN skills. (Regarding the latter point, in the poll I made of the 34 students on the sign-up list, 21 indicated they had had experience with eclipse. Assuming that meant also experience with some source control system, I decided against spending class time going over use of SVN. In retrospect, 15 minutes would certainly have been a good investment.)

Leave a Reply