test: Add StandardShaderBall test scene and common models directory

[jmp-22]

Description

Closes issue #1976

Adds a render-shaderball testsuite entry that renders the USD Working Group's StandardShaderBall asset in testrender, and introduces testsuite/common/models/ as a home for geometry that more than one test can share.

The shader ball is a widely used reference scene for evaluating material response (reflection, transmission, roughness, Fresnel, caustics, subsurface) so having it in the testsuite provides a somewhat realistic comparison against other renderers.

The USD Working Group asset ships as USD with MaterialX shading networks. testrender only reads Wavefront OBJ, so the scene was imported into Blender and re-exported as OBJ + MTL. testrender already reads object names and material names out of the .obj/.mtl, which makes it straightforward to rebind the material assignments to OSL shader groups in the scene .xml description. All 12 material names map 1:1 onto shader groups in scene.xml.

Assisted-by: Claude Code / Claude Opus 5

Used Claude Code to draft the two attribution READMEs and the notices embedded in the OBJ/MTL files.
I verified the licensing facts against the upstream repository and edited the modification statement to correctly describe my changes to the model.

testrender vs USD reference

Reference images were rendered in Houdini's Karma renderer unless otherwise noted. Images shown here have been converted from EXR to PNG.

Basic test scene

testrender	Reference

Shader ball with correct UVs

testrender	Reference (from USDView)

Shader ball with subsurface geometry

testrender	Reference

Other testrender outputs

Shader ball with various materials

Plastic	Metal

Scene render passes

Normal	UV

Added

New test: testsuite/render-shaderball — 160x120, -aa 8, using the same set of comparison settings as render-uv and render-microfacet, with failthresh=0.01 and allowfailures=3.

Shared model directory: testsuite/common/models/. testsuite/common is already copied into the build tree at configure time by src/cmake/testing.cmake, so tests reference models the same way they already reference
../common/textures/.... render-bunny's bunny.obj moves here too.

Shaders: the ball itself uses a plain grey glossy (diffuse + GGX dielectric layer), with diffuse_textured on the enclosing box walls and emitter on the area-light geometry. matte, emitter, glossy and metal follow the existing
per-test-directory convention and are unchanged copies of what other render-* tests already carry.

glass.osl, metal.osl and plastic.osl are included but not instantiated in scene.xml. I used these to produce the preview renders above, and chose to include them in the render-shaderball test directory as a useful starting points for follow-up tests or experimentation. I'm happy to exclude them if reviewers would rather the directory only carry what the test uses.

Licensing

I'm not very experienced with asset licensing, so flagging a few things for review. I used Claude Opus 5 to help generate attribution information.

The USD shaderball scene assets is licensed CC BY 4.0, which differs from OSL's BSD-3-Clause. See the USD Working Group's LICENCE for the scene.

To ensure attribution, I added:

• testsuite/common/models/shaderball/README.md: Carries the full attribution to authors (Chris Rydalch, André Mazzone, Thomas Anagnostou), the license and its URL, a link to the upstream LICENCE, and a description of the modifications made.
• testsuite/render-shaderball/maps/README.md: Records that the textures are redistributed unmodified.
• A notice embedded as comments at the top of shaderball.obj and shaderball.mtl, so attribution travels with the files if they're ever copied out of the repo.

CC BY 4.0 imposes no share-alike obligation, so nothing here affects the licensing of OSL's own code. I've left the OSL repo's THIRD-PARTY.md alone for now, but I'm happy to add an entry there if maintainers would prefer THIRD-PARTY.md to list it.

The only change to the modeled geometry is the addition of light-emitting planes in place of the upstream USD area lights, which have no OBJ representation and which testrender couldn't use anyway. This is all documented in the asset README.

Repository Size

The assets add ~7.2 MB: ~6.0 MB of textures, ~1.2 MB of geometry, and a 28 KB reference image. One texture map, ground.ACEScg.exr, alone is 4.2 MB.

The textures are the USD WG files as-published. If this size increase is deemed to be too large for the repo, we could apply compression on the ground texture or remove the three emitter_* maps and uvgrid.exr (which currently only exist for the previews).

Testing

Both tests pass on the CI-OSL reference image aswf/ci-osl:latest:

$ ctest --test-dir build -R 'render-(bunny|shaderball)'
    Start 584: render-bunny.opt
1/2 Test #584: render-bunny.opt .................   Passed    4.14 sec
    Start 604: render-shaderball.opt
2/2 Test #604: render-shaderball.opt ............   Passed   15.13 sec

100% tests passed, 0 tests failed out of 2

Note that render-bunny needed re-verifying, since its model moved to testsuite/common/models.

Known limitations and follow-ups for review

• CPU only. There's no OPTIX marker file, so this doesn't currently run under OptiX. I don't have an OPTIX-capable GPU to validate against. Glad to add the marker file if someone with a GPU or CI can confirm it matches, or to leave it as a follow-up. Other platforms may need an alternate reference, as render-microfacet does for Mac ARM.
• Camera position/angle in testrender is difficult to translate exactly from the USD scene. The angle used here is not 100% accurate to the USD camera, but produces a fairly similar image.
• The ball uses a placeholder grey shader. Adding the glass and metal variants as their own tests seems like it would be the next step?

Checklist:

• I have read the guidelines on contributions and code review procedures.
• I have read the Policy on AI Coding Assistants
  and if I used AI coding assistants, I have an Assisted-by: TOOL / MODEL
  line in the pull request description above.
• I have updated the documentation if my PR adds features or changes
  behavior.
• I am sure that this PR's changes are tested in the testsuite.
• I have run and passed the testsuite in CI before submitting the
  PR, by pushing the changes to my fork and seeing that the automated CI
  passed there. (Exceptions: If most tests pass and you can't figure out why
  the remaining ones fail, it's ok to submit the PR and ask for help. Or if
  any failures seem entirely unrelated to your change; sometimes things break
  on the GitHub runners.)
• My code follows the prevailing code style of this project and I
  fixed any problems reported by the clang-format CI test.

[lgritz]

Hi, just as an aside, your PR description contains this text:

> Closes issue #1976

I think the use of a > to make it a quoted paragraph and the nonstandard phrasing "Closes issue" -- or possibly either of those in isolation -- causes this PR to merely be referenced in the original issue. But if instead you had written it with the "magic words"

Closes #1976

Then GitHub would fully understand not just the link, but also that this PR, upon acceptance, should cause automatic closure of the original issue. I think "Fixes #xyzw" also works. But many other phrasings that humans would understand perfectly well, are nonetheless not recognized as being equivalent and will not cause the issue to be closed when this is merged.

I think that if you edit the description to say it correctly, it still might establish the link?

[lgritz]

The OSL project uses 2 standard licenses: BSD-3-Clause for code, and CC-BY-4.0 for docs and other non-code things. We mention this and link to the CC pages in the main README.md of this project. So you aren't adding any new or different kinds of licenses here, and I think you can just minimally note that the original data the shaderball file is derived from was also CC-BY-4.0 and give a link to the usd-wg repo where it lives.

[lgritz]

This is great! (And I'm especially happy to see this land clean, well organized, and fully passing CI on the first shot.)

I have a feeling that we will use the shaderball for many more tests over time, so I wonder if, just like the shaderball geometry, the shaderball textures should be moved to testsuite/common/textures/shaderball?

It seems that the render-shaderball test still contains a lot of .osl files that aren't used by the test. Presumably those were used to generate the examples you posted above in this PR. But probably the final form of this PR should remove the ones that we don't intend to directly use.

Really, those two items are about all I can think of suggesting... this is everything I'd hoped for.

I do have another question, which may be more revealing of my unfamiliarity with the USD test shaderball than it is about anything you have done:

In the first pair of rendered examples above, the testrender image on the left shows polygon faceting of the silhouette -- everywhere, but it's most easily visible in the "corners" of the triangular-ish depression of the outer shaderball surface. (Are there agreed upon names for the different geometric/geographic features of the shader ball?) But in the reference image on the right from Houdini, it has been fully subdivided so that no tessellation artifacts are visible.

All the other examples above, which I believe are testrender vs USDView, appear to be about the same level of tessellation as the OSL version. So my questions are:

• Is the USDView rough tessellation what users expect from a shader ball image? Is that adequate?
• How are people used to it appearing in MaterialX tests, in terms of tessellation, but also camera parameters, lighting, etc.? Is there any difference between typical MatX and USD use of this test asset, and if so, is there advantage to us matching one versus the other?
• Is there any advantage to using a higher quality conversion for the sake of looking better and/or more closely matching MatX, USD, or how it would look in a good renderer like Karma?

I think what I'm really getting at is, is this the best tessellation rate that will serve us well for matching MatX and/or USD and testing material behaviors with OSL, versus (obviously) the tradeoff of not wanting a truly ginormous obj file checked into our repo if the increase in quality will never be needed.