geometry.ts

Blame: the commit that last changed each line · file · history

`ec7e78a8` 2026-09-07 Pavel Safronov	1	/**
	2	* Surface coordinates and the cylinder's geometry. See design.md §1.7.
	3	*
	4	* The canonical surface coordinate is (theta, z): theta radians around the
	5	* cylinder, z metres from the sun cap. A cylinder is a developable surface, so the
	6	* unrolled map is exact — no projection distortion, and surface geodesics are
	7	* straight lines on it. That is a real advantage over mapping a globe.
	8	*/
	9	import { RADIUS_M, LENGTH_M, CIRCUMFERENCE_M } from './constants.js'
	10	import {
	11	slatAngularWidth, slatCount, slatSpacing,
	12	} from './slats.js'
	13
	14	export interface SurfacePoint { theta: number; z: number }
	15	export type Vec3 = readonly [number, number, number]
	16
	17	const TAU = 2 * Math.PI
	18
	19	/** Wrap an angle into [0, 2π). */
	20	export function normalizeTheta(theta: number): number {
	21	return ((theta % TAU) + TAU) % TAU
	22	}
	23
	24	/** Shortest signed angular difference from `a` to `b`, in (-π, π]. */
	25	export function deltaTheta(a: number, b: number): number {
	26	let d = normalizeTheta(b) - normalizeTheta(a)
	27	if (d > Math.PI) d -= TAU
	28	if (d <= -Math.PI) d += TAU
	29	return d
	30	}
	31
	32	/** 3D position of a surface point, optionally lifted `height` metres off the floor. */
	33	export function toCartesian(p: SurfacePoint, height = 0): Vec3 {
	34	const r = RADIUS_M - height
	35	return [r * Math.cos(p.theta), r * Math.sin(p.theta), p.z]
	36	}
	37
	38	/**
	39	* Distance walked across the floor between two points. Exact, because unrolling a
	40	* cylinder preserves lengths — the geodesic is a straight line on the map.
	41	*/
	42	export function surfaceDistance(a: SurfacePoint, b: SurfacePoint): number {
	43	return Math.hypot(deltaTheta(a.theta, b.theta) * RADIUS_M, b.z - a.z)
	44	}
	45
	46	/** Straight-line distance through the interior — a chord, always shorter. */
	47	export function directDistance(a: SurfacePoint, b: SurfacePoint): number {
	48	const [ax, ay, az] = toCartesian(a)
	49	const [bx, by, bz] = toCartesian(b)
	50	return Math.hypot(bx - ax, by - ay, bz - az)
	51	}
	52
	53	/** Height above the floor of the highest point on the chord between two points. */
	54	export function chordApexHeight(a: SurfacePoint, b: SurfacePoint): number {
	55	return RADIUS_M * (1 - Math.cos(Math.abs(deltaTheta(a.theta, b.theta)) / 2))
	56	}
	57
	58	// ------------------------------------------------------------------------- slats
	59	// All of these follow the runtime slat count (src/canon/slats.ts), so the whole
	60	// app answers coherently when the author changes it.
	61
	62	/** Centre angle of slat `i`. Slat 0 sits between land strips 0 and 1. */
	63	export function slatCentre(i: number): number {
	64	return normalizeTheta((i + 0.5) * slatSpacing())
	65	}
	66
	67	/** Centre angle of land strip `i`. Strip 0 is centred on theta = 0 (design.md §1.7). */
	68	export function landStripCentre(i: number): number {
	69	return normalizeTheta(i * slatSpacing())
	70	}
	71
	72	/** True if `theta` falls on a transparent slat rather than on land. */
	73	export function isSlat(theta: number): boolean {
	74	const half = slatAngularWidth() / 2
	75	for (let i = 0; i < slatCount(); i++) {
	76	if (Math.abs(deltaTheta(slatCentre(i), theta)) <= half) return true
	77	}
	78	return false
	79	}
	80
	81	/** Index of the land strip containing `theta`, or null if it is on a slat. */
	82	export function landStripIndex(theta: number): number \| null {
	83	if (isSlat(theta)) return null
	84	if (slatCount() === 0) return 0
	85	return Math.round(normalizeTheta(theta) / slatSpacing()) % slatCount()
	86	}
	87
	88	/** True if walking from `a` to `b` crosses at least one slat. */
	89	export function routeCrossesSlat(a: SurfacePoint, b: SurfacePoint, samples = 256): boolean {
	90	if (slatCount() === 0) return false
	91	const d = deltaTheta(a.theta, b.theta)
	92	for (let i = 0; i <= samples; i++) {
	93	if (isSlat(a.theta + (d * i) / samples)) return true
	94	}
	95	return false
	96	}
	97
	98	// --------------------------------------------------------------- map projection
	99	/** Map coordinates in metres: x along the axis, y around the circumference. */
	100	export interface MapPoint { x: number; y: number }
	101
	102	/**
	103	* Where the map is cut open, as an angle.
	104	*
	105	* The map shows the surface once, not tiled, so it needs an edge — and the edge
	106	* has to fall somewhere. Land strip 0 is centred on theta = 0, so cutting there
	107	* would slice a whole strip in half across the top and bottom margins. Cutting at
	108	* a slat centre instead leaves all eight land strips whole and splits only a band
	109	* of stars, which carries no geography. This is the same reasoning that puts
	110	* Earth's map edge at the antimeridian.
	111	*/
	112	export const MAP_CUT_WITHOUT_SLATS = Math.PI
	113
	114	export const mapThetaOrigin = (): number =>
	115	slatCount() === 0 ? MAP_CUT_WITHOUT_SLATS : slatCentre(slatCount() - 1)
	116
	117	export const toMap = (p: SurfacePoint): MapPoint => ({
	118	x: p.z,
	119	y: normalizeTheta(p.theta - mapThetaOrigin()) * RADIUS_M,
	120	})
	121	export const fromMap = (m: MapPoint): SurfacePoint => ({
	122	theta: normalizeTheta(m.y / RADIUS_M + mapThetaOrigin()),
	123	z: Math.min(LENGTH_M, Math.max(0, m.x)),
	124	})
	125
	126	export const MAP_WIDTH_M = LENGTH_M
	127	export const MAP_HEIGHT_M = CIRCUMFERENCE_M