Polyscope uses matcaps to render the appearance of objects in the scene, as opposed to more traditional configurations of lights and shading models, etc. A matcap is a small image of a material, which is sampled by the renderer to query the materials’ appearance from a some angle. Scene information like lighting is implicitly baked in to the matcap image.
Most objects in Polyscope (surface meshes, point clouds, vectors, etc) expose a
material='matname' option to choose a material for the object’s appearance. Additionally, materials can generally be set in the UI from
[Options] --> [Material].
In Polyscope, we often want to adjust set custom colors for rendered objects. This can be a constant color for the object (to distinguish structures in a scene), or a varying color across a surface (when color-mapping scalar quantities). Traditionally, matcaps don’t really support setting an albedo color like this, but we achieve the effect in Polyscope by blending between basis matcaps.
How it works
Instead of just using a single material image, we take four images of the material, representing basis red, green, blue, and black components.
At runtime, to generate a color from a triple of
rgb values each in the range
[0,1], we sample the images like:
outputColor = r * basis_r + g * basis_g + b * basis_b + (1. - r - g - b) * basis_k
Intuitively, this strategy presumes the underlying material has a light response which is a linear function of the color, plus another component which is independent of the color. Crucially, Polyscope uses a linear lighting workflow and performs this blending on linear matcaps before tone-mapping, which is necessary for the results to look reasonable across the full color space.
Materials which which support this blending are denoted by
(rgb) in the options menu. Ordinary static matcaps consisting of a single image can still be used as materials, but will ignore any color maps or other options.
Polyscope supports the following built-in materials:
Loading custom materials
Custom matcaps can be loaded at runtime from image files and used anywhere materials are used. Loading can be performed with the UI from
[Appearance] --> [Materials] --> [Load material], or programatically using the function below. For blendable matcaps, if the single filename
mat.hdr is given, Polyscope will try to load
Ideally, matcap images should be linear
.hdr images for best results, but any image will work. If other image formats are given, the input is assumed to be non-linear and will be inverse-tonemapped with
gamma=2.2 before use. Most common image formats are accepted (anything
stb_image can read).
Load a new static (non-blendable) material from a single image file
filename. The new material will be called
import polyscope as ps ps.load_static_material("fancy mat", "my_image.png")
load_blendable_material(mat_name, filenames=None, filename_base=None, filename_ext=None)
Load a new blendable material, which will be called
There are two different ways to specify which files to load the material images from:
filenames, a tuple of four string filenames corresponding to red, green, blue, and black basis materials
filename_ext, to generate the four filenames as
filename_base + "_r" + filename_ext, etc.
import polyscope as ps ps.load_blendable_material("fancy blendable mat", filenames = ( "my_image_r.png", "my_image_g.png", "my_image_b.png", "my_image_k.png" )) # OR ps.load_blendable_material("fancy blendable mat", filename_base="my_image", filename_ext=".png")