Bosatsu packages

Yichus/Picture

Builtin package (resource picture.bosatsu). This is the complete package source used by this build. The export list names its public API; definitions below give the types and behavior.

New to the API? Start with Make a data app or Build an API, then use this page to look up a definition.

package Yichus/Picture

from Bosatsu/Predef import (
  Int, List, Option, String,
  add, mul, foldl_List, range
)
from Yichus/Num/Float64 import (
  Float64,
  addf, subf, mulf, divf, neg_Float64,
  int_to_Float64, to_Int, cmp_Float64, LT as Below
)
from Yichus/Geometry import Point

export (
  Tone(),
  Align(),
  Mark(),
  Picture(),
  turn_point,
  around
)

exposes (Yichus/Num/Float64, Yichus/Geometry)

# A picture is a value the calculator computes. It is built from a few keyed
# marks and composed with Layer and Group. Coordinates run from -1 to 1 on
# both axes, y pointing up; the page fits that square to the card.
#
# Keys are the identity of an element across evaluations: when an input
# changes, the page moves, fades in or fades out each element by its key, so
# the reader can follow it. The page computes nothing about a mark.

# Tones are roles, not colours; the page maps each one to its theme.
# Ghost marks where something would be under other inputs (a deal a tax
# prevented, an earlier position): drawn hollow, never as a fact of now.
enum Tone:
  Quiet
  Base
  Accent
  Highlight
  Selected
  Ghost

# Which end of a Text sits at its point: Start puts the text to the right
# of the point, End to its left, Middle centres it.
enum Align:
  Start
  Middle
  End

# Dot: a keyed point; clicking it sets the picture's pick input to `pick`.
# Link: a connection between two Dots, named by their keys.
# Ring: a guide circle, such as one ring of a radial arrangement.
# Label: keyed text centred on a point.
# Span: a band `width` thick from one point to another, ending square at
# both points, such as the stretch of values a range covers.
# Text: keyed text with one end at a point, in a tone.
enum Mark:
  Dot(key: String, label: String, at: Point, size: Float64, tone: Tone, pick: Option[Int])
  Link(key: String, source: String, target: String, tone: Tone)
  Ring(key: String, label: String, center: Point, radius: Float64)
  Label(key: String, at: Point, text: String)
  Span(key: String, label: String, from: Point, to: Point, width: Float64, tone: Tone)
  Text(key: String, at: Point, text: String, align: Align, tone: Tone)

# Layer draws pictures in order, later ones on top. Group names a part of a
# picture that can be read on its own.
enum Picture:
  Marks(marks: List[Mark])
  Layer(pictures: List[Picture])
  Group(key: String, label: String, inner: Picture)

# pi as an exact ratio of integers (error below 1e-16), so every engine
# computes the same bits.
def half_pi() -> Float64:
  divf(int_to_Float64(245850922), int_to_Float64(156513558))

# Sum of the alternating series term_k = (-1)^k t^(2k+e) / (2k+e)!, from its
# first term. Twelve terms reach full double precision for t below pi/2.
def alternating(t: Float64, first: Float64, first_exponent: Int) -> Float64:
  sq = mulf(t, t)
  def step(acc: (Float64, Float64), k: Int) -> (Float64, Float64):
    (total, term) = acc
    n = add(mul(2, k), first_exponent)
    denominator = int_to_Float64(mul(add(n, 1), add(n, 2)))
    (addf(total, term), neg_Float64(divf(mulf(term, sq), denominator)))
  (sum, _) = foldl_List(range(12), (int_to_Float64(0), first), step)
  sum

# The point on the unit circle a fraction `turns` of the way round,
# counter-clockwise from the positive x axis. Built from + - * / only.
def turn_point(turns: Float64) -> Point:
  whole = int_to_Float64(to_Int(turns))
  raw = subf(turns, whole)
  frac = match cmp_Float64(raw, int_to_Float64(0)):
    case Below: addf(raw, int_to_Float64(1))
    case _: raw
  quarters = mulf(frac, int_to_Float64(4))
  quadrant = match cmp_Float64(quarters, int_to_Float64(3)):
    case Below: to_Int(quarters)
    case _: 3
  theta = mulf(subf(quarters, int_to_Float64(quadrant)), half_pi())
  c = alternating(theta, int_to_Float64(1), 0)
  s = alternating(theta, theta, 1)
  match quadrant:
    case 0: Point(c, s)
    case 1: Point(neg_Float64(s), c)
    case 2: Point(neg_Float64(c), neg_Float64(s))
    case _: Point(s, neg_Float64(c))

# Slot `index` of `count` evenly spaced slots on a circle, rotated by
# `offset` turns.
def around(center: Point, radius: Float64, index: Int, count: Int, offset: Float64) -> Point:
  Point(cx, cy) = center
  Point(ux, uy) = turn_point(addf(offset, divf(int_to_Float64(index), int_to_Float64(count))))
  Point(addf(cx, mulf(radius, ux)), addf(cy, mulf(radius, uy)))