sky schema for usd

UsdSkyAPI.usda

#usda 1.0
(
    doc = """UsdSkyModel is a schema representing procedural sky parameters.
    It allows for defining parameters like solar position, atmospheric clarity,
    and the underlying sky model (Preetham, Hosek-Wilkie, Nishita) for realistic
    sky rendering.
    
    UsdCloudModel is a schema for defining procedural cloud parameters,
    inspired by meteorological concepts like cloud cover, cloud types, altitude,
    and density. Multiple layers can be combined to create complex cloud formations.
    
    Implementation note: A suitable candidate for implementation of a the sky
    color and luminance calculations is here: https://github.com/andrewwillmott/sun-sky/tree/master
    
    Sky and Cloud could be applied to a SkyDome prim, and the behavior could be that if
    applied, the procedural computation takes precedence over a supplied texture map (or vice versa!)
    """
    subLayers = [
        @usdGeom/schema.usda@
    ]
)

over "GLOBAL" (
    customData = {
        string libraryName      = "usdGames"
        string libraryPath      = "./"
    }
)
{
}


class "UsdSkyModel" (
    customData = {
        string apiSchemaType = "singleApply"
    }
    inherits = </APISchemaBase>
    doc = """Schema representing a procedural sky model with shared parameters 
    like solar position, turbidity, and ground reflectance. The sky model used 
    (e.g., Preetham, Hosek-Wilkie, or Nishita) is specified via the skyModel 
    attribute."""
)
{
    # Solar position
    double skyModel:solarAzimuth = 0 (
        doc = """Azimuth angle of the sun (in degrees)."""
    )
    double skyModel:solarElevation = 45 (
        doc = """Elevation angle of the sun (in degrees)."""
    )

    # Turbidity - atmospheric clarity/haziness
    double skyModel:turbidity = 2.5 (
        doc = """Atmospheric turbidity, which influences how much light is scattered. Values range typically from 2 (clear sky) to 10 (very hazy)."""
    )

    # Ground reflectance (albedo)
    double skyModel:groundAlbedo = 0.3 (
        doc = """Ground reflectance, influencing the color of the sky. Values range from 0 (non-reflective) to 1 (highly reflective)."""
    )

    # Optional model-specific parameters
    double skyModel:skyBrightness = 1.0 (
        doc = """Overall brightness multiplier for the sky. Optional, applicable to some sky models."""
    )
    double skyModel:atmosphericDensity = 1.0 (
        doc = """Atmospheric density affecting the scattering behavior of light. Optional, mostly used in advanced models."""
    )
    color3f skyModel:atmosphericScattering = (0.002, 0.003, 0.004) (
        doc = """RGB scattering coefficients for atmospheric scattering. Optional, mostly used in advanced models."""
    )

    # Sky model name
    uniform token skyModel:skyModel = "Preetham" (
        allowedTokens = [
            "Preetham", "PreethamTable", "PreethamBRDF",
            "HosekWilie", "HosekWilkieTable", "HosekWilieBRDF",
            "Preetham",
            "CIEClear", "CIEOvercase", "CIEPartlyCloudy" ]
        doc = """Specifies the sky model used."""
    )
}


class "UsdCloudModel" (
    customData = {
        string apiSchemaType = "multipleApply"
    }
    inherits = </APISchemaBase>
    doc = """Schema representing procedural cloud cover parameters. This schema 
    includes attributes for cloud cover fraction, cloud types, altitude range, 
    density, wind speed, and time-based evolution.
    
    Complex meteorological conditions may be simulated by having more than one
    CloudModel prim in a scene.
    
    Improvements could include using maps for the parameters of this model.
    """
)
{
    # Cloud fraction (coverage)
    float cloudModel:cloudCover = 0.5 (
        doc = """Fraction of the sky covered by clouds, ranging from 0 (clear sky) to 1 (fully overcast)."""
    )

    # Cloud type weights (fraction of cloud types present)
    float cloudModel:cumulusWeight = 0.4 (
        doc = """Weight of cumulus clouds (low, fluffy clouds) in the procedural sky."""
    )
    float cloudModel:stratusWeight = 0.3 (
        doc = """Weight of stratus clouds (low, flat clouds) in the procedural sky."""
    )
    float cloudModel:cirrusWeight = 0.2 (
        doc = """Weight of cirrus clouds (high, wispy clouds) in the procedural sky."""
    )
    float cloudModel:cumulonimbusWeight = 0.1 (
        doc = """Weight of cumulonimbus clouds (storm clouds) in the procedural sky."""
    )

    # Cloud altitude range (in meters)
    double cloudModel:minAltitude = 1000 (
        doc = """Minimum altitude (in meters) for cloud formations."""
    )
    double cloudModel:maxAltitude = 10000 (
        doc = """Maximum altitude (in meters) for cloud formations."""
    )

    # Cloud density (optical thickness)
    float cloudModel:cloudDensity = 0.8 (
        doc = """Cloud density, affecting their optical thickness. Higher values make clouds denser and darker."""
    )

    # Wind speed and direction (influencing cloud movement)
    double cloudModel:windSpeed = 5.0 (
        doc = """Wind speed (in meters per second) that affects cloud movement."""
    )
    float cloudModel:windDirection = 90 (
        doc = """Wind direction (in degrees), where 0 is north and 90 is east."""
    )

    # Optional: Cloud optical depth (affects light scattering)
    float cloudModel:opticalDepth = 0.7 (
        doc = """Optical depth of clouds, affecting how much light they scatter and block."""
    )

    # Optional: Time evolution of clouds
    bool cloudModel:enableTimeEvolution = 1 (
        doc = """Enable or disable time-based cloud evolution."""
    )
    float cloudModel:timeScale = 0.01 (
        doc = """Controls the rate at which clouds evolve over time."""
    )
}