Files
chenlin d5e9004f6c
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

217 lines
9.7 KiB
Python

"""Low sun over wet sand, warm horizon, dusk overhead.
The hard part of a sunset is not the colours, it is that a low sun is a lighting
setup, not a backdrop. Three things have to agree or it reads as a beach photo
with a robot pasted on:
- **The sun sits just above the horizon**, so `dir` is almost horizontal. That is
what produces long shadows raking across the sand, and long shadows are what
makes footfall legible -- the same reason `rough` uses a low light.
- **Its colour is warm and the ambient is not.** Direct sunlight at dusk is
orange; everything it does not reach is lit by the sky, which is violet-blue.
Tinting both the same way is the usual mistake and it flattens the image.
- **The ambient has no direction.** Skylight at dusk arrives from the whole dome
at once, so it is the headlight's `ambient` and nothing else: its `diffuse` is
zero, and there is no fill light. Both of those are sources with a direction --
the headlight's diffuse follows the camera, so it re-lights the robot as you
orbit, which is the one thing an ambient must not do.
- **The sand does not mirror.** `reflectance` is the only knob mjlab's
`MaterialCfg` exposes, and MuJoCo's reflection is a mirror of the whole scene:
any value above zero puts an upside-down robot under the robot. Damp sand does
not do that, and a legged robot standing on its own reflection reads as ice.
So reflectance stays at 0. The sheen survives regardless, because the band of
glare running back towards the sun is the **specular highlight** -- MuJoCo's
material default, lit by the sun's `specular` -- and not the reflection. That
was worth checking rather than assuming: rendering it both ways shows the
mirrored robot disappear and the glare stay exactly where it was.
The sky is a **cube map** rather than a builtin gradient, because a builtin one
runs from zenith to horizon and nothing else -- it cannot be warm on one side of
the compass and cold on the other, which is most of what makes a low sun read as
a low sun rather than as an orange filter over the whole world. The six faces are
generated by `tools/make_skybox.py`, which draws the
sun's disc into them as well, so the sun is where the light says it is rather
than merely implied. That file holds the sun direction and **it has to stay the
negation of the light's `dir` below**: disagreeing puts the bright part of the sky
somewhere other than where the light comes from, and nothing anywhere complains.
The grain is `mark="random"` over a **flat** base, at `texrepeat=(2, 2)` with
`texuniform` so one tile is about half a metre. Both halves of that were arrived
at by rendering: at `texrepeat=24` the speckle averages out at any normal camera
distance into a flat brown floor, and over a `checker` base -- the obvious way to
get variation -- the squares read unmistakably as floor tiles, which is precisely
what a beach must not look like.
The sky gradient runs from dusk at the zenith (`rgb1`) to the warm band at the
horizon (`rgb2`), which is the direction MuJoCo's builtin gradient takes -- the
test for this scene renders it and checks the horizon really is the warmer end,
because getting it backwards produces a picture that is merely odd rather than
obviously broken.
"""
from __future__ import annotations
from pathlib import Path
import numpy as np
from . import skygen
from .registry import GROUND, Headlight, Scene
#: This scene's images, inside the package beside the code describing them.
#: This scene's asset directory, **named from this module** rather than written
#: out. The two used to be independent literals, so renaming the module left the
#: path pointing at a directory that no longer existed -- and a scene whose
#: textures silently fail to bind renders unchanged with no error, which
#: `rough.py`'s docstring already records happening twice.
_ASSET = Path(__file__).resolve().parent / "assets" / Path(__file__).stem
# ── The sky ─────────────────────────────────────────────────────────────
#
# Colours are code and live here; the six PNGs they produce are data and live
# under assets/. Re-render them with `python tools/make_skybox.py beach`
# after changing anything below -- the scene loads what was written last time.
#
# The mechanics (MuJoCo's face table, the image axes within a face, seamless
# noise) are in scenes/skygen.py and were measured rather than assumed.
#: Direction **towards** the sun; the negation of the scene light's `dir`.
SUN = np.array([-0.9336, -0.3515, 0.0698])
SUNWARD_HORIZON = np.array([0.66, 0.79, 0.92])
SUNWARD_ZENITH = np.array([0.26, 0.44, 0.74])
COLD_HORIZON = np.array([0.10, 0.15, 0.34])
COLD_ZENITH = np.array([0.02, 0.03, 0.10])
AFTERGLOW_LOW = np.array([1.00, 0.55, 0.26])
AFTERGLOW_HIGH = np.array([0.99, 0.66, 0.66])
AFTERGLOW_ELEV_DEG = 11.0
AFTERGLOW_AZIM_DEG = 62.0
CLOUD_LIT = np.array([1.00, 0.52, 0.20])
CLOUD_SHADE = np.array([0.34, 0.16, 0.26])
CLOUD_FREQ = 1.5
CLOUD_THRESHOLD = 0.49
CLOUD_SOFTNESS = 0.22
CLOUD_SQUASH = 1.7
CLOUD_SEED = 7
#: The sun's disc is 1.6 degrees, not the real 0.27: a face is 512 texels across
#: 90 degrees, so a real sun is a texel and a half and reads as nothing.
SUN_RADIUS_DEG = 1.6
SUN_GLOW_DEG = 18.0
SUN_COLOR = np.array([1.0, 0.90, 0.68])
#: Stars: under a texel across, hard-edged, all the same brightness. See the
#: module docstring; the count is calibrated by sampling because the lattice is
#: 3D and most cells hold their star off the sphere where it is never seen.
STAR_FREQ = 14.0
STAR_PROB = 0.24
STAR_RADIUS = 0.032
STAR_SEED = 31
def _stars(dirs: np.ndarray) -> np.ndarray:
q = dirs * STAR_FREQ
cell = np.floor(q).astype(np.int64)
frac = q - cell
present = skygen.hash01(cell, STAR_SEED) < STAR_PROB
centre = np.stack(
[0.3 + 0.4 * skygen.hash01(cell, STAR_SEED + k) for k in (1, 2, 3)], axis=-1
)
dist = np.linalg.norm(frac - centre, axis=-1)
return ((dist < STAR_RADIUS).astype(float) * present)[..., None]
def sky(dirs: np.ndarray) -> np.ndarray:
sun = SUN / np.linalg.norm(SUN)
up = skygen.smoothstep(dirs[..., 2:3] / 0.75)
towards = skygen.smoothstep(np.sum(dirs * sun, axis=-1, keepdims=True)) ** 2
elev = np.degrees(np.arcsin(np.clip(dirs[..., 2:3], -1.0, 1.0)))
sunward = SUNWARD_HORIZON + (SUNWARD_ZENITH - SUNWARD_HORIZON) * up
cold = COLD_HORIZON + (COLD_ZENITH - COLD_HORIZON) * up
out = cold + (sunward - cold) * towards
azim = skygen.angle_to(dirs, sun)
band = np.exp(-((np.maximum(elev, 0.0) / AFTERGLOW_ELEV_DEG) ** 2)) * np.exp(
-((azim / AFTERGLOW_AZIM_DEG) ** 2)
)
glow_colour = AFTERGLOW_LOW + (AFTERGLOW_HIGH - AFTERGLOW_LOW) * np.clip(
np.maximum(elev, 0.0) / AFTERGLOW_ELEV_DEG, 0.0, 1.0
)
out = out + (glow_colour - out) * (0.92 * band)
q = dirs * CLOUD_FREQ
q = np.stack([q[..., 0], q[..., 1], q[..., 2] * CLOUD_SQUASH], axis=-1)
density = skygen.fbm(q, CLOUD_SEED)[..., None]
cover = skygen.smoothstep((density - CLOUD_THRESHOLD) / CLOUD_SOFTNESS)
cover = cover * skygen.smoothstep(elev / 2.5) * (1.0 - 0.96 * up)
lit = CLOUD_SHADE + (CLOUD_LIT - CLOUD_SHADE) * skygen.smoothstep(
(towards * 1.15) ** 0.5
)
out = out + (lit - out) * (0.95 * cover)
darkness = np.clip(1.0 - out.max(axis=-1, keepdims=True) * 1.5, 0.0, 1.0)
gate = skygen.smoothstep(
np.clip(darkness * (1.0 - cover) * skygen.smoothstep(elev / 6.0)
* (1.0 - towards) * 2.5, 0.0, 1.0)
)
out = out + (1.0 - out) * np.clip(_stars(dirs) * gate, 0.0, 1.0)
glow = np.exp(-((azim / SUN_GLOW_DEG) ** 2))
out = out + (SUN_COLOR - out) * (0.6 * glow)
return out + (SUN_COLOR - out) * skygen.disc(dirs, sun, SUN_RADIUS_DEG)
#: Cube maps this scene generates, by file prefix.
CUBEMAPS = {"sky": sky}
def scene() -> Scene:
from mjlab.utils import spec_config as sc
return Scene(
headlight=Headlight(ambient=(0.500, 0.525, 0.600), diffuse=(0.0, 0.0, 0.0)),
textures=(
sc.TextureCfg(
name="beach_sand", type="2d", builtin="flat",
rgb1=(0.80, 0.70, 0.54), rgb2=(0.80, 0.70, 0.54),
mark="random", markrgb=(0.60, 0.50, 0.37), random=0.30,
width=512, height=512,
),
sc.TextureCfg(
name="beach_sky", type="skybox",
cubefiles=skygen.cubefiles(_ASSET),
),
),
materials=(
sc.MaterialCfg(
name="beach_sand", texture="beach_sand", texuniform=True,
texrepeat=(2.0, 2.0), reflectance=0.0, geom_names_expr=GROUND,
),
),
lights=(
# The sun itself: low, warm, hard-edged shadows.
#
# The diffuse channels run above 1.0 on purpose. MuJoCo does not
# clamp a light's intensity there -- clamping happens once, on the
# final pixel -- so values above one are how a light is made bright
# rather than merely saturated. Pushing the colour instead would only
# shift the hue: red is already at its limit at this warmth.
#
# 1.75x the nominal value. It was 2.4 and that clipped: the sand
# facing the sun went to white, which is not brightness but lost
# information, and it takes the grain with it. Chosen by measuring
# the clipped fraction rather than by eye, since a blown highlight
# looks like a bright highlight until you count the pixels.
sc.LightCfg(
name="sun", type="directional", pos=(-9.0, -3.4, 0.63),
dir=(0.9336, 0.3515, -0.0698), castshadow=True,
diffuse=(1.75, 1.09, 0.60), specular=(0.75, 0.52, 0.34),
ambient=(0.0, 0.0, 0.0),
),
),
)