diffrp.materials.base_material#

class diffrp.materials.base_material.CustomSurfaceInputs(si: SurfaceInput)#

Bases: Mapping

Implementation for custom vertex attribute access.

This is an implementation detail and you do not need to take care of it.

__init__(si: SurfaceInput) → None#
class diffrp.materials.base_material.SurfaceInput(uniforms: SurfaceUniform, vertex_buffers: VertexArrayObject, interpolator: Interpolator)#

Bases: object

Users can access system and custom attributes of the fragments currently processing from the shade function from this class.

__init__(uniforms: SurfaceUniform, vertex_buffers: VertexArrayObject, interpolator: Interpolator)#
property color: Tensor#

The interpolated color attributes (RGBA) of the fragments. Usually ranges from 0 to 1 (instead of 255).

Defaults to white (ones) if not specified in the MeshObject.

Returns:

Tensor of shape (…, 4) where … is batched pixels.

Return type:

torch.Tensor

property custom_attrs: Mapping[str, Tensor]#

Dictionary of custom attributes of the fragments.

The keys are the same as you specified in the MeshObject.

If some objects provide the custom inputs while others not for the key, you will get zeros for objects where the custom vertex attributes are absent.

An error will be raised if custom inputs with the same key have different numbers of channels.

Returns:

Tensor of shape (…, C) where … is batched pixels. C is the number of channels in the vertex attribute you input in MeshObject.

Return type:

torch.Tensor

interpolate_ex(vertex_buffer: Tensor, world_transform: Literal['none', 'vector', 'vectornor', 'point', 'vector3ex1', 'vector3norex1'] = 'none')#

Use this method to interpolate arbitrary vertex attributes into fragments queried in the shade method.

Parameters:

  • vertex_buffer (torch.Tensor) – The vertex attributes to be interpolated. Tensor of shape (V, C).

  • world_transform (str) –

    One of ‘none’, ‘vector’, ‘vectornor’, ‘point’, ‘vector3ex1’ or ‘vector3norex1’.
    ’none’: Interpolate the vertex attributes as-is.
    ’vector’: Requires C = 3. Transforms as direction vectors attributed with vertices into world space before interpolating.
    ’vectornor’: Requires C = 3. Transforms as direction vectors attributed with vertices into world space and normalize before interpolating. They are NOT normalized again after interpolation.
    ’point’: Requires C = 3. Transforms as positions or points attributed with vertices into world space before interpolating.
    ’vector3ex1’: Requires C = 4. Transforms the first 3 channels as direction vectors attributed with vertices into world space before interpolating. The fourth channel is interpolated as-is.
    ’vector3norex1’: Requires C = 4. Transforms the first 3 channels as direction vectors attributed with vertices into world space and normalize before interpolating. They are NOT normalized again after interpolation. The fourth channel is interpolated as-is.

Returns:

Tensor of shape (…, C) where … is batched pixels. C is the number of channels in the vertex attribute you input in vertex_buffer.

Return type:

torch.Tensor

property local_pos: Tensor#

The local (object space) position of the fragments.

Returns:

Tensor of shape (…, 3) where … is batched pixels.

Return type:

torch.Tensor

property uv: Tensor#

The interpolated UV coordinate attributes of the fragments. (0, 0) is the bottom-left in OpenGL convention, in contrast to top-left in most image libraries.

Defaults to zeros if not specified in the MeshObject.

Returns:

Tensor of shape (…, 2) where … is batched pixels.

Return type:

torch.Tensor

property view_dir: Tensor#

View directions. The normalized unit vectors looking from the camera to the world position of the fragments.

Returns:

Tensor of shape (…, 3) where … is batched pixels.

Return type:

torch.Tensor

property world_normal: Tensor#

The normalized unit vectors for geometry world normal of the fragments. This includes the effect of smooth (vertex interpolation) and flat face specification in the MeshObject.

Returns:

Tensor of shape (…, 3) where … is batched pixels.

Return type:

torch.Tensor

property world_normal_unnormalized: Tensor#

The geometry world normal of the fragments. This includes the effect of smooth (vertex interpolation) and flat face specification in the MeshObject.

Normals are normalized in vertices, but not again after interpolation. Thus, this is slightly off from unit vectors, but may be useful in e.g. tangent space calculations.

Returns:

Tensor of shape (…, 3) where … is batched pixels.

Return type:

torch.Tensor

property world_pos: Tensor#

The world position of the fragments.

Returns:

Tensor of shape (…, 3) where … is batched pixels.

Return type:

torch.Tensor

property world_tangent: Tensor#

The interpolated tangents in world space of the fragments.

The xyz dimensions form the tangent vector, while the w dimension specifies the sign (1 or -1).

Defaults to zeros if not specified in the MeshObject.

Returns:

Tensor of shape (…, 4) where … is batched pixels.

Return type:

torch.Tensor

class diffrp.materials.base_material.SurfaceMaterial#

Bases: object

abstract shade(su: SurfaceUniform, si: SurfaceInput) → SurfaceOutputStandard#

The interface for implementing materials. It takes a fragment batch specified as SurfaceUniform and SurfaceInput.

You shall not assume any order or shape of the fragment batch. In other words, the method should be trivial on the batch dimension, that is, the method should return batched outputs equivalent to concatenated outputs from the same batch of input but split into multiple sub-batches.

Most functions implemented with attribute accesses, element/vector-wise operations and DiffRP utility functions naturally have this property.

class diffrp.materials.base_material.SurfaceOutputStandard(albedo: Tensor | None = None, normal: Tensor | None = None, emission: Tensor | None = None, metallic: Tensor | None = None, smoothness: Tensor | None = None, occlusion: Tensor | None = None, alpha: Tensor | None = None, aovs: Dict[str, Tensor] | None = None, normal_space: Literal['tangent', 'object', 'world'] = 'tangent')#

Bases: object

The output structure that specifies standard and custom (AOV) outputs from the material (shader). All outputs are optional. The outputs shapes are all (…, C), where (…) is batched pixels. They should match the batch dimensions provided by SurfaceInput. It can be 1D to 3D according to interpolator implementation, 1D under default settings – a batch of pixel features of shape (B, C). See the documentation for interpolator options and interpolators for more details.

Parameters:

  • albedo (torch.Tensor) – The per-pixel base color in linear RGB space, used both for diffuse and specular. Defaults to magenta (1.0, 0.0, 1.0). Tensor of shape (…, 3), where (…) should match the pixel batch dimensions in inputs.

  • normal (torch.Tensor) – The per-pixel normal in specified space. Defaults to geometry normal. See also normal_space. This can be used to implement per-pixel (neural) normal maps. Tensor of shape (…, 3), where (…) should match the pixel batch dimensions in inputs.

  • emission (torch.Tensor) – The per-pixel emission value in linear RGB space. Defaults to black (0.0, 0.0, 0.0) which means no emission. Tensor of shape (…, 3), where (…) should match the pixel batch dimensions in inputs.

  • metallic (torch.Tensor) – The per-pixel metallic value. Defaults to 0.0, fully dielectric. Tensor of shape (…, 1), where (…) should match the pixel batch dimensions in inputs.

  • smoothness (torch.Tensor) – The per-pixel smoothness value. Defaults to 0.5. Tensor of shape (…, 1), where (…) should match the pixel batch dimensions in inputs.

  • occlusion (torch.Tensor) – The per-pixel ambient occlusion value. Dims indirect light. Defaults to 1.0, no occlusion. Tensor of shape (…, 1), where (…) should match the pixel batch dimensions in inputs.

  • alpha (torch.Tensor) – The per-pixel alpha value. Linear transparency. Defaults to 1.0, fully opaque. Any value will be overridden to 1.0 if render sessions are executed in opaque_only mode. Tensor of shape (…, 1), where (…) should match the pixel batch dimensions in inputs.

  • aovs (Dict[str, torch.Tensor]) – Auxiliary Output Variables (AOVs). Anything you would like to output for the shader. Batch dimensions of values need to match the pixel batch dimensions in inputs.

  • normal_space (str) –

    One of ‘tangent’, ‘object’ and ‘world’.
    Defaults to ‘tangent’ as most normal maps are in tangent space, featuring a ‘blueish’ look.
    ’object’ and ‘world’ spaces are simple.
    ’tangent’ means (tangent, bitangent, geometry_normal) for XYZ components, respectively, where tangents are typically generated from the UV mapping. See also the mikktspace plugin.

__init__(albedo: Tensor | None = None, normal: Tensor | None = None, emission: Tensor | None = None, metallic: Tensor | None = None, smoothness: Tensor | None = None, occlusion: Tensor | None = None, alpha: Tensor | None = None, aovs: Dict[str, Tensor] | None = None, normal_space: Literal['tangent', 'object', 'world'] = 'tangent') → None#
albedo: Tensor | None = None#
alpha: Tensor | None = None#
aovs: Dict[str, Tensor] | None = None#
emission: Tensor | None = None#
metallic: Tensor | None = None#
normal: Tensor | None = None#
normal_space: Literal['tangent', 'object', 'world'] = 'tangent'#
occlusion: Tensor | None = None#
smoothness: Tensor | None = None#
class diffrp.materials.base_material.SurfaceUniform(M: Tensor, V: Tensor, P: Tensor)#

Bases: object

Users can access the system surface uniforms from this class.

Uniform means the same value or data accessed across a material. Extra custom uniforms like textures and other attributes should be put in fields of the materials.

Parameters:

  • M (torch.Tensor) – The Model matrix. Tensor of shape (4, 4).

  • V (torch.Tensor) – The View matrix in OpenGL convention. Tensor of shape (4, 4).

  • P (torch.Tensor) – The Projection matrix in OpenGL convention. Tensor of shape (4, 4).

M: Tensor#
P: Tensor#
V: Tensor#
__init__(M: Tensor, V: Tensor, P: Tensor) → None#
property camera_matrix#

Access the camera matrix, or pose transform, in OpenGL convention. Camera right, up, forward is X, Y, -Z, respectively. This is the inverse of the View matrix V.

Returns:

The camera matrix, commonly referred to as c2w. Tensor of shape (4, 4).

Return type:

torch.Tensor

property camera_position#

Access the position of the camera.

Returns:

The camera position vector XYZ. Tensor of shape (3,).

Return type:

torch.Tensor

class diffrp.materials.base_material.VertexArrayObject(verts: Tensor, normals: Tensor, world_pos: Tensor, tris: IntTensor, stencils: IntTensor, color: Tensor, uv: Tensor, tangents: Tensor, custom_attrs: Dict[str, Tensor])#

Bases: object

Vertex Array Object. Includes vertex and index buffers of the scene.

Created automatically by render pipelines.

__init__(verts: Tensor, normals: Tensor, world_pos: Tensor, tris: IntTensor, stencils: IntTensor, color: Tensor, uv: Tensor, tangents: Tensor, custom_attrs: Dict[str, Tensor]) → None#
color: Tensor#
custom_attrs: Dict[str, Tensor]#
normals: Tensor#
stencils: IntTensor#
tangents: Tensor#
tris: IntTensor#
uv: Tensor#
verts: Tensor#
world_pos: Tensor#