Module imp3d
Package de.grogra.imp3d.shading

Class Ward

java.lang.Object
de.grogra.graph.impl.Edge
de.grogra.graph.impl.Node
de.grogra.imp3d.shading.ChannelMapNode
de.grogra.imp3d.shading.ColorMapNode
de.grogra.imp3d.shading.Material
de.grogra.imp3d.shading.Ward
All Implemented Interfaces:
Icon, IconSource, ColorMapNodeProperty, Scattering, Shader, ChannelMap, ColorMap, Manageable, PersistenceCapable, Shareable, RenderedIcon, Scattering, Shader, UserFields, XObject, Map, Serializable
public class Ward extends Material implements ColorMapNodeProperty
A Ward shader implementing the anisotropic Ward (1992) reflectance model.

The BRDF is:

   f_r = k_d / π  +  k_s · exp(−E(h)) / (4π · α_u · α_v · √(cos θ_i · cos θ_o))
where the exponent for the isotropic case is 
   E(h) = tan²θ_h / α²
and for the anisotropic case 
   E(h) = ((h·T)² / α_u²  +  (h·B)² / α_v²) / (h·N)²
with N the surface normal, T = dpdu, B = dpdv the surface tangents, α_u the roughness along T (field roughness), and α_v the roughness along B (field roughnessV; if null, isotropic with α_v = α_u).

The model supports diffuse, specular, and (optionally) transparent transmission via the transparency field. Transmission uses Fresnel-weighted straight-through (delta BTDF), CPU light model only.

Author:
MH, MH at YNL 2026
See Also:

  • Field Details

    • DEFAULT_DIFFUSE

      public static final ColorMap DEFAULT_DIFFUSE

    • DEFAULT_SPECULAR

      public static final ColorMap DEFAULT_SPECULAR

    • DEFAULT_ROUGHNESS

      public static final ColorMap DEFAULT_ROUGHNESS

    • DEFAULT_AMBIENT

      public static final ColorMap DEFAULT_AMBIENT

    • DEFAULT_EMISSIVE

      public static final ColorMap DEFAULT_EMISSIVE

    • DEFAULT_TRANSPARENCY

      public static final ColorMap DEFAULT_TRANSPARENCY

    • normalizeEnergy

      protected boolean normalizeEnergy
      When true and diffuse+specular+transparency+diffuseTransparency > 1, the four channels are scaled down proportionally so that the maximum channel sum equals 1. When false (default) only a warning is logged.

    • $TYPE

      public static final Node.NType $TYPE

    • diffuse$FIELD

      public static final Node.NType.Field diffuse$FIELD

    • specular$FIELD

      public static final Node.NType.Field specular$FIELD

    • roughness$FIELD

      public static final Node.NType.Field roughness$FIELD

    • roughnessV$FIELD

      public static final Node.NType.Field roughnessV$FIELD

    • ambient$FIELD

      public static final Node.NType.Field ambient$FIELD

    • emissive$FIELD

      public static final Node.NType.Field emissive$FIELD

    • transparency$FIELD

      public static final Node.NType.Field transparency$FIELD

    • diffuseTransparency$FIELD

      public static final Node.NType.Field diffuseTransparency$FIELD

    • normalizeEnergy$FIELD

      public static final Node.NType.Field normalizeEnergy$FIELD

  • Constructor Details

    • Ward

      public Ward()
      Creates a Ward instance with all channel maps at their defaults (null = use defaults).

    • Ward

      public Ward(ShaderPreset preset)
      Creates a Ward shader with the given preset configuration.
      Parameters:
      preset - the desired material preset

    • Ward

      public Ward(RGBColor diffuse)
      Creates a Ward shader with the given diffuse colour and default roughness (0.3).
      Parameters:
      diffuse - diffuse colour

    • Ward

      public Ward(RGBColor diffuse, float roughness)
      Creates a Ward shader with explicit diffuse colour and isotropic roughness.
      Parameters:
      diffuse - diffuse colour
      roughness - isotropic Ward roughness α ∈ [0,1]

    • Ward

      public Ward(RGBColor diffuse, RGBColor specular, float roughness)
      Creates a Ward shader with explicit diffuse, specular, and isotropic roughness.
      Parameters:
      diffuse - diffuse colour
      specular - specular colour
      roughness - isotropic Ward roughness α ∈ [0,1]

    • Ward

      public Ward(RGBColor diffuse, RGBColor specular, float roughnessU, float roughnessV)
      Creates a Ward shader with explicit diffuse, specular, and anisotropic roughness.
      Parameters:
      diffuse - diffuse colour
      specular - specular colour
      roughnessU - roughness along the dpdu (T) tangent axis
      roughnessV - roughness along the dpdv (B) tangent axis

  • Method Details

    • createWard

      public static Ward createWard()
      Creates a Ward instance with a default specular value of 0.3 (grey).

    • getAverageColor

      public int getAverageColor()
      Description copied from interface: Scattering
      Returns an average color for the scattering entity. This color is used for simplified graphical representations of the corresponding objects.
      Specified by:
      getAverageColor in interface ColorMap
      Specified by:
      getAverageColor in interface Scattering
      Returns:
      an average color in Java's default sRGB color space, encoded as an int (0xAARRGGBB).

    • getFlags

      public int getFlags()
      Specified by:
      getFlags in interface Scattering

    • shade

      public void shade(Environment env, RayList rays, Vector3f out, Spectrum outSpec, Tuple3d outColor)
      Description copied from interface: Shader
      Computes color of outgoing light ray for given input. The computed value is, for each color component j = R, G, B, the following sum over all incident rays k:
      ∑k |cos θk| BSDFj(ωk, out) ck,j
      where BSDFj is the bidirectional scattering distribution function (= BRDF + BTDF) at the point env.point, ωk and ck the direction and color of ray k, and θk the angle between the surface normal and ωk.

      The computation may include physically invalid contributions, which may not fit into the formula above, e.g., ambient or emissive light contributions.

      Specified by:
      shade in interface Shader
      Parameters:
      env - the environment for scattering
      rays - the incoming rays
      out - the direction unit vector of the outgoing ray (i.e., pointing away from the surface)
      outSpec - spectrum of outgoing ray
      outColor - the output color will be placed in here

    • computeMaxRays

      public void computeMaxRays(Environment env, Vector3f out, Spectrum outSpec, Ray reflected, Tuple3f refVariance, Ray transmitted, Tuple3f transVariance)
      Description copied from interface: Shader
      Computes, for the given input, the reflected and transmitted importance rays for which the reflection/transmission probability densities (integrated over the spectrum) attain a maximum. The reflection probability density (measured with respect to solid angle) for the outgoing importance direction (i.e., incoming light direction) ω, given a fixed incident direction in, is
      pr(ω) = cos θ BRDF(ω, in) / R
      where BRDF is the bidirectional reflectivity distribution function, θ the angle between the surface normal and ω, and R the total reflectivity for the incident direction, i.e., the integral over cos θ BRDF(ω, in). The transmission probability density is defined correspondingly.

      The color-fields are set to the total reflectivity/transparency for the incident direction for each color component R, G, B. Thus, for physically plausible BRDF/BTDF, the component-wise sum of reflected.color and transmitted.color lies in the interval [0, 1], and the difference to 1 is the amount absorbed.

      The color may be zero if there is no reflected or transmitted ray, respectively, i.e., if the surface is fully transparent, opaque, or absorbing. The origin-fields of the rays will never be set.

      The computed variances are defined to be, for each color component, (approximations for) the angular mean quadratic deviations of the densities from the returned maximal ray directions. E.g., for perfect reflection/transmission, these variances are zero, whereas for a perfect lambertian reflector, the variance of reflection is ∫ cos θ (1 / π) θ2 dω = (π2 - 4) / 8. This is the value of Shader.LAMBERTIAN_VARIANCE.

      The ray properties which are not mentioned are neither used nor modified. These are the origin and its density, and the direction density.

      Specified by:
      computeMaxRays in interface Shader
      Parameters:
      env - the environment for scattering
      out - the (negated) direction unit vector of the incoming ray (i.e., pointing away from the surface)
      outSpec - spectrum of incoming ray
      reflected - the reflected ray with maximal probability
      refVariance - the angular mean quadratic deviation from reflected
      transmitted - the transmitted ray with maximal probability
      transVariance - the angular mean quadratic deviation from transmitted

    • generateRandomRays

      public void generateRandomRays(Environment env, Vector3f out, Spectrum specOut, RayList rays, boolean adjoint, Random rnd)
      Description copied from interface: Scattering
      Pseudorandomly generates, for the given input, a set of scattered rays. The scattered rays are generated such that they can be used for a Monte Carlo integration of a function f(ω;ν) over cos θ BSDF(ωi, νi; ωo, νo) in the following way:
      • If adjoint is false, out = ωo describes the direction of an outgoing light ray. In this case, the integration is with respect to ωi. Let g(ω, ν; out, μ) = BSDF(ω, ν; out, μ)
      • Otherwise, adjoint is true. In this case, out = ωi describes the direction of an outgoing importance ray (an inverse light ray). Now the integration is with respect to ωo. Let g(ω, ν; out, μ) = BSDF(out, μ; ω, ν)
      Let di and si denote the directions and spectra of the N generated rays (N = rays.size). Then, for every frequency ν the sum
      1 / N ∑i si(ν) f(di; ν)
      is an unbiased estimate for the integral
      ∫ cos θ f(ω; ν) g(ω, ν; out, μ) specOut(μ) dμ dω
      θ is the angle between the surface normal and ω. The domain of integration is the whole sphere, since the bidirectional scattering distribution includes both reflection and transmission (BSDF = BRDF + BTDF).

      If this Scattering instance is in fact a Light source, adjoint is true, and the BSDF is defined as BSDF(out, μ; ω, ν) = L1(ω, ν) δ(μ - ν), i.e., the directional distribution of the emitted radiance at env.point, see Emitter. In this case, out is not used.

      If this Scattering instance is in fact a Sensor, adjoint is false, and the BSDF is defined as BSDF(ω, ν; out, μ) = W1(ω, ν) δ(μ - ν), i.e., the directional distribution of the emitted importance at env.point, see Emitter. In this case, out is not used.

      Let pω be the probability density used for the ray direction (measured with respect to solid angle ω), then the field directionDensity of the ray i is set to pω(di). For ideal specular reflection or transmission, or for directional lights or sensors, pω is not a regular function, the value directionDensity will be set to a multiple of Scattering.DELTA_FACTOR.

      The ray properties which are not mentioned in the given formulas are neither used nor modified. These are the origin and its density.

      Specified by:
      generateRandomRays in interface Scattering
      Parameters:
      env - the environment for scattering
      out - the direction unit vector of the outgoing ray (i.e., pointing away from the surface)
      specOut - the spectrum of the outgoing ray
      rays - the rays to be generated
      adjoint - represents out a light ray or an importance ray?
      rnd - pseudorandom generator
      See Also:

    • computeBSDF

      public float computeBSDF(Environment env, Vector3f in, Spectrum specIn, Vector3f out, boolean adjoint, Spectrum bsdf)
      Evaluates bidirectional scattering distribution function for given input.

      The computed spectrum is an integral over the spectrum of the following product:

      |cos θ| BSDF(ωi, νi; ωo, νo)
      where BSDF is the bidirectional scattering distribution function (= BRDF + BTDF) at the point env.point, ωi the (negated) direction of the incoming light ray, νi the frequency where the incoming ray is sampled, ωo the direction of the outgoing light ray, νo the frequency where the outgoing ray is sampled, and θ the angle between the surface normal and out.

      If adjoint is false, in and out describe true light rays from light sources to sensors. In this case, ωi = in, ωo = out, and the integral is

      bsdf(ν) = |cos θ| ∫ BSDF(in, νi; out, ν) specIn(νi) dνi
      Otherwise, adjoint is true. in and out then describe importance rays (inverse light rays from sensors to light sources). In this case, ωi = out, ωo = in, and the integral is
      bsdf(ν) = |cos θ| ∫ BSDF(out, ν; in, νo) specIn(νo) dνo

      If this Scattering instance is in fact a Light source, adjoint is false, and the BSDF is defined as BSDF(in, μ; ω, ν) = L1(ω, ν) δ(μ - ν), i.e., the directional distribution of the emitted radiance at env.point, see Emitter. In this case, in is not used.

      If this Scattering instance is in fact a Sensor, adjoint is true, and the BSDF is defined as BSDF(ω, ν; in, μ) = W1(ω, ν) δ(μ - ν), i.e., the directional distribution of the emitted importance at env.point, see Emitter. In this case, in is not used.

      The computation should be physically valid. This excludes, e.g., ambient or emissive light contributions.

      The returned value is the value of the probability density pω that would be calculated by Scattering.generateRandomRays(de.grogra.ray.physics.Environment, javax.vecmath.Vector3f, de.grogra.ray.physics.Spectrum, de.grogra.ray.util.RayList, boolean, java.util.Random) if the ray happened to be one of the randomly generated rays.

      Evaluates the Ward BRDF. The parameter out is the sampled (light) direction; in is the view direction. Returns the PDF of sampling out via the mixture strategy used by generateRandomRays(de.grogra.ray.physics.Environment, javax.vecmath.Vector3f, de.grogra.ray.physics.Spectrum, de.grogra.ray.util.RayList, boolean, java.util.Random).

      Specified by:
      computeBSDF in interface Scattering
      Parameters:
      env - the environment for scattering
      in - the (negated) direction unit vector of the incoming ray (i.e., pointing away from the surface)
      specIn - the spectrum of the incoming ray
      out - the direction unit vector of the outgoing ray (i.e., pointing away from the surface)
      adjoint - light ray or importance ray?
      bsdf - the computed spectrum of the outgoing ray will be placed in here
      Returns:
      the value of the probability density for the ray direction

    • isTransparent

      public boolean isTransparent()
      Returns true if a transparency channel map is set.
      Specified by:
      isTransparent in interface Shader

    • getImageChannel

      public ColorMapNode getImageChannel()
      Specified by:
      getImageChannel in interface ColorMapNodeProperty

    • setPreset

      public Ward setPreset(ShaderPreset preset)
      Applies a preset configuration, overwriting all current field values.
      Parameters:
      preset - the desired material preset
      Returns:
      this for use as a factory return value

    • diffuse

      public static Ward diffuse()
      Returns:
      a new Ward preset for ShaderPreset.DIFFUSE.

    • soilDry

      public static Ward soilDry()
      Returns:
      a new Ward preset for ShaderPreset.SOIL_DRY.

    • soilWet

      public static Ward soilWet()
      Returns:
      a new Ward preset for ShaderPreset.SOIL_WET.

    • mirror

      public static Ward mirror()
      Returns:
      a new Ward preset for ShaderPreset.MIRROR.

    • polishedMetal

      public static Ward polishedMetal()
      Returns:
      a new Ward preset for ShaderPreset.POLISHED_METAL.

    • brushedMetal

      public static Ward brushedMetal()
      Returns:
      a new Ward preset for ShaderPreset.BRUSHED_METAL.

    • glass

      public static Ward glass()
      Returns:
      a new Ward preset for ShaderPreset.GLASS.

    • plasticFilm

      public static Ward plasticFilm()
      Returns:
      a new Ward preset for ShaderPreset.PLASTIC_FILM.

    • diffuser

      public static Ward diffuser()
      Returns:
      a new Ward preset for ShaderPreset.DIFFUSER.

    • leafAdaxial

      public static Ward leafAdaxial()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_ADAXIAL.

    • leafAbaxial

      public static Ward leafAbaxial()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_ABAXIAL.

    • leafDry

      public static Ward leafDry()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_DRY.

    • greenhouseGlass

      public static Ward greenhouseGlass()
      Returns:
      a new Ward preset for ShaderPreset.GREENHOUSE_GLASS.

    • retroreflector

      public static Ward retroreflector()
      Returns:
      a new Ward preset for ShaderPreset.RETROREFLECTOR.

    • sand

      public static Ward sand()
      Returns:
      a new Ward preset for ShaderPreset.SAND.

    • concrete

      public static Ward concrete()
      Returns:
      a new Ward preset for ShaderPreset.CONCRETE.

    • diffusingPlastic

      public static Ward diffusingPlastic()
      Returns:
      a new Ward preset for ShaderPreset.DIFFUSING_PLASTIC.

    • aluminiumGreenhouse

      public static Ward aluminiumGreenhouse()
      Returns:
      a new Ward preset for ShaderPreset.ALUMINIUM_GREENHOUSE.

    • whitePlastic

      public static Ward whitePlastic()
      Returns:
      a new Ward preset for ShaderPreset.WHITE_PLASTIC.

    • leafRice

      public static Ward leafRice()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_RICE.

    • leafBarley

      public static Ward leafBarley()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_BARLEY.

    • leafWheat

      public static Ward leafWheat()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_WHEAT.

    • leafCotton

      public static Ward leafCotton()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_COTTON.

    • leafMaize

      public static Ward leafMaize()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_MAIZE.

    • leafJuvenile

      public static Ward leafJuvenile()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_JUVENILE.

    • leafSenescent

      public static Ward leafSenescent()
      Returns:
      a new Ward preset for ShaderPreset.LEAF_SENESCENT.

    • setDiffuse

      public void setDiffuse(float r, float g, float b)
      Sets diffuse colour from RGB components in [0,1].

    • setDiffuse

      public void setDiffuse(float v)
      Sets diffuse colour to a uniform grey value in [0,1].

    • setSpecular

      public void setSpecular(float r, float g, float b)
      Sets specular colour from RGB components in [0,1].

    • setSpecular

      public void setSpecular(float v)
      Sets specular colour to a uniform grey value in [0,1].

    • setRoughness

      public void setRoughness(float v)
      Sets isotropic Ward roughness α ∈ [0,1] (sets both axes).

    • setRoughnessV

      public void setRoughnessV(float v)
      Sets the secondary (dpdv) roughness α_v ∈ [0,1] for anisotropic rendering.

    • setTransparency

      public void setTransparency(float r, float g, float b)
      Sets transparency colour from RGB components in [0,1].

    • setTransparency

      public void setTransparency(float v)
      Sets transparency to a uniform grey value in [0,1].

    • setDiffuseTransparency

      public void setDiffuseTransparency(float r, float g, float b)
      Sets diffuse transmission colour from RGB components in [0,1].

    • setDiffuseTransparency

      public void setDiffuseTransparency(float v)
      Sets diffuse transmission to a uniform grey value in [0,1].

    • clone

      public Ward clone()
      Overrides:
      clone in class Node

    • accept

      public void accept(ShaderVisitor visitor)
      Specified by:
      accept in interface Shader

    • accept

      public void accept(ChannelMapNodeVisitor visitor)
      Overrides:
      accept in class ChannelMapNode

    • getNTypeImpl

      protected Node.NType getNTypeImpl()
      Description copied from class: Node
      This method returns the Node.NType which describes the managed fields of the class of this node. This method has to be implemented in every concrete subclass.
      Overrides:
      getNTypeImpl in class Node
      Returns:
      type describing the managed fields of the class of this node

    • newInstance

      protected Node newInstance()
      Description copied from class: Node
      This method returns a new instance of the class of this node. This method has to be implemented in every concrete subclass.
      Overrides:
      newInstance in class Node
      Returns:
      new instance of class of this node

    • isNormalizeEnergy

      public boolean isNormalizeEnergy()

    • setNormalizeEnergy

      public void setNormalizeEnergy(boolean value)

    • getDiffuse

      public ChannelMap getDiffuse()

    • setDiffuse

      public void setDiffuse(ChannelMap value)

    • getSpecular

      public ChannelMap getSpecular()

    • setSpecular

      public void setSpecular(ChannelMap value)

    • getRoughness

      public ChannelMap getRoughness()

    • setRoughness

      public void setRoughness(ChannelMap value)

    • getRoughnessV

      public ChannelMap getRoughnessV()

    • setRoughnessV

      public void setRoughnessV(ChannelMap value)

    • getAmbient

      public ChannelMap getAmbient()

    • setAmbient

      public void setAmbient(ChannelMap value)

    • getEmissive

      public ChannelMap getEmissive()

    • setEmissive

      public void setEmissive(ChannelMap value)

    • getTransparency

      public ChannelMap getTransparency()

    • setTransparency

      public void setTransparency(ChannelMap value)

    • getDiffuseTransparency

      public ChannelMap getDiffuseTransparency()

    • setDiffuseTransparency

      public void setDiffuseTransparency(ChannelMap value)