@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/src/labels/label_point.ts

@@ -0,0 +1,131 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import Label from './label';
+import type {CollisionBounds, CollisionLabel} from './collision-types';
+import type {LabelLayout, LabelParent} from './label-types';
+import PointAnchor from './point_anchor';
+import OBB from '../utils/obb';
+import StyleParser from '../styles/style_parser';
+
+type LabelPointCoordinate = [number, number];
+type LabelPointSize = [number, number];
+type LabelPointLayout = LabelLayout;
+const typedStyleParser = StyleParser as unknown as {zeroPair: readonly number[]};
+
+export default class LabelPoint extends Label {
+    /** Discriminator used by the checked point/text quad builders. */
+    declare type: 'point';
+
+    position: LabelPointCoordinate;
+    angle: number;
+    parent: LabelParent | undefined;
+    start_anchor_index: number;
+    degenerate: boolean;
+    throw_away: boolean;
+    static PLACEMENT: Record<string, number>;
+
+    constructor (position: LabelPointCoordinate, size: LabelPointSize, layout: LabelPointLayout, angle = 0) {
+        super(size, layout);
+        this.type = 'point';
+        this.position = [position[0], position[1]];
+        this.angle = angle;
+        this.parent = this.layout.parent;
+        this.update();
+
+        this.start_anchor_index = 1;
+        this.degenerate = !this.size[0] && !this.size[1] && !this.layout.buffer[0] && !this.layout.buffer[1];
+        this.throw_away = false;
+    }
+
+    update() {
+        super.update();
+        this.computeOffset();
+        this.updateBBoxes();
+    }
+
+    computeOffset () {
+        this.offset = [this.layout.offset[0], this.layout.offset[1]];
+
+        // Additional anchor/offset for point:
+        if (this.parent) {
+            let parent = this.parent;
+            // point's own anchor, text anchor applied to point, additional point offset
+            this.offset = PointAnchor.computeOffset(this.offset, parent.size, parent.anchor, PointAnchor.zero_buffer);
+            this.offset = PointAnchor.computeOffset(this.offset, parent.size, this.anchor, PointAnchor.zero_buffer);
+            if (parent.offset !== typedStyleParser.zeroPair) {        // point has an offset
+                if (this.offset === typedStyleParser.zeroPair) {      // no text offset, use point's
+                    this.offset = parent.offset;
+                }
+                else {                                           // text has offset, add point's
+                    this.offset[0] += parent.offset[0];
+                    this.offset[1] += parent.offset[1];
+                }
+            }
+        }
+
+        this.offset = PointAnchor.computeOffset(this.offset, this.size, this.anchor);
+    }
+
+    updateBBoxes (this: Pick<LabelPoint, 'size' | 'unit_scale' | 'position' | 'offset' | 'angle' | 'obb' | 'aabb' | 'breach' | 'may_repeat_across_tiles'> & {layout: Pick<LabelLayout, 'buffer' | 'italic'>} & Partial<Pick<LabelPoint, 'inTileBounds' | 'mayRepeatAcrossTiles'>>) {
+        let width = (this.size[0] + this.layout.buffer[0] * 2) * this.unit_scale * Label.epsilon;
+        let height = (this.size[1] + this.layout.buffer[1] * 2) * this.unit_scale * Label.epsilon;
+
+        // fudge width value as text may overflow bounding box if it has italic, bold, etc style
+        if (this.layout.italic) {
+            width += 5 * this.unit_scale;
+        }
+
+        // make bounding boxes
+        this.obb = new OBB(
+            this.position[0] + (this.offset[0] * this.unit_scale),
+            this.position[1] - (this.offset[1] * this.unit_scale),
+            -this.angle, // angle is negative because tile system y axis is pointing down
+            width,
+            height
+        );
+        this.aabb = this.obb.getExtent();
+
+        if (this.inTileBounds) {
+            this.breach = !this.inTileBounds();
+        }
+
+        if (this.mayRepeatAcrossTiles) {
+            this.may_repeat_across_tiles = this.mayRepeatAcrossTiles();
+        }
+    }
+
+    discard (bboxes: CollisionBounds, exclude: CollisionLabel | null | 0 | '' = null) {
+        if (this.degenerate) {
+            return false;
+        }
+
+        if (super.discard(bboxes, exclude)) {
+            // If more than one anchor specified, try them in order
+            if (Array.isArray(this.layout.anchor)) {
+                // Start on second anchor (first anchor was set on creation)
+                for (let i=this.start_anchor_index; i < this.layout.anchor.length; i++) {
+                    this.anchor = this.layout.anchor[i];
+                    this.update();
+
+                    if (!super.discard(bboxes, exclude)) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+
+}
+
+// Placement strategies
+LabelPoint.PLACEMENT = {
+    VERTEX: 0,          // place labels at endpoints of line segments
+    MIDPOINT: 1,        // place labels at midpoints of line segments
+    SPACED: 2,          // place labels equally spaced along line
+    CENTROID: 3         // place labels at center of polygons
+};

package/src/labels/main-pass-types.ts

@@ -0,0 +1,73 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {CollisionLabel, CollisionObject} from './collision-types';
+import type {LabelPointCoordinate, SerializedLabel} from './label-types';
+import type OBB from '../utils/obb';
+
+/** Serialized label container attached to a worker-built mesh. */
+export interface MeshLabel {
+    container: {label: SerializedLabel; linked?: number | string | null};
+    /** Byte offset and vertex count for each label geometry range. */
+    ranges: [number, number][];
+}
+
+/** Mutable GPU-mesh surface consumed by the visibility pass. */
+export interface LabelMesh {
+    /** First terrain draw timestamp, shared with color/selection morphing. */
+    terrainVisibleAt?: number;
+    /** Last submitted height blend, for non-terrain callers and diagnostics. */
+    terrainBlend?: number;
+    /** Captured worker generation's duration; a pending field must not retime admitted labels. */
+    variant?: {terrainTransitionDuration?: number};
+    valid: boolean;
+    labels?: Record<string, MeshLabel>;
+    vertex_layout: {offset?: Record<string, number>; stride: number};
+    /** CPU bytes are absent after an unretained mesh upload or destruction. */
+    vertex_data?: import('../gl/mesh-types').MeshVertexData;
+    upload(): void;
+}
+
+/** Current/proxy tile metadata needed for cross-tile collisions. */
+export interface LabelTile {
+    coords: {z: number};
+    style_z: number;
+    build_id: number;
+    min: {x: number; y: number};
+    span: {x: number};
+    meshes: Record<string, LabelMesh[]>;
+    pending_label_meshes: Record<string, LabelMesh[]> | null;
+    isProxy(): boolean;
+    /** Whether a proxy style still draws while a child finishes its label meshes. */
+    shouldProxyForStyle?(style: string): boolean;
+    swapPendingLabels(): void;
+}
+
+/** Main-pass reconstruction: screen-scaled boxes without alternate-anchor fitting. */
+export interface MainPassLabel extends CollisionLabel {
+    id: number;
+    type: string;
+    layout: SerializedLabel['layout'] & {repeat_scale: number};
+    build_id: number;
+    unit_scale: number;
+    size: LabelPointCoordinate;
+    offset: LabelPointCoordinate;
+    angle: number;
+    obb: OBB | null;
+    aabb: number[] | null;
+    obbs: OBB[];
+    aabbs: number[][];
+}
+
+/** Resolved cross-tile candidate, including its mesh update ranges. */
+export interface MainPassContainer extends CollisionObject {
+    label: MainPassLabel;
+    ranges: [number, number][];
+    mesh: LabelMesh;
+}
+
+/** Temporary worker ID link, resolved before collision submission. */
+export type UnresolvedMainPassContainer = Omit<MainPassContainer, 'linked'> & {
+    linked?: number | string | CollisionObject | null;
+};

package/src/labels/main_pass.ts

@@ -0,0 +1,221 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {CollisionBounds, CollisionLabel} from './collision-types';
+import type {LabelTile, LabelMesh, MainPassLabel, MainPassContainer, UnresolvedMainPassContainer} from './main-pass-types';
+import Label from './label';
+import LabelPoint from './label_point';
+import {LabelLineStraight} from './label_line';
+import Collision from './collision';
+import OBB from '../utils/obb';
+import Geo from '../utils/geo';
+
+let visible: Record<string, boolean> = {};       // currently visible labels
+let prev_visible: Record<string, boolean> = {};  // previously visible labels (in last collision run)
+
+export default async function mainThreadLabelCollisionPass (tiles: LabelTile[], view_zoom: number, hide_breach = false): Promise<{labels: MainPassContainer[]; containers: MainPassContainer[]}> {
+    // Swap/reset visible label set
+    prev_visible = visible; // save last visible label set
+    visible = {};           // initialize new visible label set
+
+    // Build label containers from tiles
+    let containers = buildLabels(tiles, view_zoom);
+
+    // Collide all labels in a single group
+    // TODO: maybe rename tile and style to group/subgroup?
+    Collision.startTile('main', { apply_repeat_groups: true, return_hidden: true });
+    Collision.addStyle('main', 'main');
+
+    // Adaptive collision grid, using a heuristic based on the tile with the most labels
+    const max_tile_label_count =
+        Math.max(0, ...Object.values(tiles)
+            .map(t => Object.values(t.meshes))
+            .flat()
+            .map(meshes => Math.max(0, ...meshes.map(mesh => mesh.labels ? Object.keys(mesh.labels).length : 0)))
+        );
+
+    const grid_divs = Math.floor(max_tile_label_count / Geo.tile_size); // heuristic of label density to tile size
+    if (grid_divs > 0) {
+        Collision.initGrid({
+            anchor: { x: Math.min(...tiles.map(t => t.min.x)), y: Math.min(...tiles.map(t => t.min.y)) },
+            span: tiles[0].span.x / grid_divs
+        });
+    }
+    else {
+        Collision.initGrid();
+    }
+
+    const labels = await Collision.collide(containers, 'main', 'main');
+
+    // Update label visiblity
+    let meshes: LabelMesh[] = [];
+    labels.forEach(container => {
+        // Hide breach labels (those that cross tile boundaries) while tiles are loading, unless they
+        // were previously visible (otherwise fully loaded/collided breach labels will flicker in and out
+        // when new tiles load, even if they aren't adjacent)
+        let show = 0;
+        if (container.show === true &&
+            (!hide_breach || !container.label.breach || prev_visible[container.label.id])) {
+            show = 1;
+        }
+
+        if (show) {
+            visible[container.label.id] = true; // track visible labels
+        }
+
+        let changed = true; // check if label visibility changed on this collision pass
+
+        container.ranges.forEach(r => {
+            if (!changed) {
+                return; // skip rest of label if state hasn't changed
+            }
+
+            let mesh = container.mesh;
+            if (!mesh.valid || !mesh.vertex_data || !mesh.vertex_layout.offset) {
+                return;
+            }
+
+            let off = mesh.vertex_layout.offset.a_shape; // byte offset (within each vertex) of attribute
+            let stride = mesh.vertex_layout.stride;      // byte stride per vertex
+
+            for (let i=0; i < r[1]; i++) {
+                // NB: +6 is because attribute is a short int (2 bytes each), and we're skipping to 3rd element, 6=3*2
+                if (mesh.vertex_data[r[0] + i * stride + off + 6] === show) {
+                    changed = false;
+                    return; // label hasn't changed states, skip further updates
+                }
+                mesh.vertex_data[r[0] + i * stride + off + 6] = show;
+            }
+
+            if (meshes.indexOf(mesh) === -1) {
+                meshes.push(mesh);
+            }
+        });
+    });
+
+    // Upload updated meshes and make them visible
+    meshes.forEach(mesh => mesh.upload());
+    tiles.forEach(t => t.swapPendingLabels());
+
+    return { labels, containers }; // currently returned for debugging
+}
+
+function buildLabels (tiles: LabelTile[], view_zoom: number): MainPassContainer[] {
+    const labels: Record<string, MainPassLabel> = {};
+    let containers: Record<string, UnresolvedMainPassContainer> | UnresolvedMainPassContainer[] = {};
+
+    // Collect labels from each tile and turn into new label instances
+    tiles.forEach(tile => {
+        const units_per_meter = Geo.unitsPerMeter(tile.coords.z); // scale from tile units to mercator meters
+        const zoom_scale = Math.pow(2, view_zoom - tile.style_z); // adjust label size by view zoom
+        const size_scale = units_per_meter * zoom_scale; // scale from tile units to zoom-adjusted meters
+        const meters_per_pixel = Geo.metersPerPixel(view_zoom);
+
+        // First pass: create label instances and centralize collision containers
+        // Combine existing (previously collided) and pending (waiting to be collided for first time) meshes
+        const tile_meshes = Object.assign({}, tile.meshes, tile.pending_label_meshes);
+        for (let style in tile_meshes) {
+            const meshes = tile_meshes[style];
+            meshes.forEach(mesh => {
+                if (mesh.labels) {
+                    for (let label_id in mesh.labels) {
+                        // For proxy tiles, only allow visible labels to be *hidden* by further collisions,
+                        // don't allow new ones to appear. Promotes label stability and prevents thrash
+                        // from different labels (often not thematically relevant given the different zoom level of
+                        // the proxy tile content, e.g. random POIs popping in/out when zooming out to city-wide view).
+                        if (tile.isProxy() && !prev_visible[label_id]) {
+                            continue;
+                        }
+
+                        const params = mesh.labels[label_id].container.label;
+                        const linked = mesh.labels[label_id].container.linked;
+                        const ranges = mesh.labels[label_id].ranges;
+                        // const debug = Object.assign({}, mesh.labels[label_id].debug, { tile, params, label_id });
+
+                        // The worker snapshot and bounds are installed below before collision reads this record.
+                        let label = labels[label_id] = {} as MainPassLabel;
+                        label.discard = discard.bind(label);
+                        label.build_id = tile.build_id; // original order in which tiles were built
+
+                        Object.assign(label, params);
+                        label.layout = Object.assign({}, params.layout) as MainPassLabel['layout']; // repeat_scale is installed below
+                        label.layout.repeat_scale = 0.75; // looser second pass on repeat groups, to weed out repeats near tile edges
+                        label.layout.repeat_distance = label.layout.repeat_distance || 0;
+                        label.layout.repeat_distance /= size_scale; // TODO: where should this be scaled?
+                        label.position = [ // don't overwrite referenced values
+                            label.position[0] / units_per_meter + tile.min.x,
+                            label.position[1] / units_per_meter + tile.min.y
+                        ];
+                        label.unit_scale = meters_per_pixel;
+
+                        if (label.type === 'point') { // TODO: move to integer constants to avoid excess string copies
+                            LabelPoint.prototype.updateBBoxes.call(label);
+                        }
+                        else if (label.type === 'straight') {
+                            LabelLineStraight.prototype.updateBBoxes.call(label, label.position, label.size, label.angle, label.angle, label.offset);
+                        }
+                        else if (params.obbs) {
+                            // NB: this is a very rough approximation of curved label collision at intermediate zooms,
+                            // because the position/scale of each collision box isn't correctly updated; however,
+                            // it's good enough to provide some additional label coverage, with less overhead
+                            const obbs = params.obbs.map(o => {
+                                let { x, y, a, w, h } = o;
+                                x = x / units_per_meter + tile.min.x;
+                                y = y / units_per_meter + tile.min.y;
+                                w /= size_scale;
+                                h /= size_scale;
+                                return new OBB(x, y, a, w, h);
+                            });
+                            label.obbs = obbs;
+                            label.aabbs = obbs.map(o => o.getExtent());
+                        }
+
+                        (containers as Record<string, UnresolvedMainPassContainer>)[label_id] = {
+                            label,
+                            linked,
+                            ranges,
+                            mesh,
+                            // debug
+                        };
+                    }
+                }
+            });
+        }
+    });
+
+    // Resolve links between label containers
+    for (let c in containers) {
+        const container = containers[c];
+        if (container.linked) {
+            container.linked = containers[container.linked as string] as MainPassContainer;
+        }
+        // NB: if linked label not found, it was discarded in initial tile collision pass
+    }
+
+    // Convert container map to array
+    containers = Object.keys(containers).map(k => (containers as Record<string, UnresolvedMainPassContainer>)[k]);
+    return containers as MainPassContainer[];
+}
+
+// Generic discard function for labels, does simple occlusion with one or more bounding boxes
+// (no additional logic to try alternate anchors or other layout options, etc.)
+function discard (this: MainPassLabel, bboxes: CollisionBounds, exclude: CollisionLabel | null | 0 | '' = null): boolean {
+    if (this.obb) { // single collision box
+        return Label.prototype.occluded.call(this, bboxes, exclude);
+    }
+    else if (this.obbs) { // mutliple collision boxes
+        for (let i = 0; i < this.obbs.length; i++){
+            let aabb = this.aabbs[i];
+            let obb = this.obbs[i];
+            let obj = { aabb, obb };
+
+            let should_discard = Label.prototype.occluded.call(obj, bboxes, exclude);
+            if (should_discard) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/src/labels/point_anchor.ts

@@ -0,0 +1,100 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Sets of values to match for directional and corner anchors
+const lefts = ['left', 'top-left', 'bottom-left'];
+const rights = ['right', 'top-right', 'bottom-right'];
+const tops = ['top', 'top-left', 'top-right'];
+const bottoms = ['bottom', 'bottom-left', 'bottom-right'];
+
+type AnchorName = string | string[] | undefined;
+type Point = [number, number];
+type Buffer = [number, number, number, number];
+interface PointAnchorNamespace {
+    computeOffset(offset: Point, size: Point, anchor: AnchorName, buffer?: Buffer | null): Point;
+    alignForAnchor(anchor: AnchorName): string;
+    isLeftAnchor(anchor: AnchorName): boolean;
+    isRightAnchor(anchor: AnchorName): boolean;
+    isTopAnchor(anchor: AnchorName): boolean;
+    isBottomAnchor(anchor: AnchorName): boolean;
+    default_buffer: Buffer;
+    zero_buffer: Buffer;
+}
+const PointAnchor = {
+
+    computeOffset (offset: Point, size: Point, anchor: AnchorName, buffer: Buffer | null = null): Point {
+        if (!anchor || anchor === 'center') {
+            return offset;
+        }
+
+        const offset2: Point = [offset[0], offset[1]];
+        buffer = buffer || this.default_buffer;
+
+        // An optional left/right offset
+        if (this.isLeftAnchor(anchor)) {
+            offset2[0] -= size[0] / 2;
+            if (anchor === 'left') {
+                offset2[0] -= buffer[0];
+            }
+        }
+        else if (this.isRightAnchor(anchor)) {
+            offset2[0] += size[0] / 2;
+            if (anchor === 'right') {
+                offset2[0] += buffer[1];
+            }
+        }
+
+        // An optional top/bottom offset
+        if (this.isTopAnchor(anchor)) {
+            offset2[1] -= size[1] / 2;
+            if (anchor === 'top') {
+                offset2[1] -= buffer[2];
+            }
+        }
+        else if (this.isBottomAnchor(anchor)) {
+            offset2[1] += size[1] / 2;
+            if (anchor === 'bottom') {
+                offset2[1] += buffer[3];
+            }
+        }
+
+        return offset2;
+    },
+
+    alignForAnchor (anchor: AnchorName): string {
+        if (anchor && anchor !== 'center') {
+            if (this.isLeftAnchor(anchor)) {
+                return 'right';
+            }
+            else if (this.isRightAnchor(anchor)) {
+                return 'left';
+            }
+        }
+        return 'center';
+    },
+
+    isLeftAnchor (anchor: AnchorName): boolean {
+        return (lefts.indexOf(typeof anchor === 'string' ? anchor : '') > -1);
+    },
+
+    isRightAnchor (anchor: AnchorName): boolean {
+        return (rights.indexOf(typeof anchor === 'string' ? anchor : '') > -1);
+    },
+
+    isTopAnchor (anchor: AnchorName): boolean {
+        return (tops.indexOf(typeof anchor === 'string' ? anchor : '') > -1);
+    },
+
+    isBottomAnchor (anchor: AnchorName): boolean {
+        return (bottoms.indexOf(typeof anchor === 'string' ? anchor : '') > -1);
+    },
+
+    // Buffers: [left, right, top, bottom]
+    default_buffer: [2.5, 2.5, 1.5, 0.75],
+    zero_buffer: [0, 0, 0, 0]
+
+} as PointAnchorNamespace;
+
+export default PointAnchor;

package/src/labels/point_placement.ts

@@ -0,0 +1,150 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Logic for placing point labels along a line geometry
+
+import LabelPoint from './label_point';
+import type {LabelLayout} from './label-types';
+import {isCoordOutsideTile} from '../builders/common';
+
+const PLACEMENT = LabelPoint.PLACEMENT;
+const default_spacing = 80; // spacing of points along line in pixels
+type Point = [number, number];
+type PlacementLayout = LabelLayout;
+type PlacementResult = {positions: Point[]; angles: number[]};
+
+export default function placePointsOnLine (line: Point[], size: Point, layout: PlacementLayout): LabelPoint[] {
+    const labels: LabelPoint[] = [];
+    const strategy = layout.placement;
+    const min_length = Math.max(size[0], size[1])  * Number(layout.placement_min_length_ratio) * layout.units_per_pixel;
+
+    if (strategy === PLACEMENT.SPACED) {
+        let result = getPositionsAndAngles(line, min_length, layout);
+        // false will be returned if line have no length
+        if (!result) {
+            return [];
+        }
+
+        let positions = result.positions;
+        let angles = result.angles;
+        for (let i = 0; i < positions.length; i++) {
+            let position = positions[i];
+            let angle = angles[i];
+            if (layout.tile_edges === true || !isCoordOutsideTile(position)) {
+                labels.push(new LabelPoint(position, size, layout, angle));
+            }
+        }
+    }
+    else if (strategy === PLACEMENT.VERTEX) {
+        let p, q;
+        for (let i = 0; i < line.length - 1; i++) {
+            p = line[i];
+            q = line[i + 1];
+            if (layout.tile_edges === true || !isCoordOutsideTile(p)) {
+                const angle = getAngle(p as Point, q as Point, layout.angle);
+                labels.push(new LabelPoint(p as Point, size, layout, angle));
+            }
+        }
+
+        // add last endpoint
+        const angle = getAngle(p as Point, q as Point, layout.angle);
+        labels.push(new LabelPoint(q as Point, size, layout, angle));
+    }
+    else if (strategy === PLACEMENT.MIDPOINT) {
+        for (let i = 0; i < line.length - 1; i++) {
+            let p = line[i];
+            let q = line[i + 1];
+            let position = [
+                0.5 * (p[0] + q[0]),
+                0.5 * (p[1] + q[1])
+            ];
+            if (layout.tile_edges === true || !isCoordOutsideTile(position)) {
+                if (!min_length || norm(p, q) > min_length) {
+                    const angle = getAngle(p, q, layout.angle);
+                labels.push(new LabelPoint(position as Point, size, layout, angle));
+                }
+            }
+        }
+    }
+    return labels;
+}
+
+function getPositionsAndAngles(line: Point[], min_length: number, layout: PlacementLayout): PlacementResult | false {
+    let upp = layout.units_per_pixel;
+    let spacing = (layout.placement_spacing || default_spacing) * upp;
+
+    let length = getLineLength(line);
+    if (length <= min_length) {
+        return false;
+    }
+
+    let num_labels = Math.max(Math.floor(length / spacing), 1);
+    let remainder = length - (num_labels - 1) * spacing;
+    let positions: Point[] = [];
+    let angles: number[] = [];
+
+    let distance = 0.5 * remainder;
+    for (let i = 0; i < num_labels; i++) {
+        let {position, angle} = interpolateLine(line, distance, min_length, layout);
+        if (position != null && angle != null) {
+            positions.push(position);
+            angles.push(angle);
+        }
+        distance += spacing;
+    }
+
+    return {positions, angles};
+}
+
+function getAngle(p: Point, q: Point, angle: number | 'auto' = 0): number {
+    return (angle === 'auto') ? Math.atan2(q[0] - p[0], q[1] - p[1]) : angle;
+}
+
+function getLineLength(line: Point[]): number {
+    let distance = 0;
+    for (let i = 0; i < line.length - 1; i++) {
+        distance += norm(line[i], line[i+1]);
+    }
+    return distance;
+}
+
+function norm(p: Point, q: Point): number {
+    return Math.sqrt(Math.pow(p[0] - q[0], 2) + Math.pow(p[1] - q[1], 2));
+}
+
+// TODO: can be optimized.
+// you don't have to start from the first index every time for placement
+function interpolateLine(line: Point[], distance: number, min_length: number, layout: PlacementLayout): {position?: Point; angle?: number} {
+    let sum = 0;
+    let position: Point | undefined;
+    let angle: number | undefined;
+    for (let i = 0; i < line.length-1; i++) {
+        let p = line[i];
+        let q = line[i+1];
+
+        const length = norm(p, q);
+        if (length <= min_length) {
+            continue;
+        }
+
+        sum += length;
+
+        if (sum > distance) {
+            position = interpolateSegment(p, q, sum - distance);
+            angle = getAngle(p, q, layout.angle);
+            break;
+        }
+    }
+    return {position, angle};
+}
+
+function interpolateSegment(p: Point, q: Point, distance: number): Point {
+    let length = norm(p, q);
+    let ratio = distance / length;
+    return [
+        ratio * p[0] + (1 - ratio) * q[0],
+        ratio * p[1] + (1 - ratio) * q[1]
+    ];
+}