Fix pyvista doc export

[jourdain]

No description provided.

[jourdain]

@user27182 that would be the one to test.

[user27182]

Tested against 8174b4c with build outputs here https://github.com/pyvista/pyvista/actions/runs/30313669088
looks like Kitware/trame#900 is almost 100% resolved, except this one case for ExplicitStructuredGrid:

[jourdain]

I've tested it locally and it is not related to the trame side of thing but the vtk version instead.
Anything VTK 9.6.* is fine but 9.7rc3 fails...

grid-9.6.20260517.html
grid-9.7.html

[user27182]

Hmm... if it was a vtk issue I would have expected two test failures, with both the static render and interactive render failing. But only the vtksz screenshot is in the failure report...

[jourdain]

Right, the rendering using vtk C++ is indeed correct... The export seems to have messed up the order of the scalar arrays...

EDIT: not an ordering issue, just 64 decoded as 32 bits.

[jourdain]

Difference output is that with 9.6 the generated array is BigUint64Array while in 9.7 we get Uint32Array with most likely the wrong conversion.

[jourdain]

9.6 report VTK_UNSIGNED_LONG_LONG for the scalar type while 9.7 report VTK_UNSIGNED_LONG which generate a 32/64 bit mismatch.

[jourdain]

Test code...

import pyvista as pv
from pyvista import examples

pl = pv.Plotter()

grid = examples.load_explicit_structured()
grid = grid.compute_connections()

pl.add_mesh(grid, show_edges=True)
pl.trame.export_vtksz("grid.vtksz")
pl.trame.export_html("grid.html")

[jourdain]

@user27182 we should be all good now. (9.7 and older version)

[user27182]

Thanks, I built docs again with the updates. I also updated the baselines based on the previous commit.

Here's the new report.
https://6a68d63645a5138d2ed72e0f--pyvista-doctest-images.netlify.app

Everything looks good, except you'll notice the add_mesh vtksz images are blank. This is fine, because they were blank with VTK 9.6.2. But, they were temporarily working with the previous commit ( see #123 (comment)), so that version of the branch actually fixed the issue, where these were blank in 9.6.2, but were working (so I added them to the baselines), but now with the latest push they're broken again.

So, this fix as-is is fine with no regressions for 9.6 -> 9.7. But, maybe you want to see if you can keep the fix that was there? Can also raise it as a separate issue if you prefer and keep this as-is.

This is the specific example that I'm talking about:

# Plot using RGB on a single cell.  Note that since the number of
# points and the number of cells are identical, we have to pass
# `preference='cell'`.
import pyvista as pv
import numpy as np
vertices = np.array(
    [
        [0, 0, 0],
        [1, 0, 0],
        [0.5, 0.667, 0],
        [0.5, 0.33, 0.667],
    ]
)
faces = np.hstack([[3, 0, 1, 2], [3, 0, 3, 2], [3, 0, 1, 3], [3, 1, 2, 3]])
mesh = pv.PolyData(vertices, faces)
mesh.cell_data['colors'] = [
    [255, 255, 255],
    [0, 255, 0],
    [0, 0, 255],
    [255, 0, 0],
]
pl = pv.Plotter()
_ = pl.add_mesh(
    mesh,
    scalars='colors',
    lighting=False,
    rgb=True,
    preference='cell',
)
pl.camera_position = 'xy'
pl.show()

[jourdain]

Thanks for the pointer, so the last commit ensure that any (u)int64 get converted to 32 bits so it can properly be managed by JS without weird type that don't behave like a standard typed array.

[user27182]

Great. I'll push another commit and check the output again. LGTM here otherwise. Though I wonder if there should be regression tests for these...? Or maybe there already are elsewhere. Seems pretty finicky to get all the dtype conversions right.

On our end a full PyVista docs build is really one of the best regression tests we have. But this test doesn't run with trame-pyvista. So without tests trame-vtk and trame-pyvista will both be blind.

[jourdain]

Well before we were allowing some arrays to stay in (u)int64 which works in some cases (very little) on the JS side.
Here we normalize everything to 32 bits for (u)int. There is a risk of overflow, but at the same time vtk.js will also fail related to the size of the mesh at that point to...

The finicky part is about the strategy, not the conversion per say. Before we were trying to be as true as possible to the original data, while now we prefer compatibility for the client side.

The last thing is that before we were using the reported type from VTK (UNSIGNED_LONG, UNSIGNED_LONG_LONG, ...) to figure out the actual data representation. The problem is that *_LONG has a different meaning across platforms (32/64). By using the numpy dtype, we now have an homogeneous meaning across platform.

[jourdain]

For context, on mac, VTK_UNSIGNED_LONG and VTK_UNSIGNED_LONG_LONG are both 64 bits. In my mapping I was assuming VTK_UNSIGNED_LONG to be 32 bits. Which is true on Windows but not on Mac/Linux.

[jourdain]

Also I'm not expecting trame-vtk to evolve much. It will be replaced by trame-vtklocal (vtk-wasm / local rendering) and trame-rca (remote rendering).

I'm in the process to add wasm support for PyVista which should fix all the issue reported and linked to vtk.js limitation...

[user27182]

Okay. Sounds like things are (mostly) sorted then? Indeed the various C/C++ types, NumPy types, and variations across OS is all pretty confusing.

Seems like this is more of a compatibility shim then, and limited testing is fine. Thanks for all the investigating! LGTM