Sunflow & Processing

Posted by Amnon on September 28, 2010 · 47 Comments 

I’ve been using the java-based global illumination renderer Sunflow together with Processing for quite some time now. The first ever video I made with Processing (only 10 months ago!) was actually one that employed Sunflow through the P5Sunflow library. Two months ago I went a little further to create a short motion graphics experiment for the 5 second project. All my Sunflow projects until that time worked through the P5Sunflow library. The main advantage of this library is that it automatically ‘translates’ a sketch. This means you don’t have to make any changes to your original sketch, except change the renderer. This is ideal. Unfortunately however, this library was never fully developed. So although it supports geometry, it does not allow for more advanced Sunflow functionalities such as shaders, lighting and Sunflow’s built-in primitives.

SunflowP5 alternatives
For the last few months I’ve been looking at different alternatives to bring full Sunflow functionality to Processing. I checked out some of the P5Sunflow clones like Sunflow4P5. See the discussion in this thread on the old forum. Didn’t work out at all. I then downloaded Sunflow itself and examined the possibility of exporting geometry from Processing, which is subsequently rendered in “the real” Sunflow. This is possible. You can export stuff from Processing as regular 3D models or try to export it in a Sunflow-ready format. Many 3D applications already have plugins to export to Sunflow format and it’s a relatively simple format. Interestingly enough, a very recent attempt to bridge the gap between Processing and Sunflow seems to focus on this technique. Like a hybrid between full translation and using the Sunflow .sc format or something. See this thread in the new forum for more details about this library-in-development called JoonsRenderer. Looks really interesting, although I haven’t tried it yet. It wasn’t around at the time I started my search. Getting back to the story, my attempt to export geometry and then manually render in Sunflow, worked. But it was very time-intensive and for my end goal (animation) not a viable solution at all. So I decided to look into different alternatives.

SunflowAPIAPI
I then found a java-wrapper called SunflowAPIAPI, created by Christopher Warnow back in 2008. It functions like an easier-to-use API for Sunflow’s functionalities. After some figuring out, I got it to work directly from within Processing. I’ve been spending some time (between vacations, my day job and other personal projects!) on learning this wrapper and the possibilities of Sunflow in general. The three big advantages of using SunflowAPIAPI are that it allows for (a) full Sunflow functionality (b) directly from within Processing and (c) can be tweaked at will; as the code is directly accessible from Processing’s IDE. The big disadvantage, especially compared to SunflowP5, is that it requires special syntax. So it will not translate existing sketch code automatically. Instead it requires some manual translation. How much work this will be, depends on the sketch. The syntax itself is not difficult. In fact it’s fairly straight-forward, as it completely mirrors the terminology used in Sunflow. So it all makes sense, but you gotta consider the translation-issue beforehand If you’re aiming for an efficient workflow.

Workflow alternatives
I’ve found two main workflow options. Either work fully in SunflowAPIAPI-ready code and render to Sunflow in preview mode. The advantage of this method is that it’s 1:1. You write it, you see it etcetera. The disadvantage is, that Sunflow is SLOW even for low-resolution, low-quality preview renders. The second method is to program your sketch in OPENGL and have a ‘mirror copy’ of all your code for the SunflowAPIAPI. The advantage is that OPENGL works in real-time. Then at the press of a button you could start rendering to Sunflow. The disadvantage is that all your code is basically doubled and you have to sync geometry, camera’s etcetera. I’ve used both methods. It really depends on your needs and the complexity of the scene, which one you’d wanna use.

How to install SunflowAPIAPI
For people interested in using this API, let me elaborate on the steps you need to make it work.

1. Create a new empty sketch.
2. Compile a version of Sunflow or download the latest version 0.073 here.
3. Copy this file “sunflow-and-janino.jar” into the “/code” subdirectory of your sketch.
4. Go to the Google repository for SunflowAPIAPI.
5. Checkout the code via a Subversion client or directly download the files via browse.
6. The main file you will need is “SunflowAPIAPI.java”. Copy this file into the main sketch directory (besides your “sketchname.pde”).
7. Now when you code your sketch – using the correct syntax – it should render using Sunflow. A basic code example is provided below.

How to use SunflowAPIAPI (code example)
Once you have followed all of the above steps, all that remains is the content of the sketch. The examples provided with the API are useful, but you have to make some small changes for them to work in Processing. Here is an example for learning purposes, which only has the extremely bare essentials needed to make a simple test render. Code example:

import java.awt.Color;
import com.briansteen.SunflowAPIAPI;

int sceneWidth = 500;
int sceneHeight = 500;

void setup() {
 SunflowAPIAPI sunflow = new SunflowAPIAPI();
 sunflow.setWidth(sceneWidth);
 sunflow.setHeight(sceneHeight);
 sunflow.setCameraPosition(0,2.5,-5);
 sunflow.setCameraTarget(0,0,0);
 sunflow.setThinlensCamera("thinLensCamera", 50f, (float)sceneWidth/sceneHeight);
 sunflow.drawPlane("ground", new Point3(0,-3.5,0), new Vector3(0,1,0));
 sunflow.drawSphereFlake("mySphereFlake", 20, new Vector3(0,1,0), 1);
 sunflow.setPathTracingGIEngine(64);
 sunflow.render(sketchPath + "/SunflowTestRender.png");
 exit();
}

The above code snippet should, if all goes well, result in something like the image below…

Trying out different Sunflow functionalities
All right, so like I said before, this API basically gives you full Sunflow functionality. Christopher’s been adding some of the last remaining functions lately. And I’m also a project committer myself now (yay! :cool:), so in the latest revision I added one little thing, the sphereFlake (as shown in the above code example). I’ve been playing with shaders, lighting options and some of Sunflow’s built-in primitives, like Hair and the JuliaFractal. The former is quite useful, the latter less interesting than it might seem at first sight. I’m of course grateful to Christopher for helping me out along the way and for developing the wrapper to begin with! Perhaps now that I’ve learned how to use it, it will be easier to apply it to actual projects. I’ll definitely be committing interesting and/or useful code additions, if I have any, into the repository. A video which mashes up two of my preliminary test render sessions can be found on Vimeo here.

Connecting Toxiclibs & HEMesh with Sunflow
Once I knew the API could run from inside Processing, I started working on connections with other libraries. So far I’ve successfully come up with methods to get stuff from Toxiclibs into Sunflow, from HEMesh into Sunflow and from external 3D model files into Sunflow. All of them go through Sunflow’s triangleMesh shape. This shape, as the name suggests, is made out of vertices and triangulated faces. Since most 3D shapes are already in  – or can be translated into – this format, it becomes relatively easy to get complex geometry from Processing (libraries) into Sunflow.

Tips & Tricks
Please benefit from some of the lessons I learned the hard way 😆

– The regular render option does not allow saving in Processing. You have to render to a file directly. Of course it’s possible to immediately afterwards load and draw the rendered image in Processing. But you could just as easily go to the output directory to see the rendered result. Depends on your needs.

– The way the API works is somewhat different from regular draw cycles. The API creates a 3D scene, which stays in memory! When nothing changes except for example camera movement, you could use this. Only create the scene once and subsequently just change the camera’s position. If however you have moving/changing objects you will need to re-create them. Initially I did this by removing objects/shaders and then creating them again. Since not removing them results in errors because the names are already in use. This is however not the most efficient way to do it. A better way is to re-create the full Sunflow object on every draw cycle. The old scene goes into the garbage collector. And you don’t have to worry about removing stuff or names already in use. Of course this makes rendering animations much more convenient.

– Syncing the camera between OPENGL en Sunflow is a challenge, which I’ve only figured out partially. I’m using the peasyCam library by the way. Getting the camera position and lookAt points is easy, because they are 1:1 related between renderers. The only thing to consider is the reverse Y due to OPENGL’s coordinate system. PeasyCam’s getPosition and getLookAt functions can be used to get the relevant coordinates, which can be directly inserted into Sunflow’s setCameraPosition and setCameraTarget functions. The problem is that this is not the full transformation, but only two-thirds. I’m guessing the third parameter is the camera’s rotation, probably around it’s own center point. Like I said, haven’t fully figured this one out yet, so suggestions are welcome… 🙂

Future developments
As with all my experiments, the learning process is more important than the final result. And I must say I’ve learned a great many things again. Sunflow stuff like lighting, shading and cool camera tricks. But also coding stuff like how to using the original Sunflow’s source code to your advantage and using subversion to keep track of code revisions. And I finally overcame my long-held reservations to working with advanced libraries like Toxiclibs and HEMesh, only to find out that they’re not as scary as they look from the outside, haha 🙂 Another step forward, but just a first step really. This is only the beginning. I hope to push all of this further. Been reading about fractal geometry, which poses interesting challenges and possibilities. Also I’ve barely scratched the surface of the mentioned libraries so my intention is to dive into those much more and see what comes out at the other end. That’s it for now! See you around and please feel free to share any comments below! 😀

Links related to this post:

1. Vimeo Video
2. Flickr Set

Filed under Experiments · Tagged with 3d, animation, black and white, creative coding, example, fractals, global illumination, HEMesh, p5sunflow, processing.org, source code, sunflow, toxiclibs