@takram/three-clouds 0.1.0

package/src/qualityPresets.ts

@@ -0,0 +1,117 @@
+import { Vector2 } from 'three'
+import { type PartialDeep, type SharedUnionFieldsDeep } from 'type-fest'
+
+import { type CloudsEffect } from './CloudsEffect'
+
+export type QualityPreset = 'low' | 'medium' | 'high' | 'ultra'
+
+const values = {
+  resolutionScale: 1,
+  lightShafts: true,
+  shapeDetail: true,
+  turbulence: true,
+  haze: true,
+  clouds: {
+    multiScatteringOctaves: 8,
+    accurateSunSkyIrradiance: true,
+    accuratePhaseFunction: false,
+
+    // Primary raymarch
+    maxIterationCount: 500,
+    minStepSize: 50,
+    maxStepSize: 1000,
+    maxRayDistance: 2e5,
+    perspectiveStepScale: 1.01,
+    minDensity: 1e-5,
+    minExtinction: 1e-5,
+    minTransmittance: 1e-2,
+
+    // Secondary raymarch
+    maxIterationCountToGround: 3,
+    maxIterationCountToSun: 2,
+    minSecondaryStepSize: 100,
+    secondaryStepScale: 2,
+
+    // Shadow length
+    maxShadowLengthIterationCount: 500,
+    minShadowLengthStepSize: 50,
+    maxShadowLengthRayDistance: 2e5
+  },
+  shadow: {
+    cascadeCount: 3,
+    mapSize: /*#__PURE__*/ new Vector2(512, 512),
+
+    // Primary raymarch
+    maxIterationCount: 50,
+    minStepSize: 100,
+    maxStepSize: 1000,
+    minDensity: 1e-5,
+    minExtinction: 1e-5,
+    minTransmittance: 1e-4
+  }
+} satisfies PartialDeep<CloudsEffect>
+
+// Relax types narrowed down by satisfies operator.
+type Schema = SharedUnionFieldsDeep<typeof values | CloudsEffect>
+
+export const defaults: Schema = values
+
+export const qualityPresets: Record<QualityPreset, Schema> = {
+  // TODO: We cloud decrease multi-scattering octaves for lower quality presets,
+  // but it leads to a loss of higher frequency scattering, making it darker
+  // overall, which suggests the need for a fudge factor to scale the radiance.
+  low: {
+    ...defaults,
+    lightShafts: false, // Expensive
+    shapeDetail: false, // Expensive
+    turbulence: false, // Expensive
+    clouds: {
+      ...defaults.clouds,
+      accurateSunSkyIrradiance: false, // Greatly reduces texel reads.
+      maxIterationCount: 200,
+      minStepSize: 100,
+      maxRayDistance: 1e5,
+      minDensity: 1e-4,
+      minExtinction: 1e-4,
+      minTransmittance: 1e-1, // Makes the primary march terminate earlier.
+      maxIterationCountToGround: 0, // Expensive
+      maxIterationCountToSun: 1 // Only 1 march makes big difference
+    },
+    shadow: {
+      ...defaults.shadow,
+      maxIterationCount: 25,
+      minDensity: 1e-4,
+      minExtinction: 1e-4,
+      minTransmittance: 1e-2, // Makes the primary march terminate earlier.
+      cascadeCount: 2, // Obvious
+      mapSize: /*#__PURE__*/ new Vector2(256, 256) // Obvious
+    }
+  },
+  medium: {
+    ...defaults,
+    lightShafts: false, // Expensive
+    turbulence: false, // Expensive
+    clouds: {
+      ...defaults.clouds,
+      minDensity: 1e-4,
+      minExtinction: 1e-4,
+      accurateSunSkyIrradiance: false,
+      maxIterationCountToSun: 2,
+      maxIterationCountToGround: 1
+    },
+    shadow: {
+      ...defaults.shadow,
+      minDensity: 1e-4,
+      minExtinction: 1e-4,
+      mapSize: /*#__PURE__*/ new Vector2(256, 256)
+    }
+  },
+  high: defaults, // Consider high quality preset as default.
+  ultra: {
+    ...defaults,
+    shadow: {
+      ...defaults.shadow,
+      mapSize: /*#__PURE__*/ new Vector2(1024, 1024)
+    }
+  }
+}

package/src/r3f/CloudLayer.tsx

@@ -0,0 +1,95 @@
+import {
+  forwardRef,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState
+} from 'react'
+
+import { type ExpandNestedProps } from '@takram/three-geospatial/r3f'
+
+import {
+  CloudLayer as CloudLayerImpl,
+  type CloudLayerLike
+} from '../CloudLayer'
+import { CloudLayers } from '../CloudLayers'
+import { CloudLayersContext } from './CloudLayers'
+
+export interface CloudLayerProps
+  extends CloudLayerLike,
+    ExpandNestedProps<CloudLayerLike, 'densityProfile'> {
+  index?: number
+}
+
+export const CloudLayer = forwardRef<CloudLayerImpl, CloudLayerProps>(
+  function CloudLayer({ index: indexProp, ...props }, forwardedRef) {
+    const context = useContext(CloudLayersContext)
+    if (context == null) {
+      throw new Error(
+        'CloudLayer can only be used within the Clouds component!'
+      )
+    }
+
+    const { layers, indexPool, disableDefault } = context
+    const [index, setIndex] = useState<number>()
+
+    useLayoutEffect(() => {
+      if (indexProp != null) {
+        const poolIndex = indexPool.indexOf(indexProp)
+        if (poolIndex !== -1) {
+          indexPool.splice(poolIndex, 1)
+          setIndex(indexProp)
+          return () => {
+            indexPool.push(indexProp)
+            setIndex(undefined)
+          }
+        }
+      } else {
+        // Sorting is just for predictability. Layer order is still not defined,
+        // but it doesn't matter.
+        const index = indexPool.sort((a, b) => a - b).shift()
+        if (index != null) {
+          setIndex(index)
+          return () => {
+            indexPool.push(index)
+            setIndex(undefined)
+          }
+        }
+      }
+    }, [indexProp, layers, indexPool])
+
+    useLayoutEffect(() => {
+      if (index == null) {
+        return
+      }
+      const layer = layers[index]
+      return () => {
+        layer.copy(
+          disableDefault ? CloudLayerImpl.DEFAULT : CloudLayers.DEFAULT[index]
+        )
+      }
+    }, [layers, index, disableDefault])
+
+    useEffect(() => {
+      if (index == null) {
+        return
+      }
+      if (typeof forwardedRef === 'function') {
+        forwardedRef(layers[index])
+      } else if (forwardedRef != null) {
+        forwardedRef.current = layers[index]
+      }
+    }, [forwardedRef, layers, index])
+
+    // Surely this resets any modifications made via forwarded ref.
+    if (index != null) {
+      const layer = layers[index]
+      layer.copy(
+        disableDefault ? CloudLayerImpl.DEFAULT : CloudLayers.DEFAULT[index]
+      )
+      layer.set(props)
+    }
+
+    return null
+  }
+)

package/src/r3f/CloudLayers.tsx

@@ -0,0 +1,54 @@
+import {
+  createContext,
+  useLayoutEffect,
+  useState,
+  type FC,
+  type ReactNode
+} from 'react'
+
+import { CloudLayer } from '../CloudLayer'
+import { CloudLayers as CloudLayersImpl } from '../CloudLayers'
+
+export interface CloudLayersContextValue {
+  layers: CloudLayersImpl
+  indexPool: number[]
+  disableDefault: boolean
+}
+
+export const CloudLayersContext =
+  /*#__PURE__*/ createContext<CloudLayersContextValue | null>(null)
+
+export interface CloudLayersProps {
+  layers: CloudLayersImpl
+  disableDefault?: boolean
+  children?: ReactNode
+}
+
+export const CloudLayers: FC<CloudLayersProps> = ({
+  layers,
+  disableDefault = false,
+  children
+}) => {
+  const [context, setContext] = useState<CloudLayersContextValue>()
+
+  useLayoutEffect(() => {
+    layers.set(
+      disableDefault
+        ? Array(4).fill(CloudLayer.DEFAULT)
+        : CloudLayersImpl.DEFAULT
+    )
+    setContext({
+      layers,
+      indexPool: [0, 1, 2, 3],
+      disableDefault
+    })
+  }, [layers, disableDefault])
+
+  return (
+    context != null && (
+      <CloudLayersContext.Provider value={context}>
+        {children}
+      </CloudLayersContext.Provider>
+    )
+  )
+}

package/src/r3f/Clouds.tsx

@@ -0,0 +1,278 @@
+import { useFrame, useThree } from '@react-three/fiber'
+import { EffectComposerContext } from '@react-three/postprocessing'
+import {
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from 'react'
+import {
+  LinearFilter,
+  LinearMipMapLinearFilter,
+  NoColorSpace,
+  RedFormat,
+  RepeatWrapping,
+  TextureLoader,
+  type Data3DTexture,
+  type Texture,
+  type WebGLRenderer
+} from 'three'
+
+import { AtmosphereContext, separateProps } from '@takram/three-atmosphere/r3f'
+import {
+  createData3DTextureLoaderClass,
+  DEFAULT_STBN_URL,
+  parseUint8Array,
+  STBNLoader
+} from '@takram/three-geospatial'
+import {
+  type ExpandNestedProps,
+  type PassThoughInstanceProps
+} from '@takram/three-geospatial/r3f'
+
+import {
+  CloudsEffect,
+  cloudsPassOptionsDefaults,
+  type CloudsEffectChangeEvent
+} from '../CloudsEffect'
+import {
+  CLOUD_SHAPE_DETAIL_TEXTURE_SIZE,
+  CLOUD_SHAPE_TEXTURE_SIZE,
+  DEFAULT_LOCAL_WEATHER_URL,
+  DEFAULT_SHAPE_DETAIL_URL,
+  DEFAULT_SHAPE_URL,
+  DEFAULT_TURBULENCE_URL
+} from '../constants'
+import { type Procedural3DTexture } from '../Procedural3DTexture'
+import { type ProceduralTexture } from '../ProceduralTexture'
+import { CloudLayers } from './CloudLayers'
+
+function useTextureState(
+  input: string | Texture | ProceduralTexture,
+  gl: WebGLRenderer
+): Texture | ProceduralTexture | null {
+  const [data, setData] = useState(typeof input !== 'string' ? input : null)
+  useEffect(() => {
+    if (typeof input === 'string') {
+      const loader = new TextureLoader()
+      ;(async () => {
+        const texture = await loader.loadAsync(input)
+        texture.minFilter = LinearMipMapLinearFilter
+        texture.magFilter = LinearFilter
+        texture.wrapS = RepeatWrapping
+        texture.wrapT = RepeatWrapping
+        texture.colorSpace = NoColorSpace
+        texture.needsUpdate = true
+
+        // WORKAROUND: The color space resets to sRGB for unknown reason, unless
+        // the texture is initialized here.
+        gl.initTexture(texture)
+
+        setData(texture)
+      })().catch(error => {
+        console.error(error)
+      })
+    } else {
+      setData(input)
+    }
+  }, [input, gl])
+
+  return data
+}
+
+function use3DTextureState(
+  input: string | Data3DTexture | Procedural3DTexture,
+  size: number
+): Data3DTexture | Procedural3DTexture | null {
+  const [data, setData] = useState(typeof input !== 'string' ? input : null)
+  useEffect(() => {
+    if (typeof input === 'string') {
+      const Loader = createData3DTextureLoaderClass(parseUint8Array, {
+        width: size,
+        height: size,
+        depth: size,
+        format: RedFormat,
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        wrapS: RepeatWrapping,
+        wrapT: RepeatWrapping,
+        wrapR: RepeatWrapping,
+        colorSpace: NoColorSpace
+      })
+      const loader = new Loader()
+      ;(async () => {
+        setData(await loader.loadAsync(input))
+      })().catch(error => {
+        console.error(error)
+      })
+    } else {
+      setData(input)
+    }
+  }, [input, size])
+
+  return data
+}
+
+function useSTBNTextureState(
+  input: string | Data3DTexture
+): Data3DTexture | null {
+  const [data, setData] = useState(typeof input !== 'string' ? input : null)
+  useEffect(() => {
+    if (typeof input === 'string') {
+      const loader = new STBNLoader()
+      ;(async () => {
+        setData(await loader.loadAsync(input))
+      })().catch(error => {
+        console.error(error)
+      })
+    } else {
+      setData(input)
+    }
+  }, [input])
+
+  return data
+}
+
+export interface CloudsProps
+  extends Omit<
+    PassThoughInstanceProps<
+      CloudsEffect,
+      [],
+      Partial<
+        CloudsEffect &
+          ExpandNestedProps<CloudsEffect, 'clouds'> &
+          ExpandNestedProps<CloudsEffect, 'shadow'>
+      >
+    >,
+    | 'localWeatherTexture'
+    | 'shapeTexture'
+    | 'shapeDetailTexture'
+    | 'turbulenceTexture'
+    | 'stbnTexture'
+  > {
+  disableDefaultLayers?: boolean
+  localWeatherTexture?: Texture | ProceduralTexture | string
+  shapeTexture?: Data3DTexture | Procedural3DTexture | string
+  shapeDetailTexture?: Data3DTexture | Procedural3DTexture | string
+  turbulenceTexture?: Texture | ProceduralTexture | string
+  stbnTexture?: Data3DTexture | string
+}
+
+export const Clouds = /*#__PURE__*/ forwardRef<CloudsEffect, CloudsProps>(
+  function Clouds(
+    {
+      disableDefaultLayers = false,
+      localWeatherTexture: localWeatherTextureProp = DEFAULT_LOCAL_WEATHER_URL,
+      shapeTexture: shapeTextureProp = DEFAULT_SHAPE_URL,
+      shapeDetailTexture: shapeDetailTextureProp = DEFAULT_SHAPE_DETAIL_URL,
+      turbulenceTexture: turbulenceTextureProp = DEFAULT_TURBULENCE_URL,
+      stbnTexture: stbnTextureProp = DEFAULT_STBN_URL,
+      children,
+      ...props
+    },
+    forwardedRef
+  ) {
+    const { textures, transientStates, ...contextProps } =
+      useContext(AtmosphereContext)
+
+    const [atmosphereParameters, others] = separateProps({
+      ...cloudsPassOptionsDefaults,
+      ...contextProps,
+      ...textures,
+      ...props
+    })
+
+    const effect = useMemo(() => new CloudsEffect(), [])
+    useEffect(() => {
+      return () => {
+        effect.dispose()
+      }
+    }, [effect])
+
+    useFrame(() => {
+      if (transientStates != null) {
+        effect.sunDirection.copy(transientStates.sunDirection)
+        effect.ellipsoidCenter.copy(transientStates.ellipsoidCenter)
+        effect.ellipsoidMatrix.copy(transientStates.ellipsoidMatrix)
+      }
+    })
+
+    useEffect(() => {
+      if (transientStates != null) {
+        transientStates.overlay = effect.atmosphereOverlay
+        transientStates.shadow = effect.atmosphereShadow
+        transientStates.shadowLength = effect.atmosphereShadowLength
+        return () => {
+          transientStates.overlay = null
+          transientStates.shadow = null
+          transientStates.shadowLength = null
+        }
+      }
+    }, [effect, transientStates])
+
+    const handleChange = useCallback(
+      (event: CloudsEffectChangeEvent) => {
+        if (transientStates == null) {
+          return
+        }
+        switch (event.property) {
+          case 'atmosphereOverlay':
+            transientStates.overlay = effect.atmosphereOverlay
+            break
+          case 'atmosphereShadow':
+            transientStates.shadow = effect.atmosphereShadow
+            break
+          case 'atmosphereShadowLength':
+            transientStates.shadowLength = effect.atmosphereShadowLength
+            break
+        }
+      },
+      [effect, transientStates]
+    )
+    useEffect(() => {
+      effect.events.addEventListener('change', handleChange)
+      return () => {
+        effect.events.removeEventListener('change', handleChange)
+      }
+    }, [effect, handleChange])
+
+    const gl = useThree(({ gl }) => gl)
+    const localWeatherTexture = useTextureState(localWeatherTextureProp, gl)
+    const shapeTexture = use3DTextureState(
+      shapeTextureProp,
+      CLOUD_SHAPE_TEXTURE_SIZE
+    )
+    const shapeDetailTexture = use3DTextureState(
+      shapeDetailTextureProp,
+      CLOUD_SHAPE_DETAIL_TEXTURE_SIZE
+    )
+    const turbulenceTexture = useTextureState(turbulenceTextureProp, gl)
+    const stbnTexture = useSTBNTextureState(stbnTextureProp)
+
+    const { camera } = useContext(EffectComposerContext)
+    return (
+      <>
+        <primitive
+          ref={forwardedRef}
+          object={effect}
+          mainCamera={camera}
+          {...atmosphereParameters}
+          localWeatherTexture={localWeatherTexture}
+          shapeTexture={shapeTexture}
+          shapeDetailTexture={shapeDetailTexture}
+          turbulenceTexture={turbulenceTexture}
+          stbnTexture={stbnTexture}
+          {...others}
+        />
+        <CloudLayers
+          layers={effect.cloudLayers}
+          disableDefault={disableDefaultLayers}
+        >
+          {children}
+        </CloudLayers>
+      </>
+    )
+  }
+)

package/src/r3f/index.ts

@@ -0,0 +1,2 @@
+export * from './Clouds'
+export * from './CloudLayer'

package/src/shaders/catmullRomSampling.glsl

@@ -0,0 +1,113 @@
+// Taken from https://gist.github.com/TheRealMJP/c83b8c0f46b63f3a88a5986f4fa982b1
+// TODO: Use 5-taps version: https://www.shadertoy.com/view/MtVGWz
+// Or even 4 taps (requires preprocessing in the input buffer):
+// https://www.shadertoy.com/view/4tyGDD
+
+/**
+ * MIT License
+ *
+ * Copyright (c) 2019 MJP
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+vec4 textureCatmullRom(sampler2D tex, vec2 uv) {
+  vec2 texSize = vec2(textureSize(tex, 0));
+
+  // We're going to sample a a 4x4 grid of texels surrounding the target UV
+  // coordinate. We'll do this by rounding down the sample location to get the
+  // exact center of our "starting" texel. The starting texel will be at
+  // location [1, 1] in the grid, where [0, 0] is the top left corner.
+  vec2 samplePos = uv * texSize;
+  vec2 texPos1 = floor(samplePos - 0.5) + 0.5;
+
+  // Compute the fractional offset from our starting texel to our original
+  // sample location, which we'll feed into the Catmull-Rom spline function to
+  // get our filter weights.
+  vec2 f = samplePos - texPos1;
+
+  // Compute the Catmull-Rom weights using the fractional offset that we
+  // calculated earlier. These equations are pre-expanded based on our knowledge
+  // of where the texels will be located, which lets us avoid having to evaluate
+  // a piece-wise function.
+  vec2 w0 = f * (-0.5 + f * (1.0 - 0.5 * f));
+  vec2 w1 = 1.0 + f * f * (-2.5 + 1.5 * f);
+  vec2 w2 = f * (0.5 + f * (2.0 - 1.5 * f));
+  vec2 w3 = f * f * (-0.5 + 0.5 * f);
+
+  // Work out weighting factors and sampling offsets that will let us use
+  // bilinear filtering to simultaneously evaluate the middle 2 samples from the
+  // 4x4 grid.
+  vec2 w12 = w1 + w2;
+  vec2 offset12 = w2 / (w1 + w2);
+
+  // Compute the final UV coordinates we'll use for sampling the texture
+  vec2 texPos0 = texPos1 - 1.0;
+  vec2 texPos3 = texPos1 + 2.0;
+  vec2 texPos12 = texPos1 + offset12;
+
+  texPos0 /= texSize;
+  texPos3 /= texSize;
+  texPos12 /= texSize;
+
+  vec4 result = vec4(0.0);
+  result += texture(tex, vec2(texPos0.x, texPos0.y)) * w0.x * w0.y;
+  result += texture(tex, vec2(texPos12.x, texPos0.y)) * w12.x * w0.y;
+  result += texture(tex, vec2(texPos3.x, texPos0.y)) * w3.x * w0.y;
+
+  result += texture(tex, vec2(texPos0.x, texPos12.y)) * w0.x * w12.y;
+  result += texture(tex, vec2(texPos12.x, texPos12.y)) * w12.x * w12.y;
+  result += texture(tex, vec2(texPos3.x, texPos12.y)) * w3.x * w12.y;
+
+  result += texture(tex, vec2(texPos0.x, texPos3.y)) * w0.x * w3.y;
+  result += texture(tex, vec2(texPos12.x, texPos3.y)) * w12.x * w3.y;
+  result += texture(tex, vec2(texPos3.x, texPos3.y)) * w3.x * w3.y;
+
+  return result;
+}
+
+vec4 textureCatmullRom(sampler2DArray tex, vec3 uv) {
+  vec2 texSize = vec2(textureSize(tex, 0));
+  vec2 samplePos = uv.xy * texSize;
+  vec2 texPos1 = floor(samplePos - 0.5) + 0.5;
+  vec2 f = samplePos - texPos1;
+  vec2 w0 = f * (-0.5 + f * (1.0 - 0.5 * f));
+  vec2 w1 = 1.0 + f * f * (-2.5 + 1.5 * f);
+  vec2 w2 = f * (0.5 + f * (2.0 - 1.5 * f));
+  vec2 w3 = f * f * (-0.5 + 0.5 * f);
+  vec2 w12 = w1 + w2;
+  vec2 offset12 = w2 / (w1 + w2);
+  vec2 texPos0 = texPos1 - 1.0;
+  vec2 texPos3 = texPos1 + 2.0;
+  vec2 texPos12 = texPos1 + offset12;
+  texPos0 /= texSize;
+  texPos3 /= texSize;
+  texPos12 /= texSize;
+  vec4 result = vec4(0.0);
+  result += texture(tex, vec3(texPos0.x, texPos0.y, uv.z)) * w0.x * w0.y;
+  result += texture(tex, vec3(texPos12.x, texPos0.y, uv.z)) * w12.x * w0.y;
+  result += texture(tex, vec3(texPos3.x, texPos0.y, uv.z)) * w3.x * w0.y;
+  result += texture(tex, vec3(texPos0.x, texPos12.y, uv.z)) * w0.x * w12.y;
+  result += texture(tex, vec3(texPos12.x, texPos12.y, uv.z)) * w12.x * w12.y;
+  result += texture(tex, vec3(texPos3.x, texPos12.y, uv.z)) * w3.x * w12.y;
+  result += texture(tex, vec3(texPos0.x, texPos3.y, uv.z)) * w0.x * w3.y;
+  result += texture(tex, vec3(texPos12.x, texPos3.y, uv.z)) * w12.x * w3.y;
+  result += texture(tex, vec3(texPos3.x, texPos3.y, uv.z)) * w3.x * w3.y;
+  return result;
+}