VTK Examples - Updated Physically Based Rendering (PBR) examples

The PBR examples have been extensively re-worked and will be much easier to use, the major changes are:

  1. Sliders to manipulate the various parameters are now provided in the left-hand viewport.
  2. A major change is the moving of most of the command line parameters into a JSON file. The format of this file is documented here: PBR_JSON_format.

The great advantage of a JSON file is that it is easy to edit so users can add their own textures, equirectangular files or cubemaps. The JSON file and any associated folders containing the files are easily relocated.

So, at their simplest, these examples just need the location of the JSON file.

For the C++ examples, we need VTK to be built with these modules vtk::cli11 and vtk::json. Additionally C++17 is needed since std::filesystem is used to validate files and for some path manipulation - you can comment out this code or use boost filesystem.

The Python examples just use the standard Python imports argparse, json and pathlib, so the VTK third party modules are not needed.

The C++ examples are here:




Of course there are corresponding Python examples.


To me it seems that the Python examples have slightly better saturation.

The big difference relates to the Python version PBR_Skybox_Anisotropy:

As far as I know the code is similar to the C++ example.


Awesome work @amaclean !

You can open issues if you find strange behaviors.

FYI @Timothee_Chabat

Thanks @mwestphal, using a JSON file has made such a difference!

The link does not appear to be valid. Could you please send the correct link?

It would be nice to use a standard json PBR material description format (or something as close as possible to a standard), for example glTF:

    "pbrMetallicRoughness": {
    "baseColorFactor": [
    "metallicFactor": 0.0,
    "roughnessFactor": 1.0

That format could be then used in other places in VTK and in other VTK-based applications.

1 Like

Aren’t material json based in OSPRay @Dave_DeMarle @Timothee_Chabat ?

The link to the PBR is broken for me too unfortunately so I don’t know if that is related to the JSON material infrastructure in VTK/Rendering/RayTracing.

That one is just the way I came up with back in the day for VTK to drive OSPRay’s API for specifying materials. It has since been extended to cover PBR, drive OptiX via MDL internally, and also optionally with input coming from the ancient .obj/.mtl file format instead of json.

That parser is VTK not OSPRay.

It could be promoted out of the RayTracing module. That would probably help bring VTK’s user interface to PBR materials in the GL and RayTraced backends closer together which would be a good thing.

However, I am with @andras and would rather see VTK’s json material interface(s?) deprecated and replaced with something that is both open and widely adopted. glTF seems to be the leading contender today.


Thanks everybody for your input. The link is working now: PBR_JSON_format. The cat at that point had decided that it was dinner time and wanted pre-dinner treats so she took over the editing and typing! I will have words with her.

My objective here was to have a simple easily edited file that can be readily parsed by both C++ and Python. It looks to be pretty close to glTF. If you look at the sample file at the bottom of the link you will see that is consists mainly of file paths. Everything is text with the exception of the boolean value for skybox. I kept colours as names so that a new user can easily select from pre-defined palettes. I have been restrictive in that only a small set of keys are accepted and file paths are strictly checked. This is to make it easy on the user.

As you can imagine, the old versions were quite cumbersome with a very long command line (generally more than 400 characters) specifying at least five files and possibly an object.

Here, the user can easily edit the JSON file changing colours, switching off the skybox, adding new files etc. For example it is now very simple to switch to the six cube map files instead of the equirectangular file (-c) on the command line.

1 Like

@mwestphal, @Timothee_Chabat I’ll do some further checks over the next day or so. It looks as if Paraview is correct when I look at the HDR file. My generated equirectangular file from the six skyboxes is flipped when compared with the original skybox files. So it may be something in that process.

Your new file format scratches an itch that many VTK users have - the lack of a simple scene file format for VTK. There are a number of exporters for other scene file formats (glTF, x3d, vrml, renderman, etc.), there is even a vtkJSONSceneExporter that could be quite close to what you have defined. However, there are only a few importers (glTF, 3ds, vrml) which are too complex and/or quite old.

I’m wondering where adding this new file format will lead us. It would be so tempting to add some more features (definition of camera parameters, lights, SSAO, support for multiple objects, object position/orientation, etc.) because it would be so easy and would result in huge improvements in capabilities and rendering quality. Should we resist and keep only the current capabilities? Or should we give in and finally have a simple VTK scene file format?

All fixed! I had flipped the generated equirectangular skyboxes for some reason. I was probably having trouble with reflectiions on the surface in an earlier version. I have also updted the above images.

Your new file format scratches an itch that many VTK users have - the lack of a simple scene file format for VTK.

It would be interesting to know what other people think. I must admit it was very difficult to keep it simple!

There are 2 reasons why I’m against the idea of creating yet another scene file format. First VTK does not have a scene graph so a “scene” is not a core part of VTK : creating a new VTK specific file format for something that is not core sounds bad to me.

Second there are aready plenty of very good scene file format. I’d prefer to improve existing support for common scene file format such as glTF or USD. If we see that we need to store some custom variables then we could always design an extension for these file formats and support it in the importers / exporters.

But this is a bit off topic though :slightly_smiling_face: if needed then we can create a new topic

I definitely aggree with @Timothee_Chabat here.

This pbr json format is nice but specific to examples for now, not something supported in VTK. Adding this to VTK in any shape or form will require much more discussion and thoughts.

It seems that VTK developers would not like to introduce yet another scene file format (and I fully agree that it is a much better investment of time to improve support of existing standard scene file formats).

This means that @amaclean you need to resist the temptation to add more feature to this new file format (to avoid making users depend on it) and make sure users understand that it is just to be used inside some VTK tests. You could add a warning in the file format description and direct people to use standard scene file formats instead (or maybe remove the file format description page from the public documentation to make it clear that it is not some officially supported VTK file format).

Just a reminder, Andrew is doing this on his own time just for fun and making a huge impact over the years (including things like the textbook and vtk examples) :-). I am loath to say “no” to anybody who may have an interest in improving VTK. On the other hand I agree that there are other file formats that could be improved (e.g., I keep tripping across X3D in interactions with my customers). So as a community I’d generally prefer ways to find fun and creative ways to redirect coding passion into a positive path forward. Fortunately people in the VTK community are amazingly cooperative and want to do the right thing. It is clear that there is a need to somehow capture VTK state, (I’ve generally resorted to Python scripts for this) - I’m wondering whether with a little head scratching we can clearly define an actionable path forward and then assemble a skunkworks project to get it done.


Thank you for your insight @will.schroeder. I fully agree with you. Probably I’m just worried that users will be mislead by seeing the new file format specification on an official VTK site and will think that this is some new VTK feature.

Implementing this new scene file format and corresponding parser and viewer in a separate repository (not in an official VTK repository) would avoid the confusion and it would also have the advantage that it could be more conveniently available for users. Users would not need to download or copy-paste code from VTK examples site and then build but there could be precompiled binary distributions and could be also made available on PyPI. Also, there would be more space to grow in a separate repository, it would be easier to gather a small community around this tool.

This could be yet another example of a VTK remote module, because it would not be a VTK core feature (no commitment from VTK core developers for design, implementation, maintenance, and support), but it could become much more than just a rendering example.

1 Like

Don’t say the word “remote module” in front of Ben!!! I feel a looong thread coming on…


I must emphasise that the JSON file was developed specifically to handle the large number of files needed in the PBR examples. There is no intent to add this format as a VTK standard.

The examples enhance and build on what VTK offers, it is their role to showcase VTK and provide examples/insipration for users. It is my hope that users don´t feel constrained by the examples, they should take the code and enhance it for their own purposes.

I considered other formats e.g TOML. Whilst mostly supported by CLI11 “tomllib” is new in Python 3.11. At least JSON is supported in VTK and Python and Java. feel free to create your own version using TOML if it is more convenient.