Improve Cycles standalone
Open, NormalPublic

"Like" token, awarded by up4."Like" token, awarded by GabrielS."Like" token, awarded by imsky."Like" token, awarded by PRosendahl."Like" token, awarded by monio."Like" token, awarded by erel96.
Assigned To
Authored By


I create this task here so we can talk about a design/implementation for a decent API and improvements for Cycles standalone.

Image: The Cycles standalone app
Standalone code:

Current API
At the moment we have a basic xml api, which was only intended for testing.
Examples can be found here:

I think we need an api which is easier to read/write, while still staying simple and manually editable.
We'd like to get feedback from people, who are interested in integrating Cycles into other applications.

Reasons to make this happen
I still see a great potential in the standalone, and as most code is already there, it shouldn't be too hard to make this usable.

  • Cycles would become usable for other 3D applications, and therefore we could also get more potential developers.
  • Even for Blender, it would help as benchmark and testing tool for the engine itself. We could have a automated test suite then.



Related Objects

To me there are 2 distinctly different but related things.

The API as in the c/c++ calls I have to make to get cycles to do anything

For this I would like the following

  • at least python bindings so we can test things easy / fast
  • ability to build a libcycles.dll/so/dylib

The scene description file format. This should be as close to the API as possible.

For this I would like the following:

  • ASCII/UTF-8 and binary representation that are both interchangeable and convertible both ways
  • the text variant should be somewhat understandable / hand editable

I think we can rip out the XML and replace it with a bison / flex based parser like luxrender currently has.
And add support for loading obj and ply meshes.

That all seems reasonable. I'm not sure if we need bison / flex based parser though, guess it depends on the file format. I wouldn't use a RIB like file format, it's not a great fit semantically and I don't see much point using the syntax. I'll paste what I wrote on the mailing list some time ago here:


XML and RIB syntax are well known. JSON is perhaps more readable and less verbose due to not requiring start+end elements, but also seems a bit out of place. XML would be easiest as we already have a parser from OpenImageIO, though perhaps it's not particularly hip to use XML :)

It's mostly a matter of taste I guess, maybe someone can come up with a good argument for one choice or the other.


We do not need an attribute stacks like Renderman does. That's nice if you really want to construct more complex scenes with just a text editor, but I don't think that's our target. I rather have a flat list of data with a unique ID that can reference each other, so instancing is natural and not conditional on the attribute stack state. The list of data types I imagine would be:

  • output settings
  • integrator settings
  • camera
  • geometry (mesh, curves, .. in external file)
  • object (either a geometry instance or parent object with child objects)
  • material
  • light
  • shader

We should make it so that we can have RIB like archives that we can delay loading once we support that in the core. We have to be a bit careful here in defining the semantics, so we don't just assume the whole archive is included in place.


Geometry does not need to be in the scene file format, we can reference external files in some standard format(s) instead. Alembic is quite nice for this, it supports an object hierarchy and is designed for efficient loading.

Main problem is that it is a big dependency, and we don't have Blender export here yet? Perhaps basic .obj and later alembic support is a reasonable compromise.


Shaders are node based in Cycles and OSL. You would have 3 types of shaders that all look the same from the outside, as a node with inputs and outputs:

  • Builtin node
  • OSL shader
  • Shader group

A material or light would reference such a shader and only have a few extra properties, most of its behavior is defined by the shader. A shader group is like a Blender node group and basically a more general type of shader instance as in Renderman. If we support archives this could be stored in a separate file but use the same syntax as the scene file format.

Allow me to point out an additional aspect:

One of Cycles benefits is instant feedback. Noisy, but good for quick iteration. That's what makes it interesting for some cloud use cases.

For example take a look at what Lagoa is doing ( go for "Try Lagoa" ).

So apart from the classic create scene->render->finished workflow it would be great to be able to:

  • be able to change the scene during render (like the camera position)
  • have callbacks, that inform you about the status.
  • have access to the current renderbuffers

Well, it comes down to being able to build an interactive rendered view, just like Blender has it and outsource the actual render to servers.

I know that some of those things may already exist. I created a prototype last week, that renders one of dingto's demo XMLs and saves away a JPG every 100 samples. I had troubles though since I found no documentation.

I just want to point out these use cases, so they may be considered in Cycles standalone API.


Yes, that's a good point, if we make an API it should support incremental updates. Most of it is there in the Blender integration, just needs to be wrapped a bit nicer.

Hey guys,

I'm using 3DS Max because of school and work, but I miss that badass Blender, so I'd be very pleased to provide any help for a Cycles integration with 3DS Max. I'll watch the progress of the project and maybe try a basic export to Cycles maxscript if needed.

I know Max users would love Cycles.

A Max to Cycles Standalone exporter would be possible for me, too.

At work I often use Maxscript, so adding an XML-exporter of standard materials and maybe geometry could be possible with enough time and if the standalone of Cycles gets better (more features and better documentation).

More interesting would be a real dlu-plugin to support animations and the real render pipeline in Max. :)

To push the API discussion forward.
Creating a Max-XML-Exporter for the cycles scene in general should be possible and not that difficult (but of course time consuming). But before I start coding and then it gets changed, we should make sure if we use our own XML format or use a predefined format and improve the importer of the Standalone.
The main advantage of XML would be, that its easy to parse and understand.
Like brecht wrote, the differentiation between the scene in general and the objects might be good. But for example shaders, should they then be a part of the object file or the scene file. Theoretical it would be better if they were a part of the object, but then using the same material on more then one objects would be more difficult then needed. So:
If we use our own XML-format, it should be carefully and future proofed designed and be useful for future updates and extensions.

EDIT: what about animations?

I worked on some updates the past few days:


  • Nodes are almost completely wrapped (missing are RGB Curves and Color Ramp...)
  • Lights (Point, Area, Spot, Sun) are supported now.


  • The camera is now properly refreshed, when changing the window size or passing --width --height overwrites on startup.
  • Render can be paused with "P" key.
  • Added an "Interactive Mode", which can be enabled with the "I" key.
    • Left/Right mouse can be used for Camera Move/Rotate, additionally W/A/S/D keys for camera movement.

So I think we have a pretty nice basis here now, when it comes to the GUI and XML.


  • API: Create a design proposal and implement it.

The current XML API has limitations and is not 100% complete yet. Stick to XML or use JSON is the main question still, I don't have a strong feeling here. Whatever we will decide on, we should then check on current limitations and consistency. Some things have been mentioned already in this thread.

  • Object Import: .obj or .abc (Alembic) would be nice here, I started looking into it, but not much progress yet.

Well .. this project moves. It seems quite attractive, not very complicated, and it is C++. :)

this is very exciting. I'd like to implement cycles into maya as soon as possible. But it looks as if it will take some time before we have an API. And I fear my programming skills are far away from being helpful in creating the API itself. But as soon as you have some basic code, it would be a pleasure for me to implement and test it in maya.

Very nice! Seems like --output to image file doesn't work when --background is enabled, because there is no display I'm guessing from the code in session.cpp. Am trialing using cycles standalone for a product rendering application, this option would be very useful to us. Is it possible to have a display without actually displaying it? (to only use for writing out to a file).


i have got some questions about the API. is the definition about the Format fix? because i read some time ago a post from linus torvalds which i find a pretty interesting idea that i want to share.

He used for the diving Software a XML File because he didn't like it he used the git object database format and that i find is a interesting idea. with this concept you will get all the benefits from git itself history, diff's, .... what do you think would that be a option as a format for cycles render?

it's better explained in his post: Linus Torvalds post on google+

the actual xml interface works quite well for defining materials. The main weakness atm seems to be the missing possibility to import geometry with uv mapping, the xml does not seem to support that.

A version with OBJ import would be great, I think the renderer would already be very usable once we can use proper geometry.

hi bantha,

for me the question comes up how i should integrate the cycles shader nodes into the other dcc program mesh export is simple. there i'm not sure what's the best way (Cycles Nodes or OSL).
i have made shortly just a fun work to learn a bit python so i have made a exporter (bad code and very simple) for houdini.
if you want to try: Cycles render in houdini

I'm currently improving the current blender > cycles standalone XML exporter and I hit a problem which I feel needs solving: the <connect> tag (inside the <shader> tag) currently identifies the nodes involved in the connection in a less-than-optimal way: "nodeName (SPACE character) socketName". This is problematic because node names will not be able to have spaces this way.

I'm going to change cycles_xml.cpp so as to change the format from:

<connect from="nodeName socketName" to="node2Name socket2Name">


<connect from_node="nodeName" from_socket="socketName" to_node="node2Name" to_socket="socket2Name">

Unless anyone has a better idea or is against this.

I am fine with the change, but let's wait a few days for possible further feedback.

Much cleaner. So we can also get rid of the node's socket-name conversion where spaces are eliminated (ie "is camera ray" -> "iscameraray") in xml_socket_name().

Where is the blender-cycles standalone XML exporter located at?

The blender-cycles standalone XML exporter is only capable of exporting meshes, so I'm enhancing it.

The original exporter is in intern/cycles/app/

My take on the exporter is currently here:

Very nice! Here is my shot at materials export:
Will request closing that topic, so let's continue with your exporter.

Here is a patch that adds normals and embedded files (textures) to the XML:
Maybe that task can be closed/merged.

Really nice to know that shaders are somewhat taken care of already :) I'm trying to get Cycles working on the web browser, actually, through the CrowdProcess platform.

I think it is very important to export/import materials, this will make people share stuff. Right now it is impossible to transfer materials from file->file.
People could paste simple text files to blendswap...

Step one is exporting. Textual representation comes in handy and can be recycled for XML-export. (Or the other way around ;-) ) That way we have one task for both purposes.

Step two would be importing the text back as nodes.

I'm not sure how to handle groups. It is a neat feature and must be preserved. However it is very versatile, not sure how it fits into rather "static" XML.

Hi everyone,
I have some news here. We want to switch from XML to a JSON format, which is easier to read and write in my opinion.

Are you guys ok with it? I don't want to break your work on im-/exporters, but maintaining both XML and JSON might be a bit overkill.

Hi dingto,

I would like to create a commercial render engine based on Cycles, tell me what should I "do and don't" with Apache2 License please.

Regarding data format:

Whats the ratio of actual-data vs markup-tags when using XML? XML can easily undermine itself when structuring small bits and pieces of numerical data.

JSON is probably better, or you could even use plain S-EXPRS.

XML vs S-EXPR debate:


Making a utility for converting an S-Expression layout to JSON should be extremely trivial in lisp/scheme/racket.

Can someone tell me how do I build standalone binaries so that I can run cycles using command prompt ? Cycles is great thing . Someone need to create documentation for Cycles XML api. We are integrating it in our own small 3D application.

You can find some build instructions in the standalone repository:

On the issue of changing the interchange format, have you thought about OpenGEX (Open Game Exchange)? It is opensource and was designed to exchange game scene/level data.

It does have features meant specifically for real-time games, so you may think it isn't a great fit, but there is another option. The same folks that brought us OpenGEX created a superset that can be customized for your needs. It is called OpenDDL, adn you can find out more about it here.

While I like json better than xml, I would think there are benefits to using a domain specific exchange format.

Another option might be the Pixar Universal Scene Descriptor. The idea seems to be to put everything any application might need for a scene as a list into the file, and let the application decide the pieces it needs. They are working to make this an industry standard in the same vein as OpenSubDiv and OIIO.

Edit: Put in correct links.

JSON or XML should be irrelevant, both are going to be equally easy to read or write with a decent library. I hope nobody has intentions of reinventing the wheel by writing yet another XML parser!

What's more important, in my opinion, would be the ability from Cycles to dump an entire scene/session to XML. That way, an application that wants to support standalone Cycles as well as link against Cycles directly doesn't have to implement everything twice. It can simply setup the scene as usual, and at the very end either let it render or write it out to a file. Roughly how the RenderMan API does it with RiBegin().

I'll try to start with a maya implementation of Cycles. I'll have a closer look at the way it works in the standalone. If I have questions concerning the implementation is this the correct forum to ask or should I ask elsewhere?

Hi, I'm a student who wants to contribute to Cycles standalone project for this year GSoC. I have compiled Cycles and run the examples but I'm not sure where I should go on.

I set some prerequisites as preparations.

  1. Get to know the xml API as suggested here of the required improvements is to change the exchange file format.
  2. Get to know how other mature render engine works in a production pipeline (I'm not sure where I should start for this, reading source code of RenderMan for example?)

Sergey suggested to see how it could be integrated into a production pipeline and list areas which are currently weak and should be improved, but I think I probably get some understanding about no.2 right?


Something which would be great would be a procedural API in the same vein as Renderman and Arnold, where one can dynamically load geometry to the renderer when the renderer hits a bounding box ray hit for the first time.

That way integrating things like Alembic or Cortex objects makes it a lot more straightforward and leaves the geometry out of the XML or whatever readable text format will be used. I'd like to see better integration of Cycles in Gaffer, for example (which supplies procedurals for both 3Delight and Arnold via Cortex).

One final note, can the relatively new baking system of Cycles also be exposed in standalone? Generating baked passes would make for a great lightmapper or baking high-res details to low-res models. If this is relatively trivial to implement, I would be happy to implement and supply patches back if someone could guide on where to look.


I would have to wholeheartedly agree with What of the earlier posters stated. Pixar's USD should be implemented. It is also Open source and is already has exporters for all for the High-end production Applications. It is battle tested and Pixar's Main format for going between all of their applications and renderers. After that I would say that the second Most important would be the ability to import and render Alembic Sequences. These are Opensource Battle tested solutions with clear documented API that are already supported by all of the Proven Production pipelines. if the Goal of this project is to Turn cycles standalone in to a proven application for high-end production Implementing those to will get you there the fast with the lest amount of having to meddle with the Softwares them selves as the plugins are already made and /or integrated.

Everything you need to know.

Pixar OpenSources USD

USD support could be good, maybe even as the native Cycles file format, but we'd be adding a big required dependency.

Adopting USD is not going to give us automatic integration into applications though, it only helps a bit. You still need to make your own plugin to integrate into the UI, make all the shaders, lights, render lays, AOVs and other settings available, probably still have a code path outside of USD for fast IPR, etc.

This comment was removed by James Brad Barnette (calmasacow).
This comment was removed by Mohamed Sakr (msakr).

Mohamed, please don't post random questions in here, that has nothing to do with Cycles standalone. Use the Mailing list or IRC for such questions please.

(And no, we don't have real AOVs, only the predefined passes that you probably already know).

Is there any activity on this? I know alternatives, C apis, other file formats, etc., have been discussed. I've made some small additions to the xml handling to support motion blur as well as a simple dso loader to experiment with rendering alembic caches. How can I make these available for others to play with?

Hi Bob, these sound great. You can upload patches here then we can check on the work and possibly include it.

This comment was removed by Giovanni Remigi (gremigi).

For anybody interested I successfully compiled and integrated Cycles into the Qt framework. Cycles is compiled as a dynamic library.

The project is available here:

It includes a small demo application which creates a cube with a chosen image and allows the use of the mouse to zoom into the scene or drag the cube around.
Scene and object are created programmatically to give a better example of integration.

Currently I only compiled with CPU support for easy of life. It perfectly works on Mac, Linux and also Windows using MinGW64.

Nice work, always cool to see Cycles used in different ways.

have you guys scene this?
The've got a full working version of cycles for Cinema4d

Mohamed Sakr (msakr) added a comment.EditedTue, Mar 7, 3:06 AM

I'm just following the great folks :) , Brecht, Sergey, Lukas, DingTo, Juicyfruit