Orbit Gallery
Image gallery intro: photos spiral into the centre around a title. An image-universe hero: a continuous stream of photos flows along an Archimedean spiral (a vortex) from the frame edges into the center — evenly spaced by arc length, shrinking and rotating to follow the coil, with the title held in the clear middle.
Source
components/kuchi/orbit-gallery.tsx
1"use client";23import { useMemo, useState } from "react";4import {5 AbsoluteFill,6 Easing,7 getRemotionEnvironment,8 Img,9 interpolate,10 staticFile,11 useCurrentFrame,12 useVideoConfig,13} from "remotion";14import {15 Item,16 mixOklch,17 parseColor,18 resolveFont,19 type KuchiTheme,20 useKuchiTheme,21 withAlpha,22} from "@/lib/kuchi-ui";2324const TWO_PI = Math.PI * 2;25/** Lookup resolution for the arc-length reparameterization table. */26const ARC_SAMPLES = 1024;2728export interface OrbitGalleryProps {29 title?: string;30 subtitle?: string;31 /** Pill CTA under the subtitle. Empty string hides it. */32 buttonLabel?: string;33 /**34 * Card artwork URLs, cycled along the spiral stream. A URL that fails to load35 * falls back to a gradient tile rather than breaking playback. Pass `[]` to36 * render self-contained editorial gradient tiles (no network).37 */38 images?: string[];39 /** How many times the Archimedean spiral winds from the edge to the center. */40 turns?: number;41 /** Arc spacing between cards along the stream (smaller = denser). */42 spacing?: number;43 /** Radius scale — larger pushes the outer coils off-frame, same coil gaps. */44 spread?: number;45 /** How much cards shrink toward the center (0 = uniform). */46 sizeAttenuation?: number;47 /** Card long-edge in px at the outer radius, on the reference 600px canvas. */48 imageSize?: number;49 /** Card width / height (portrait < 1). */50 cardAspect?: number;51 /** Percent of the path over which a card fades in at the outer end. */52 fadeIn?: number;53 /** Percent of the path over which a card fades out at the center end. */54 fadeOut?: number;55 /** Corner rounding, matching the reference's 0–20 scale (0 = sharp). */56 cornerRadius?: number;57 /** Seconds for the stream to flow one full turnover into the center. */58 orbitSeconds?: number;59 /** Overrides the design system's `background`. */60 background?: string;61 /** Overrides the design system's `foreground`. */62 textColor?: string;63 /** Design-system token overrides. */64 theme?: Partial<KuchiTheme>;65 /** Defaults to `"dark"` — the orbit is a cinematic stage, lit for dark. */66 mode?: "light" | "dark";67 /**68 * The face this scene paints its words in — a label from `fonts.ts`69 * ("Inter", "Space Grotesk", "Instrument Serif") or a CSS family you have70 * loaded yourself. Unset, the scene keeps the face it was designed around.71 *72 * Overrides `theme.fontFamily`, which is how a brand kit re-skins a whole73 * timeline from one value.74 */75 fontFamily?: string;76 /** Tiny captions pinned to the bottom edge. Empty strings hide them. */77 footerLeft?: string;78 footerCenter?: string;79 footerRight?: string;80 speed?: number;81 className?: string;82}8384export const SAMPLE_IMAGES = Array.from(85 { length: 16 },86 (_, i) => `https://picsum.photos/seed/snap-orbit-${i + 1}/440/560`,87);8889/** Editorial two-stop gradients used for tiles without a (working) photo. */90export const PLACEHOLDER_FILLS = [91 "linear-gradient(135deg, #2b5fd9, #14306e)",92 "linear-gradient(135deg, #c96f2f, #7a3c12)",93 "linear-gradient(135deg, #e8e4da, #b6ad99)",94 "linear-gradient(135deg, #c8332b, #6e1511)",95 "linear-gradient(135deg, #b9a0d0, #6f5590)",96 "linear-gradient(135deg, #4c6b3c, #24361a)",97 "linear-gradient(135deg, #1f4dd8, #0d2262)",98 "linear-gradient(135deg, #d9d2c5, #a09684)",99];100101const FONT_STACK = "Inter, -apple-system, BlinkMacSystemFont, sans-serif";102103/**104 * Archimedean spiral point at parameter `n` in [0, 1]: n=0 is the outer edge105 * (radius R), n=1 is the center (radius 0). Because the radius falls off106 * LINEARLY, every coil is separated by the same radial gap (R / turns) — the107 * even "circle to circle" spacing. `y` is flipped so the spiral reads clockwise108 * from the top like the reference.109 */110export function archimedeanPoint(111 n: number,112 R: number,113 turns: number,114): { x: number; y: number } {115 const ang = n * turns * TWO_PI;116 const rad = R * (1 - n);117 return { x: rad * Math.cos(ang), y: -rad * Math.sin(ang) };118}119120/**121 * Build the arc-length reparameterization table for a spiral of `turns` turns.122 * Sampling the path by even parameter would bunch cards near the center (where123 * the coils are short); sampling by even ARC length spaces them evenly. The124 * spiral's shape is radius-independent, so the table is built once at R=1 and125 * returns, for each even arc fraction, the spiral parameter `n` that lands126 * there.127 */128export function buildArcTable(turns: number, samples = 2000): Float64Array {129 const cum = new Float64Array(samples + 1);130 let prev = archimedeanPoint(0, 1, turns);131 for (let k = 1; k <= samples; k++) {132 const pt = archimedeanPoint(k / samples, 1, turns);133 cum[k] = cum[k - 1] + Math.hypot(pt.x - prev.x, pt.y - prev.y);134 prev = pt;135 }136 const total = cum[samples] || 1;137138 const nForArc = new Float64Array(ARC_SAMPLES + 1);139 let j = 0;140 for (let a = 0; a <= ARC_SAMPLES; a++) {141 const target = (a / ARC_SAMPLES) * total;142 while (j < samples && cum[j + 1] < target) j++;143 const seg = cum[j + 1] - cum[j];144 const f2 = seg > 0 ? (target - cum[j]) / seg : 0;145 nForArc[a] = (j + f2) / samples;146 }147 return nForArc;148}149150/** Map an arc fraction `s` in [0, 1) to the spiral parameter `n` (interpolated151 * so motion stays smooth, never quantized into visible steps). */152export function arcToN(s: number, nForArc: Float64Array): number {153 const x = Math.max(0, Math.min(ARC_SAMPLES, s * ARC_SAMPLES));154 const i = Math.floor(x);155 const a = nForArc[i];156 const b = nForArc[Math.min(i + 1, ARC_SAMPLES)];157 return a + (b - a) * (x - i);158}159160/** Radius scale for the spiral: R = 0.48·min · (1 + (spread − 1)·0.18). */161export function ringRadius(minDim: number, spread: number): number {162 return 0.48 * minDim * (1 + (spread - 1) * 0.18);163}164165/** Card size multiplier from its distance to the center — smaller toward the166 * middle. `dist/R` clamped to 1, raised to `sizeAttenuation/2`. */167export function sizeScale(168 dist: number,169 R: number,170 sizeAttenuation: number,171): number {172 return sizeAttenuation > 0173 ? Math.min(dist / R, 1) ** (sizeAttenuation * 0.5)174 : 1;175}176177/**178 * A root-relative asset is a `public/` file. Only the site's own Player serves179 * it at that path; Remotion Studio and a render know its URL through180 * `staticFile()` alone — so every environment but the Player rewrites it.181 */182function resolveSrc(src: string): string {183 const isLocal = src.startsWith("/") && !src.startsWith("//");184 if (!isLocal || getRemotionEnvironment().isPlayer) return src;185 // A value that already came out of staticFile() carries the static base186 // (`/static-<hash>/…`); running it through again would prefix it twice.187 const base = staticFile("_").slice(0, -2);188 if (base && src.startsWith(`${base}/`)) return src;189 try {190 return staticFile(src.replace(/^\/+/, ""));191 } catch {192 return src;193 }194}195196/**197 * One card face: the editorial gradient is always painted as the base layer,198 * and a photo (when provided) overlays it. A failed load flips to `errored` so199 * the gradient shows through — crucially, the `onError` handler also stops200 * Remotion's <Img> from calling cancelRender(), which would otherwise halt the201 * whole player when an external image is blocked or slow to fail. */202function OrbitTile({ src, fill }: { src: string | undefined; fill: string }) {203 const [errored, setErrored] = useState(false);204 return (205 <>206 <div style={{ position: "absolute", inset: 0, backgroundImage: fill }} />207 {src && !errored ? (208 // No crossOrigin: nothing reads these pixels back, and asking for CORS209 // fails every photo from a host that does not send it (most do not),210 // leaving only the gradient.211 <Img212 src={resolveSrc(src)}213 onError={() => setErrored(true)}214 style={{215 position: "absolute",216 inset: 0,217 width: "100%",218 height: "100%",219 objectFit: "cover",220 }}221 />222 ) : null}223 </>224 );225}226227export function OrbitGallery({228 title = "A whole new universe",229 subtitle = "Article — The Design Process",230 buttonLabel = "Explore",231 images,232 turns = 3,233 spacing = 5,234 spread = 7,235 sizeAttenuation = 2,236 imageSize = 172,237 cardAspect = 0.78,238 fadeIn = 20,239 fadeOut = 0,240 cornerRadius = 5,241 orbitSeconds = 40,242 background,243 textColor,244 theme,245 mode,246 fontFamily,247 footerLeft = "",248 footerCenter = "",249 footerRight = "",250 speed = 1,251 className,252}: OrbitGalleryProps) {253 const frame = useCurrentFrame();254 const { width, height, fps, durationInFrames } = useVideoConfig();255 const tokens = useKuchiTheme(theme, mode ?? "dark");256 const face = resolveFont(fontFamily ?? tokens.fontFamily) ?? FONT_STACK;257 const stage = background ?? tokens.background;258 const ink = textColor ?? tokens.foreground;259 const t = frame * speed;260261 const minDim = Math.min(width, height);262 const R = ringRadius(minDim, spread);263 const baseSize = imageSize * (minDim / 600);264 const artwork = images ?? SAMPLE_IMAGES;265 const nImgs = artwork.length || 1;266267 // Arc-length table (shape-only, so it depends on `turns` alone).268 const nForArc = useMemo(() => buildArcTable(turns), [turns]);269270 const stepFrac = Math.max(0.005, (spacing * 0.5) / 100);271 const slots = Math.min(400, Math.ceil(1 / stepFrac) + 2);272273 // Seamless inward flow: advance the stream by a whole number of card-steps274 // over the composition so the loop has no visible jump.275 const stepsPerLoop = Math.max(276 1,277 Math.round(durationInFrames / fps / orbitSeconds / stepFrac),278 );279 const base =280 ((((t / durationInFrames) * stepsPerLoop * stepFrac) % 1) + 1) % 1;281282 const cards = [];283 for (let i = 0; i < slots; i++) {284 const s = (((base + i * stepFrac) % 1) + 1) % 1;285 const n = arcToN(s, nForArc);286 cards.push({ key: i, tt: s * 100, n, imgIdx: i % nImgs });287 }288 // Draw outer coils first, center cards last (on top), like the reference.289 cards.sort((a, b) => a.n - b.n);290291 // The stream cycles `images`, so one photo rides the spiral more than once.292 // Studio outlines the largest drawn copy inside the frame (else the largest293 // at all); the others are only pictures of it.294 const best = new Map<295 number,296 { key: number; inFrame: boolean; size: number }297 >();298 for (const card of cards) {299 // Only the copies the loop below draws: same fade, same cut-offs.300 let opacity = 1;301 if (card.tt < fadeIn) opacity = card.tt / fadeIn;302 else if (fadeOut > 0 && card.tt > 100 - fadeOut)303 opacity = (100 - card.tt) / fadeOut;304 if (opacity < 0.01) continue;305 const p = archimedeanPoint(card.n, R, turns);306 const size = sizeScale(Math.hypot(p.x, p.y), R, sizeAttenuation);307 if (size < 0.002) continue;308 const inFrame = Math.abs(p.x) < width / 2 && Math.abs(p.y) < height / 2;309 const held = best.get(card.imgIdx);310 if (311 !held ||312 (inFrame && !held.inFrame) ||313 (inFrame === held.inFrame && size > held.size)314 )315 best.set(card.imgIdx, { key: card.key, inFrame, size });316 }317318 const intro = interpolate(t, [0, 16], [0, 1], {319 extrapolateLeft: "clamp",320 extrapolateRight: "clamp",321 });322323 const titleSize = Math.min(width * 0.066, height * 0.11);324325 return (326 <AbsoluteFill327 className={className}328 style={{ backgroundColor: stage, fontFamily: face }}329 >330 {cards.map((card) => {331 const p = archimedeanPoint(card.n, R, turns);332 const dist = Math.hypot(p.x, p.y);333334 let opacity = 1;335 if (card.tt < fadeIn) opacity = card.tt / fadeIn;336 else if (fadeOut > 0 && card.tt > 100 - fadeOut)337 opacity = (100 - card.tt) / fadeOut;338 if (opacity < 0.01) return null;339340 const scale = sizeScale(dist, R, sizeAttenuation);341 if (scale < 0.002) return null;342343 // Tangent of the spiral at this point → the card's rotation.344 const p2 = archimedeanPoint(Math.min(card.n + 0.001, 1), R, turns);345 const angleDeg = (Math.atan2(p2.y - p.y, p2.x - p.x) * 180) / Math.PI;346347 // Long edge = baseSize·scale; the short edge follows cardAspect.348 const ch = baseSize * scale;349 const cw = ch * cardAspect;350 const rad = (cornerRadius / 20) * (Math.min(cw, ch) / 2);351352 // Only the few tiny cards passing right behind the title get a light353 // blur (a cheap per-element filter on a handful of small cards — nothing354 // like the frame-wide backdrop blur that stalled the player). Everything355 // in the visible outer band stays sharp.356 const centerBlurR = minDim * 0.16;357 const blurPx = dist < centerBlurR ? (1 - dist / centerBlurR) * 4 : 0;358359 return (360 <Item361 key={card.key}362 index={card.imgIdx}363 // Gradient tiles alone (`images={[]}`) are no photo to select.364 primary={365 artwork.length > 0 && best.get(card.imgIdx)?.key === card.key366 }367 >368 <div369 style={{370 position: "absolute",371 left: "50%",372 top: "50%",373 width: cw,374 height: ch,375 marginLeft: -cw / 2,376 marginTop: -ch / 2,377 zIndex: Math.round(card.n * 8),378 translate: `${p.x.toFixed(2)}px ${p.y.toFixed(2)}px`,379 rotate: `${angleDeg.toFixed(2)}deg`,380 opacity: opacity * intro,381 filter:382 blurPx > 0.15 ? `blur(${blurPx.toFixed(2)}px)` : undefined,383 borderRadius: rad,384 overflow: "hidden",385 backgroundColor: mixOklch(stage, tokens.card, 0.35),386 boxShadow: `0 ${(ch * 0.12).toFixed(1)}px ${(ch * 0.3).toFixed(1)}px ${withAlpha(387 mixOklch(stage, "#000", 0.75),388 0.4,389 )}`,390 }}391 >392 <OrbitTile393 src={artwork.length ? artwork[card.imgIdx % nImgs] : undefined}394 fill={PLACEHOLDER_FILLS[card.imgIdx % PLACEHOLDER_FILLS.length]}395 />396 </div>397 </Item>398 );399 })}400401 {/* Soft focus pool behind the lockup: a radial dark scrim so the title402 reads. This is a plain gradient (no backdrop-filter) — the earlier403 backdrop blur re-blurred every moving card each frame and froze the404 player. The slight softness behind the text comes from the small405 center cards' own light blur (see `centerBlur` in the card loop). */}406 {/* The scrim deepens the page behind the lockup; with no page there is407 nothing to deepen, and on a transparent one it would be black. */}408 {(title || subtitle || buttonLabel) && parseColor(stage).alpha !== 0 ? (409 <div410 style={{411 position: "absolute",412 left: "50%",413 top: "50%",414 width: width * 0.66,415 height: height * 0.5,416 marginLeft: -(width * 0.66) / 2,417 marginTop: -(height * 0.5) / 2,418 borderRadius: "50%",419 backgroundImage: `radial-gradient(ellipse at center, ${withAlpha(420 stage,421 0.62,422 )} 0%, ${withAlpha(stage, 0.34)} 42%, transparent 70%)`,423 opacity: intro,424 zIndex: 9,425 }}426 />427 ) : null}428429 <AbsoluteFill430 style={{431 alignItems: "center",432 justifyContent: "center",433 textAlign: "center",434 zIndex: 10,435 }}436 >437 {title ? (438 <div439 style={{440 fontSize: titleSize,441 fontWeight: 500,442 letterSpacing: "-0.015em",443 lineHeight: 1.08,444 color: ink,445 maxWidth: "82%",446 opacity: interpolate(t, [8, 34], [0, 1], {447 extrapolateLeft: "clamp",448 extrapolateRight: "clamp",449 }),450 translate: `0px ${interpolate(t, [8, 34], [titleSize * 0.4, 0], {451 extrapolateLeft: "clamp",452 extrapolateRight: "clamp",453 easing: Easing.out(Easing.cubic),454 })}px`,455 filter: `blur(${interpolate(t, [8, 30], [8, 0], {456 extrapolateLeft: "clamp",457 extrapolateRight: "clamp",458 })}px)`,459 }}460 >461 {title}462 </div>463 ) : null}464465 {subtitle ? (466 <div467 style={{468 marginTop: titleSize * 0.42,469 fontSize: titleSize * 0.26,470 letterSpacing: "0.02em",471 color: ink,472 opacity:473 0.65 *474 interpolate(t, [16, 40], [0, 1], {475 extrapolateLeft: "clamp",476 extrapolateRight: "clamp",477 }),478 translate: `0px ${interpolate(479 t,480 [16, 40],481 [titleSize * 0.25, 0],482 {483 extrapolateLeft: "clamp",484 extrapolateRight: "clamp",485 easing: Easing.out(Easing.cubic),486 },487 )}px`,488 }}489 >490 {subtitle}491 </div>492 ) : null}493494 {buttonLabel ? (495 <div496 style={{497 marginTop: titleSize * 0.5,498 padding: `${titleSize * 0.14}px ${titleSize * 0.34}px`,499 borderRadius: 9999,500 backgroundColor: withAlpha(ink, 0.14),501 fontSize: titleSize * 0.23,502 fontWeight: 500,503 color: ink,504 opacity: interpolate(t, [24, 44], [0, 1], {505 extrapolateLeft: "clamp",506 extrapolateRight: "clamp",507 }),508 scale: String(509 interpolate(t, [24, 48], [0.7, 1], {510 extrapolateLeft: "clamp",511 extrapolateRight: "clamp",512 easing: Easing.out(Easing.back(1.4)),513 }),514 ),515 }}516 >517 {buttonLabel}518 </div>519 ) : null}520 </AbsoluteFill>521522 {footerLeft || footerCenter || footerRight ? (523 <div524 style={{525 position: "absolute",526 left: width * 0.05,527 right: width * 0.05,528 bottom: height * 0.032,529 display: "flex",530 justifyContent: "space-between",531 fontSize: titleSize * 0.22,532 color: ink,533 opacity:534 0.78 *535 interpolate(t, [30, 50], [0, 1], {536 extrapolateLeft: "clamp",537 extrapolateRight: "clamp",538 }),539 zIndex: 10,540 }}541 >542 <span>{footerLeft}</span>543 <span>{footerCenter}</span>544 <span>{footerRight}</span>545 </div>546 ) : null}547 </AbsoluteFill>548 );549}









