Computer Science 112
The Art & Science of Computer Graphics

Spring 2016, The College of Saint Rose

Home     Syllabus     Schedule     Examples     Course Wiki

This is a very short lab exercise designed to give you some practice working with custom materials and with a new concept of creating shared models. Our goal (as a group) is to create a collection of marbles.

A Marble

Your task is to develop and submit a model of a single marble of your own design. Come up with an appropriate material (or materials) for your marble and use it to create a spherical marble with diameter 100, sitting atop (not centered at) the origin.

In addition to using a nice material for the glass of your marble, there should be some object on the inside of the marble. This is a good chance to practice your constructive solid geometry and custom object skills in preparation for the first exam.

My example marble has a purple/blue shiny and transparent material, with some little extruded lightning bolt shapes inside:

Shared Models

Beyond the practice with custom materials and objects, an important part of this exercise is to learn how to create shared models. As we progress, you will often develop models that include objects that you might want to reuse in other models. You might like to make use of the models of objects developed by others or would like to make your models of objects available to them. In this case, our goal is to be able to have a class "marble collection" in a single image. To facilate that, your marbles will be developed as shared models.

To create a shared model, you will develop your model of a specific object (or small collection of related objects) in one Python file, and then use it in another. This is essentially what Ambrosia does in its definitions of the names we've been using all along, like scene, cylinder, and Difference. Once we have separated out the definition of the details of an object (in a shared model) from the way it is used in a scene (or perhaps as a part of some other object), that shared model can then easily be reused in other contexts.

Specifically for this assignment, you will be defining your marble as a shared object in one Python file, and then using it in a scene in another. Much of the mechanism to achieve this will seem familiar, but there is some new syntax to learn. For this first shared model, you will be able to follow the template of my example very closely.

To start, download copies of my marble, defined as a shared model (JTerescoMarble.py), and the model that defines the scene in which the marble is presented (MarblePlatform.py).

First, look at JTerescoMarble.py. Almost everything in here should look familiar. The big differences are:

1. There is a line near the top:

   __all__ = ( 'JTMarble' )
   

2. There is nothing added to the scene and there is no camera.shoot() to take a picture.

If you were to run this model in the standard way:

python3 JTerescoMarble.py

you would not see any error messages, but this would also not generate any image. This makes sense, as everything is valid Python/Ambrosia code, but nothing is in the scene and no picture was taken with the camera.

The line

__all__ = ( 'JTMarble' )

is a bit less obvious. What that is telling Python is that if some other Python code tries to use the Python code in this program (a common thing for all but the simplest Python programs to do), that the only names from within this file that can be "imported" to the file that imports this file are those in this list. We'll see more about why this is a Good Thing later.

Next, look at the MarblePlatform.py file. Again, lots of things that look familiar. We're adding a few items to the scene (the idea is that in addition to the marble, there's a small platform atop a plane and some extra lighting), and then taking a picture. Excellent. The new item here is the additional import statement near the top:

from JTerescoMarble import JTMarble

This is telling Python that you would like to make use of a name JTMarble which is defined in a file JTerescoMarble. Once you've added this, when you run

python3 MarblePlatform.py

Python will find the file named JTerescoMarble.py, run it, and make available the definition of JTMarble that was in that file for you to use in the remainder of the program here in MarblePlatform.py. And the first scene.add does exactly that by adding a JTMarble to the scene!

Why is this a Good Thing?

We have already seen the benefits of developing your model with some hierarchy in mind. Looking back at the snowmen, we defined names for the sizes of the snowman's parts, then a named component for a snowman's eye, then a Group for the snowman's head, and finally a Group representing the entire snowman. Once we have that, we can place a snowman wherever we'd like, or use it pretty much in any way we'd use any other graphical object. The shared model idea takes that to a higher level: not only are we defining an object we can use later, we are defining it in its own Python file that can then be imported by anyone who wishes to make use of it.

This mechanism is easier and safer than copying and pasting the code from one model to another. Some of you have already encountered this in your models. We tend to use names like "profile" and "width" in different models. When copying and pasting code, those names might be redefined in ways you do not intend. By defining the object in a shared model, and by only including those names you really wish to make use of in the "__all__" list at the top of the shared model, the rest of the code in the shared model can use any names you wish without concern that some other part of the program might be using those same names for another purpose.

Your Tasks

As this is your first experience with shared models, this section provides a step-by-step process you can follow to create your own marble in a shared model, and use it with the provided MarblePlatform.py. Moreover, by following this process precisely, you will simplify my task of creating the class marble collection model later on.

1. Copy/rename JTerescoMarble.py to use a file name with your own name. I'll assume here that your name is Grace Hopper, but of course you should use your own name. Grace's file might be called GHopperMarble.py.
2. Inside GHopperMarble.py, change all instances of "JTMarble" to something like "GHMarble" or "GHopMarble" - anything that will be unlikely to have a name conflict with what your classmates choose.
3. In MarblePlatform.py, change the line

   from JTerescoMarble import JTMarble
   

   to use the name of your file and of your marble's Group, e.g.:

   from GHopperMarble import GHopMarble
   

   and change the line

   scene.add(JTMarble)
   

   to match your marble's name, e.g.:

   scene.add(GHopMarble)
   

4. Make sure you can still generate an image of the sample marble with the command

   python3 MarblePlatform.py
   

5. Now, replace all of the code in GHopperMarble.py with code that creates the materials, innards, and the GHopMarble group for the marble you wish to create. Even though you will be making your edits for this step in the GHopperMarble.py file, you will still be generating your model with

   python3 MarblePlatform.py
   

   each time you want to test your changes.

6. Update the comments in both files to include your name and a description of your model.
7. Submit by email and with a wiki entry, as usual.

You may submit more than one marble for inclusion in the class marble collection, but if you do, please make it clear which one you would like to be graded.

Submission

1. Email a copy of the source code for your Ambrosia model (the Python file(s), which should always be saved with a .py extension) and your best image (which should always be saved in PNG format and using a .png extension) as attachments to terescoj AT strose.edu. Please include a meaningful subject line (something like "CSC 112 Studio/Lab 5 Submission"). Make sure your name is included in a comment in your model code, and that you have comments throughout the source code to make it easier to understand.
2. Rename your best image to include your name, then upload it to the wiki. For example, if you generate an image of a fancy glass marble and your name is Grace Hopper, you might call your image "GraceHopperGlassMarble.png".
3. Add a section to your wiki page named "A Marble" that includes a link to your image and a description of your model that generated the image.

Grading

This assignment is worth 20 points, which are distributed as follows: