image-material.mdx

order	category	name	sourcePath	type	componentSignature
11.4	@threlte/extras	<ImageMaterial>	packages/extras/src/lib/components/ImageMaterial/ImageMaterial.svelte	component	extends props type url ShaderMaterial https://threejs.org/docs/index.html?q=shaderm#api/en/materials/ShaderMaterial name type default required color THREE.ColorRepresentation white false name type default required radius number 0 false name type default required description brightness number 0 false Modifies brightness. Recommended range from -1 to 1. name type default required description contrast number 0 false Modifies contrast. Recommended range from -1 to 1. name type default required description hue number 0 false Modifies hue. Range from 0 to 1. name type default required description saturation number 0 false Modifies saturation. Recommended range from -1 to 1. name type default required description lightness number 0 false Modifies lightness. Recommended range from -1 to 1. name type default required description monochromeColor THREE.ColorRepresentation #535970 false Sets a monochrome tint the image is converted to. name type default required description monochromeStrength number 0 false Sets the strength of monochrome effect. Range from 0 to 1. name type default required description negative boolean false false Enables/disables negative effect. name type required description colorProcessingTexture THREE.Texture | THREE.VideoTexture false Sets a texture used to adjust the strength and the pattern of color processing effects. Each channel of the texture is responsible for a different color processing function. R - hue, G - saturation, B - lightness, A - alpha. name type default required description alphaThreshold number 0 false name type default required description alphaSmoothing number 0 false name type default required zoom number 1 false name type default required toneMapped boolean true false name type default required transparent boolean false false name type default required opacity number 1 false name type default required side THREE.Side THREE.FrontSide false

Adapted from drei's <Image> component, with additional color processing extras.

A shader-based image material component with auto-cover (similar to css/background: cover).

Images from [Wikipedia](https://en.wikipedia.org/wiki/Wikipedia:Featured_pictures/Artwork/Paintings). Carousel originally by [Cyd Stumpel](https://codesandbox.io/s/9s2wd9?file=/src/App.js:1160-1168).

Example

<script lang="ts">
  import { DoubleSide } from 'three'
  import { ImageMaterial } from '@threlte/extras'
</script>

<T.Mesh>
  <T.PlaneGeometry />
  <ImageMaterial
    transparent
    side={DoubleSide}
    url="KlimtDieJungfrau.jpg"
    radius={0.1}
    zoom={1.1}
  />
<T.Mesh>

<ImageMaterial> can also be used with instanced or batched meshes.

Color processing effects

The <ImageMaterial /> component offers a range of properties for dynamic color processing.

The properties brightness, contrast, hue, saturation, and lightness adjust the image's initial values additively. To decrease brightness, for instance, you would use a negative value, while a positive value would increase it. The hue shift is the only exception, its values range from 0 to 1, representing a complete cycle around the color wheel. Notably, values 0 and 1 are equivalent, indicating the same hue position.

For the monochrome effect, specify your preferred tint using the monochromeColor property, and control the effect's intensity with monochromeStrength. Setting this strength to 0 disables the effect entirely, while a value of 1 applies it fully, rendering the image in varying shades of a single color.

Advanced color processing with a texture

The colorProcessingTexture property enables advanced color processing by allowing you to specify a texture that changes the strength and pattern of color effects. It can be used to create dynamic, animated effects as well as static ones that target only specified image areas.

Each texture channel controls a different color processing effect:

• Red for hue
• Green for saturation,
• Blue for lightness
• Alpha for transparency.

Red, green and blue channels are applied multiplicatively to the values of hue, saturation and lightness.

The alpha channel acts differently, providing a flexible alpha override mechanism, that uses a range of values for dynamic image reveal effect. With changing the alphaThreshold property, areas with alpha values approaching 1 are revealed first, followed by regions with values tending towards 0.

To further control this effect, the alphaSmoothing property allows for a gradual fade-in effect within a specified range. For instance, with an alphaThreshold of 0.5 and an alphaSmoothing set to 0.15, alpha values spanning from 0.5 to 0.65 will smoothly transition into visibility.

Enable "color processing with a texture" in the example on top of this page to see the effect applying RGBA color processing texture can have.

*Alpha image used in the example. The lighter values towards the center are revealed first.*

Order of processing effects

1. Alpha override
2. Brightness
3. Contrast
4. Hue, Saturation, Lightness
5. Monochrome
6. Negative