[Note: Go here for Assignment 2.] In this post I want to collect some miscellaneous tips and tricks related to the nitty-gritty of our programming environment for this course.  Please feel free to post other related helpful hints as comments to this post! I’ll be adding entries throughout the semester so it might be good to bookmark this page. I’ll add new entries at the top.

1. Animating a scene graph.  For best results, re-use SceneGraphComponents and geometry factories.  For example, if only the geometry is animated, you can simply call the factory.set…() methods you need, then call update().  The geometry will be changed and the scene graph re-rendered without further work.
2. html on-line documentation: Please try to reduce the size of your html folders in the SVN repository.  Large files make the update process with SVN slow and unreliable.  Please try to keep the total under 1MByte per team.
3. Using the computers in MA 316: Our first Thursday in this lab, it was difficult to login successfully to these machines.  I’ve found out the problem. To use these computers, you have to select a session type on the pull-down menu below the login field. KD3 or Gnome are common choices, if you don’t already have a favorite (apparently KD4 is not available, which is the source of the problem); if you’re just going to be running eclipse, it shouldn’t matter much which you choose as long as you can get a shell/terminal.  FYI, here are the directions again  for getting the correct eclipse version on these machines.  Execute in a shell:
   1. ln -s /net/MathVis/eclipse64-subversive/eclipse eclipse
   2. ./eclipse
4. If your Java process runs out of heap space:   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.
   1. You can set this just for this application in Eclipse using the menu item Run configurations…->Arguments->VM arguments.
   2. Set it globally for all Java VM’s in eclipse using Eclipse->Preferences…->Java->Installed JRE’s->Edit->Default VM Arguments.
5. Update SVN frequently: Make a habit of updating from the SVN repository after you start up eclipse.  Some files your application depends on may have changed; I try to avoid such changes but sometimes it can’t be helped, and it’s better to adjust to the changes sooner rather than later.
6. Use the utility class de.jreality.geom.Rn: If you are doing calculations involving points in $E^3$ or vectors in $R^3$, consider using the static methods Rn. It’s not possible to give an exhaustive listing here of these methods, but these include adding, subtracting, cross product, multiplying by a scale, normalizing, finding the norm, distance and angles,  etc.  Many methods also act on arrays of points or vectors (type double[][]). Take a look for yourself. When using homogeneous coordinates or doing projective geometry, consult Pn, in the same package.
7. When in doubt, consult the tutorial examples: Just because you’re writing your own programs now doesn’t mean you can’t benefit from looking back at the tutorial examples.  In fact, now that you know more what’s going in, it’s probable that you will be more appreciative of some features which previously, in the initial confusion, you didn’t fully understand.  Once more, the principle at work here is: avoid writing your own code wherever possible.  It gives you more time and energy to … write your own code.

Please excuse the delay in getting Assignment 2 on-line.  On Friday I looked over the results of Assignment 1.  Ten  teams have checked in their work.  There is a pleasing variety in the results; there is a range of subject matter, and a range of difficulty.  Some of the applications are impressive!  It’s clear that there is a wide range of experience levels in Java programming, and familiarity with 3D graphics.  For this reason I’ve decided to postpone moving on the Assignment 2 this week.  I’m renaming it as Assignment 3 and have prepared a different Assignment 2 for this week.  We’ll get back to  Assignment 3 as soon as we’ve worked through the new Assignment 2, which I now want to describe.

Assignment 2 is a continuation of Assignment 1.  I’ve created a new class named simply Assignment and checked it in in the package named util.   Your Assignment2 class should be a sub-class of Assignment, which has a number of methods to make your applications more useful and convenient.  The extensions center around three main features:

• flexible setup of JRViewer,
• support for creating inspection panels (to control the parameters of your class), and
• use of web browser to display on-line documentation.

Consult the class gunn.Assignment2 to see how I adapted gunn.Assignment1 to use these features.  Study in particular how gunn.Assignment2 overrides the following methods from Assignment.  (Note: the safest way to implement these methods in eclipseis via the menu item “Source->Override/Implement Methods”.)

• getContent():  this SceneGraphComponent is used as the content of the JRViewer. You must implement this method, as it is declared abstract in Assignment.
• getDocumentationFile(): This String gives the name of the file containing the on-line documentation for the class.  I’ve generated html files and put them in the subpackage gunn.html. In the case the String is “html/Assignment2.html”.
• getInspector(): This java.awt.Component contains GUI to interact with the parameters which behavior of this class.  If you don’t override this method, you’ll get a default inspector based on Java beans technology; if you don’t want any inspector, overwrite getInspector() and return null explicitly.
• display(): This method activates the assignment, invokes an instance of JRViewer (which you can customize by overriding the method setupJRViewer()), registers the inspector panel, and sets up the keystroke shortcut ‘h’ to activate the display of the on-line documentation.  My Assignment2 invokes this method in its main() method.

Summing up, here’s the next assignment follows.

Assignment 2

1. Re-write Assignment1 to be a subclass of util.Assignment (name the result Assignment2, leaving Assignment1 unchanged).
2. For those whose original assignment consisted of one shape or one surface: extend the mathematical content so that it depends on a real parameter in a non-trivial way. For example, implement a family of polyhedra or a family of surfaces.  This is a prerequisite [Voraussetzung] for the next point:
3. Implement the inherited method getInspector() to include at least one slider.  Use the value of this slider to control a movement in the content of your class.  For example, the angle of a rotation or length of a translation.  More interesting of course are movements which change the geometry you are displaying.  You can, for example, use this value to control the truncation of the vertices of a polyhedron; to move among a family of surfaces (such from a catenoid to a helicoid); or to control any of the appearance parameters in your program — the possibilities are only limited by your imagination.  I encourage you to include other controls (non-sliders) for other types of parameters (integer, boolean, Color …).  As usual, consult gunn.Assignment2.
4. Generate on-line documentation, preferably a html file located in a sub-package of your package named html. In this documentation file.  Of course, you can write in German if you wish!The file should contain, in whichever language you write, the following:
   1. Give a description of the mathematical content of your class, focusing on the features which you have implemented.
   2. Then, give a description of how to use your application.  A screenshot of the running application can be a big help here.
   3. Finally, conclude with a brief description directions of further work, if you were to work on it further.  You can also use this section to describe any difficulties you encountered in implementing your ideas.
5. Steal this program! I encourage you to follow the example contained in gunn.Assigmnent2 as much as possible. Copy and paste from gunn.Assignment2 as much as you wish; every minute you save at this level is a minute you can use to customize the result according to your own wishes.  The same goes for the html documentation file.

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

Assignment: 

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.