Personally, I would love to see documentation for the Python vtk module. Right now, the closest thing seem to be the auto-generated docs for C++ API, which leaves one guessing how method signature got mapped to Python. These docs also expose a lot of internal details about the VTK library, which is very confusing and easy to get lost in (when all I wanted was to export data in VTK format).
I think it would be great if Kitware could release a first-party VTK writer module for Python, that integrates nicely with NumPy.
Hello @vadimcn. This post was directly related to ParaView and VTK as you can see.
The VTK’s python API is usually 1-1 to C++ which makes it easy to understand. Nonetheless,
if you want to understand the API better with respect to numpy, e.t.c. feel free to check out Python - VTK documentation.
If VTK still feels cumbersome for you, pyvista is a python library built using VTK. Its purpose is basically to wrap VTK in a pythonic way so that VTK can be integrated in a more straightforward way with numpy and other python structures.
I think it would be great if Kitware could release a first-party VTK writer module for Python, that integrates nicely with NumPy.
Can you clarify this? For the VTK XML format? Legacy format? Something different? What does it mean to integrate with NumPy on the writing side? Thanks.
The vtk module’s python docs (via help) are actually pretty comprehensive. They cover the wrapped C++ methods as well as the specific python methods. Would something that brings those together with some handwritten documentation be sufficient? Some of the modules also have decent documentation:
>>> from vtk.numpy_interface import dataset_adapter
>>> help(dataset_adapter)
Well, let’s look my user experience, keeping in mind, that the task I needed to accomplish was to create a .vtk file from my Python code (for visualization in ParaView). In other words, I was probably looking for something like vtkPolyDataWriter and associated examples.
The page you mentioned is not linked to from vtk’s landing page. The page that is linked to, is pretty confusing, even for C++ documentation. How is one supposed to locate the needed class or function here? Doesn’t even have search… All information is hidden in the “menu” bar, so at first one might entirely miss it. Clicking on anything there leads to a deluge of auto-generated pages with scarcely any explanation of what any of these namespaces and classes are for…
Okay, let’s try search on docs.vtk.org… Nope, searching for terms like “write” or “writer” yields nothing useful, unless I want to read about file formats and implement it myself.
Google search is a bit more helpful, though the first page still doesn’t link me to vtkPolyDataWriter. Well, at least is mentions some third-party libraries…
I actually do remember arriving at your page after stumbling around the VTK website for a while, however, it was not at all obvious that it was related to the vtk package:
The name of the documented package is vtkmodules, not vtk, so I had assumed it was for something else (some ParaView internals?)
The top level namespace does not list any useful functions or classes. vtkPolyDataWriter should have been here, right?
And so on…
If it wasn’t for ChatGPT, I don’t think I would have located what I was looking for.
This is the automatically generated doxygen page of VTK from its C++ code. If you want to look for the documentation of a particular VTK class you can just click Classes->Class List and then search with Ctrl+F for your class.
Assuming that you did not find it, let’s continue your journey.
Let’s go to docs.vtk.org. When we search for the word writer we get information about file formats, in Supported Data Formats - VTK documentation, which is useful to find the name of the class you wanna use, but still not examples. Something that we omitted in this part is to list the VTK related readers/writers which are the ones that you needed, such as vtkPolyDataWriter.
Sure, the information may be there, but it’s hard to locate unless you already know what you are looking for.
Please consider this: exporting data in the VTK format is a per-requisite for everything else. Unless the user is able to accomplish that, the rest is irrelevant.
But what do we see at the top of the page on the Python HowTo page (where one would normally expect to find such info)? “Callback” and “Camera models”, hmm… The only section related to data writing on that page seems to be WriteImage?
On the Python Examples page, the IO section is mostly about reading foreign formats. The most relevant section to .vtk writing seems to be LegacyFormats. But why “legacy”? What are non-legacy formats?
I think a reference to the “12.2 Writers” section of the VTK User’s Guide would be helpful here. Too bad that the guide uses TCL syntax for examples…
As you’ve noticed, the Supported Data Formats page doesn’t even mention VTK’s native formats.
The Python Wrappers page is useful, but expecting Python users to mentally map C++ API to Python is a bit of a stretch, IMO.
Which brings us to Native Python documentation. As I mentioned previously, these pages look pretty sparse. Where are all the classes that exist in the vtk module? Is help() the only option for accessing Python docs?
PS: Please don’t bother answering the specific questions above, they are for illustrative purposes only; at this point I’ve already found what I was looking for. My intention in writing this was to bring it to your attention that using VTK documentation is perhaps harder than it needs to be… Thanks for reading!
Hi Vadim,
I want to assure you that your point is valid and well-received. It is valuable for experienced developers and long-time contributors to hear about a first-time experience with a project they are very familiar with. I did a similar workshop exercise for ParaView last year and discovered several things that could use improvement.
What can be very difficult is finding the time or the project that allows us to work on this sort of improvement. Documentation improvements like this can be an “easy” way for someone to make a first-time contribution to any open-source project, but the instructions need to be in place on how to do it! I will certainly keep your suggestions in mind if I have a chance to touch the docs, and I’m sure others at Kitware will too. Thanks for your feedback!
Hello aron, just to comment about Vadim post of python doc. I have found myself struggling a LOT with understanding how to ‘do python’ with the paraview data from the filters. Mathieu was super helpful and with a lot of patience helped me to go through but a clear ‘how to’ for using data of a paraview filter and process it from the paraview script. such as recover the data into numpy arrays and then work with them would be great. I know that there is the fetch function, but where exactly to fetch what you are looking for and even after, recover the values instead of a vtk array. I am for sure not good at programing, but generally I have successfully achieved what I was looking for (even if not in a clean way) but achieved and understood what I was doing. in the case of fetch with paraview and python even at the end that I did what I was looking to do, I still felt like yeah next time is another data different from what I am looking for, and I will not be sure where to look for it or even after getting it to access the values themselves.
I understand that it is a lot of work guys and we are ‘asking more’, but believe me I have came across several people from kitware and I am always saying how great paraview is. it is a simple constructive criticism I am trying to say with this message.