Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

4.1 KB
Raw Blame
/**
 * Describe a pixel canvas as the aspect ratio a human (or an image model) reads
 * it as — "2:3 portrait", "5:7 portrait", "16:9 landscape", "1:1 square".
 *
 * Exists so a prompt that tells a model what shape to draw can be DERIVED from
 * the canvas it will be rendered onto, rather than restated beside it. A
 * hand-written ratio phrase is a second copy of the canvas size, and the two
 * drift the moment one of them is tuned: the deck layout prompts said "2:3
 * portrait" for months after the per-kind canvases moved to the true card trims
 * (1096x1536 and 888x1536), so every card was asked for one framing and
 * rendered at another.
 *
 * The reduction is a best rational approximation (continued fractions) bounded
 * to small whole numbers, not a plain GCD: 1096:1536 reduces exactly to
 * 137:192, which is arithmetically right and useless as a phrase. Bounded, it
 * lands on 5:7 — the poker-card trim the canvas was chosen to approximate.
 * A canvas that already reduces small (1024:1536) still reports its exact
 * ratio, because the exact convergent is reached before the bound.
 *
 * Pure.
 */

// Largest value either side of the ratio may take. 24 is above every ratio a
// real print/screen format uses (2:3, 5:7, 11:19, 16:9, 4:3, 21:9) and below
// the point where a ratio stops reading as a shape.
const DEFAULT_MAX_TERM = 24;

const isPositiveSize = (value) => Number.isFinite(value) && value > 0;

/**
 * The smallest whole-number ratio within `maxTerm` that describes `width:height`.
 * Returns `null` for a non-positive or non-finite edge.
 *
 * @returns {{ width: number, height: number }|null}
 */
export function aspectRatioTerms(width, height, { maxTerm = DEFAULT_MAX_TERM } = {}) {
  if (!isPositiveSize(width) || !isPositiveSize(height)) return null;

  // Continued-fraction expansion of width/height, keeping the last convergent
  // whose terms both fit the bound. `previous` is the convergent before it, as
  // the recurrence needs both. The seeds are the standard 1/0 and 0/1.
  let value = width / height;
  let previous = { width: 0, height: 1 };
  let best = { width: 1, height: 0 };

  // 40 terms is far past the point where a double's precision is meaningful;
  // the bound below almost always ends the walk within a handful.
  for (let step = 0; step < 40; step += 1) {
    const whole = Math.floor(value);
    const next = {
      width: whole * best.width + previous.width,
      height: whole * best.height + previous.height,
    };
    if (next.width > maxTerm || next.height > maxTerm) break;
    previous = best;
    best = next;
    const remainder = value - whole;
    // An exact convergent — no remainder left to expand.
    if (remainder <= Number.EPSILON) break;
    value = 1 / remainder;
  }

  // Only reachable when the first convergent already exceeds the bound (an
  // extreme banner like 4096x64); fall back to the exact reduced ratio rather
  // than reporting nothing.
  if (best.width < 1 || best.height < 1) {
    const roundedWidth = Math.round(width);
    const roundedHeight = Math.round(height);
    // A sub-pixel edge rounds to zero, and `0:0` would be reported as a SQUARE —
    // a phrase that is not merely unhelpful but false. Nothing describable here.
    if (roundedWidth < 1 || roundedHeight < 1) return null;
    const divisor = greatestCommonDivisor(roundedWidth, roundedHeight);
    return { width: roundedWidth / divisor, height: roundedHeight / divisor };
  }
  return best;
}

function greatestCommonDivisor(a, b) {
  let x = Math.abs(a);
  let y = Math.abs(b);
  while (y) [x, y] = [y, x % y];
  return x || 1;
}

/**
 * The ratio phrase for a canvas — `"5:7 portrait"`, `"16:9 landscape"`,
 * `"1:1 square"`. Empty string for a canvas that cannot be described, so a
 * caller interpolating it into a prompt degrades to saying nothing about
 * framing rather than to saying something false.
 */
export function aspectRatioPhrase(width, height, options) {
  const terms = aspectRatioTerms(width, height, options);
  if (!terms) return '';
  const orientation = terms.width === terms.height ? 'square'
    : terms.width < terms.height ? 'portrait'
      : 'landscape';
  return `${terms.width}:${terms.height} ${orientation}`;
}