@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/layouts/GranularRectLayout.js

@@ -1,418 +1,161 @@
-const maxFeaturePitchWidth = 20000;
+import { findInsertionPoint, insertInterval } from './intervalUtils.js';
+/**
+ * See https://github.com/cmdcolin/track_layout_benchmark for information on
+ * alternative algorithms and benchmark information
+ */
+// One row's occupied spans, as a flat [start1, end1, start2, end2, ...] array
+// kept sorted by start. Spans within a row never overlap, which is what lets
+// the collision scan binary-search it.
 class LayoutRow {
     padding = 1;
-    allFilled;
     intervals = [];
-    data = [];
-    setAllFilled(data) {
-        this.allFilled = data;
-    }
     getIntervals() {
         return this.intervals;
     }
-    getItemAt(x) {
-        if (this.allFilled) {
-            return this.allFilled;
-        }
-        const intervals = this.intervals;
-        const len = intervals.length;
-        if (len === 0) {
-            return undefined;
-        }
-        if (len < 40) {
-            for (let i = 0; i < len; i += 2) {
-                if (x >= intervals[i] && x < intervals[i + 1]) {
-                    return this.data[i >> 1];
-                }
-            }
-            return undefined;
-        }
-        let low = 0;
-        let high = len >> 1;
-        while (low < high) {
-            const mid = (low + high) >>> 1;
-            const midIdx = mid << 1;
-            if (intervals[midIdx + 1] <= x) {
-                low = mid + 1;
-            }
-            else {
-                high = mid;
-            }
-        }
-        const idx = low << 1;
-        if (idx < len && x >= intervals[idx] && x < intervals[idx + 1]) {
-            return this.data[low];
-        }
-        return undefined;
-    }
-    isRangeClear(left, right) {
-        if (this.allFilled) {
-            return false;
-        }
-        const intervals = this.intervals;
-        const len = intervals.length;
-        if (len === 0) {
-            return true;
-        }
-        if (len < 40) {
-            for (let i = 0; i < len; i += 2) {
-                const start = intervals[i];
-                const end = intervals[i + 1];
-                if (end > left && start < right) {
-                    return false;
-                }
-            }
-            return true;
-        }
-        let low = 0;
-        let high = len >> 1;
-        while (low < high) {
-            const mid = (low + high) >>> 1;
-            const midIdx = mid << 1;
-            if (intervals[midIdx + 1] <= left) {
-                low = mid + 1;
-            }
-            else {
-                high = mid;
-            }
-        }
-        const idx = low << 1;
-        if (idx >= len) {
-            return true;
-        }
-        const start = intervals[idx];
-        if (start >= right) {
-            return true;
-        }
-        return false;
-    }
-    addRect(rect, data) {
+    addRect(rect) {
         const left = rect.l;
         const right = rect.r + this.padding;
         const intervals = this.intervals;
         const len = intervals.length;
-        if (len < 40) {
-            let idx = len;
-            for (let i = 0; i < len; i += 2) {
-                if (left < intervals[i]) {
-                    idx = i;
-                    break;
-                }
-            }
-            intervals.splice(idx, 0, left, right);
-            this.data.splice(idx >> 1, 0, data);
+        // Fast path: features usually arrive sorted, so append to the end
+        if (len === 0 || left >= intervals[len - 2]) {
+            intervals.push(left, right);
         }
         else {
-            let low = 0;
-            let high = len >> 1;
-            while (low < high) {
-                const mid = (low + high) >>> 1;
-                const midIdx = mid << 1;
-                if (intervals[midIdx] < left) {
-                    low = mid + 1;
-                }
-                else {
-                    high = mid;
-                }
-            }
-            intervals.splice(low << 1, 0, left, right);
-            this.data.splice(low, 0, data);
+            insertInterval(intervals, findInsertionPoint(intervals, left), left, right);
         }
     }
-    discardRange(left, right) {
-        if (this.allFilled) {
-            return;
-        }
-        const intervals = this.intervals;
-        const data = this.data;
-        const oldLen = intervals.length;
-        const newIntervals = [];
-        const newData = [];
-        for (let i = 0; i < oldLen; i += 2) {
-            const start = intervals[i];
-            const end = intervals[i + 1];
-            const intervalData = data[i >> 1];
-            if (start >= left && end <= right) {
-                continue;
-            }
-            if (end <= left || start >= right) {
-                newIntervals.push(start, end);
-                newData.push(intervalData);
-            }
-            else if (start < left && end > left) {
-                if (end <= right) {
-                    newIntervals.push(start, left);
-                    newData.push(intervalData);
-                }
-                else {
-                    newIntervals.push(start, left, right, end);
-                    newData.push(intervalData, intervalData);
-                }
-            }
-            else if (start < right && end > right) {
-                newIntervals.push(right, end);
-                newData.push(intervalData);
-            }
-        }
-        this.intervals = newIntervals;
-        this.data = newData;
-    }
 }
 export default class GranularRectLayout {
     pitchX;
     pitchY;
     hardRowLimit;
+    // sparse: rows are created lazily as rects land on them and first-fit scans
+    // rows beyond the highest created one, so every access must guard for undefined
     bitmap;
     rectangles;
-    maxHeightReached;
     maxHeight;
-    displayMode;
-    pTotalHeight;
-    constructor({ pitchX = 10, pitchY = 10, maxHeight = 10000, hardRowLimit = 10000, displayMode = 'normal', } = {}) {
+    /**
+     * pitchX - layout grid pitch in the X direction
+     * pitchY - layout grid pitch in the Y direction
+     * maxHeight - maximum layout height in pixels, default 10000
+     */
+    constructor({ pitchX = 10, pitchY = 10, maxHeight = 10000, hardRowLimit = 10000, } = {}) {
         this.pitchX = pitchX;
         this.pitchY = pitchY;
         this.hardRowLimit = hardRowLimit;
-        this.maxHeightReached = false;
-        this.displayMode = displayMode;
-        if (this.displayMode === 'compact') {
-            this.pitchY = Math.round(this.pitchY / 4) || 1;
-            this.pitchX = Math.round(this.pitchX / 4) || 1;
-        }
         this.bitmap = [];
         this.rectangles = new Map();
         this.maxHeight = Math.ceil(maxHeight / this.pitchY);
-        this.pTotalHeight = 0;
     }
-    addRect(id, left, right, height, data, serializableData, startingRow) {
+    /**
+     * @returns top position for the rect, or Null if laying
+     *  out the rect would exceed maxHeight
+     */
+    addRect(id, left, right, height) {
         const pitchX = this.pitchX;
         const pitchY = this.pitchY;
+        // if we have already laid it out, return its layout
         const storedRec = this.rectangles.get(id);
         if (storedRec) {
-            if (serializableData !== undefined) {
-                storedRec.serializableData = serializableData;
-            }
-            if (storedRec.top === null) {
-                return null;
-            }
-            this.addRectToBitmap(storedRec);
-            return storedRec.top * pitchY;
+            return storedRec.top === null ? null : storedRec.top * pitchY;
         }
+        // Use Math.trunc for fast floor operation that works with large coordinates
+        // (bitwise | 0 overflows above 2^31, causing layout issues with large genomic coordinates)
         const pLeft = Math.trunc(left / pitchX);
         const pRight = Math.trunc(right / pitchX);
         const pHeight = Math.ceil(height / pitchY);
         const rectangle = {
-            id,
             l: pLeft,
             r: pRight,
             top: null,
             h: pHeight,
-            originalHeight: height,
-            data,
-            serializableData,
         };
+        // Allow features to start at any position up to maxHeight
+        // Features starting at maxHeight or beyond are filtered out, but features
+        // that start below maxHeight and extend past it are allowed
         const maxTop = this.maxHeight;
-        let top = startingRow !== undefined
-            ? Math.min(Math.floor(startingRow / pitchY), maxTop)
-            : 0;
-        if (this.displayMode !== 'collapse') {
-            const bitmap = this.bitmap;
-            outer: for (; top <= maxTop; top += 1) {
-                const maxY = top + pHeight;
-                for (let y = top; y < maxY; y += 1) {
-                    const row = bitmap[y];
-                    if (!row) {
-                        continue;
-                    }
-                    if (row.allFilled) {
-                        continue outer;
-                    }
-                    const intervals = row.getIntervals();
-                    const len = intervals.length;
-                    if (len > 0) {
-                        if (len < 40) {
-                            for (let i = 0; i < len; i += 2) {
-                                const start = intervals[i];
-                                const end = intervals[i + 1];
-                                if (end > pLeft && start < pRight) {
-                                    continue outer;
-                                }
+        let top = 0;
+        // OPTIMIZATION: Inline collision checking for hot path
+        // Eliminates function call overhead which is critical at 100k+ features
+        const bitmap = this.bitmap;
+        // On a collision at row y, the next top worth trying is y + 1, not top + 1.
+        // Rows top..y-1 are clear (y is the first hit walking upward) and every top'
+        // between them still spans y, because y < top + pHeight — so nothing between
+        // can fit. `top = y` plus the loop's own increment is that jump, and it turns
+        // the scan from O(rows * pHeight) into O(rows): without it, a rect pHeight
+        // rows tall re-tests the row that blocked it pHeight times over.
+        outer: for (; top <= maxTop; top += 1) {
+            // Check all rows that this rectangle would occupy
+            const maxY = top + pHeight;
+            for (let y = top; y < maxY; y += 1) {
+                const row = bitmap[y];
+                // Fast path: no row created yet
+                if (!row) {
+                    continue;
+                }
+                const intervals = row.getIntervals();
+                const len = intervals.length;
+                if (len > 0) {
+                    if (len < 40) {
+                        // Linear scan for small arrays
+                        for (let i = 0; i < len; i += 2) {
+                            const start = intervals[i];
+                            const end = intervals[i + 1];
+                            if (end > pLeft && start < pRight) {
+                                top = y;
+                                continue outer;
                             }
                         }
-                        else {
-                            let low = 0;
-                            let high = len >> 1;
-                            while (low < high) {
-                                const mid = (low + high) >>> 1;
-                                const midIdx = mid << 1;
-                                if (intervals[midIdx + 1] <= pLeft) {
-                                    low = mid + 1;
-                                }
-                                else {
-                                    high = mid;
-                                }
+                    }
+                    else {
+                        // Binary search for larger arrays
+                        let low = 0;
+                        let high = len >> 1;
+                        while (low < high) {
+                            const mid = (low + high) >>> 1;
+                            const midIdx = mid << 1;
+                            if (intervals[midIdx + 1] <= pLeft) {
+                                low = mid + 1;
                             }
-                            const idx = low << 1;
-                            if (idx < len) {
-                                const start = intervals[idx];
-                                if (start < pRight) {
-                                    continue outer;
-                                }
+                            else {
+                                high = mid;
+                            }
+                        }
+                        const idx = low << 1;
+                        if (idx < len) {
+                            const start = intervals[idx];
+                            if (start < pRight) {
+                                top = y;
+                                continue outer;
                             }
                         }
                     }
                 }
-                break;
-            }
-            if (top > maxTop) {
-                rectangle.top = null;
-                this.rectangles.set(id, rectangle);
-                this.maxHeightReached = true;
-                return null;
             }
+            // No collision found in any row
+            break;
         }
-        rectangle.top = top;
-        this.addRectToBitmap(rectangle);
         this.rectangles.set(id, rectangle);
-        this.pTotalHeight = Math.max(this.pTotalHeight || 0, top + pHeight);
-        return top * pitchY;
-    }
-    collides(rect, top) {
-        const { bitmap } = this;
-        const maxY = top + rect.h;
-        for (let y = top; y < maxY; y += 1) {
-            const row = bitmap[y];
-            if (row !== undefined && !row.isRangeClear(rect.l, rect.r)) {
-                return true;
-            }
-        }
-        return false;
-    }
-    addRectToBitmap(rect) {
-        if (rect.top === null) {
-            return;
+        if (top > maxTop) {
+            return null;
         }
-        const data = rect.id;
-        const yEnd = rect.top + rect.h;
-        const bitmap = this.bitmap;
-        const hardRowLimit = this.hardRowLimit;
-        const pitchY = this.pitchY;
-        if (rect.r - rect.l > maxFeaturePitchWidth) {
-            for (let y = rect.top; y < yEnd; y += 1) {
-                let row = bitmap[y];
-                if (!row) {
-                    if (y > hardRowLimit) {
-                        throw new Error(`layout hard limit (${hardRowLimit * pitchY}px) exceeded, aborting layout`);
-                    }
-                    row = new LayoutRow();
-                    bitmap[y] = row;
-                }
-                row.setAllFilled(data);
-            }
-        }
-        else {
-            for (let y = rect.top; y < yEnd; y += 1) {
-                let row = bitmap[y];
-                if (!row) {
-                    if (y > hardRowLimit) {
-                        throw new Error(`layout hard limit (${hardRowLimit * pitchY}px) exceeded, aborting layout`);
-                    }
-                    row = new LayoutRow();
-                    bitmap[y] = row;
-                }
-                row.addRect(rect, data);
-            }
-        }
-    }
-    discardRange(left, right) {
-        const pLeft = Math.trunc(left / this.pitchX);
-        const pRight = Math.trunc(right / this.pitchX);
-        const { bitmap } = this;
-        for (const row of bitmap) {
-            row.discardRange(pLeft, pRight);
+        rectangle.top = top;
+        const yEnd = top + pHeight;
+        for (let y = top; y < yEnd; y += 1) {
+            this.getOrCreateRow(y).addRect(rectangle);
         }
+        return top * pitchY;
     }
-    hasSeen(id) {
-        return this.rectangles.has(id);
-    }
-    getByCoord(x, y) {
-        const pY = Math.trunc(y / this.pitchY);
-        const row = this.bitmap[pY];
+    getOrCreateRow(y) {
+        let row = this.bitmap[y];
         if (!row) {
-            return undefined;
-        }
-        const pX = Math.trunc(x / this.pitchX);
-        return row.getItemAt(pX);
-    }
-    getByID(id) {
-        const r = this.rectangles.get(id);
-        if (r) {
-            const t = r.top * this.pitchY;
-            return [
-                r.l * this.pitchX,
-                t,
-                r.r * this.pitchX,
-                t + r.originalHeight,
-            ];
-        }
-        return undefined;
-    }
-    getDataByID(id) {
-        return this.rectangles.get(id)?.data;
-    }
-    getSerializableDataByID(id) {
-        return this.rectangles.get(id)?.serializableData;
-    }
-    cleanup() { }
-    getTotalHeight() {
-        return this.pTotalHeight * this.pitchY;
-    }
-    get totalHeight() {
-        return this.getTotalHeight();
-    }
-    getRectangles() {
-        const pitchX = this.pitchX;
-        const pitchY = this.pitchY;
-        return new Map([...this.rectangles.entries()].map(([id, rect]) => {
-            const { l, r, originalHeight, top, serializableData } = rect;
-            const t = (top || 0) * pitchY;
-            const b = t + originalHeight;
-            return [id, [l * pitchX, t, r * pitchX, b, serializableData]];
-        }));
-    }
-    serializeRegion(region) {
-        const pitchX = this.pitchX;
-        const pitchY = this.pitchY;
-        const x1 = region.start;
-        const x2 = region.end;
-        const regionRectangles = {};
-        let maxHeightReached = false;
-        for (const [id, rect] of this.rectangles.entries()) {
-            const { l, r, originalHeight, top } = rect;
-            if (top === null) {
-                maxHeightReached = true;
-            }
-            else {
-                const t = top * pitchY;
-                const b = t + originalHeight;
-                const y1 = l * pitchX;
-                const y2 = r * pitchX;
-                if (x2 >= y1 - pitchX && y2 + pitchX >= x1) {
-                    regionRectangles[id] = [y1, t, y2, b, rect.serializableData];
-                }
+            if (y > this.hardRowLimit) {
+                throw new Error(`layout hard limit (${this.hardRowLimit * this.pitchY}px) exceeded, aborting layout`);
             }
+            row = new LayoutRow();
+            this.bitmap[y] = row;
         }
-        return {
-            rectangles: regionRectangles,
-            totalHeight: this.getTotalHeight(),
-            maxHeightReached,
-        };
-    }
-    toJSON() {
-        const rectangles = Object.fromEntries(this.getRectangles());
-        return {
-            rectangles,
-            totalHeight: this.getTotalHeight(),
-            maxHeightReached: this.maxHeightReached,
-        };
+        return row;
     }
 }

package/esm/util/layouts/index.d.ts

@@ -1,8 +1,2 @@
-export * from './BaseLayout.ts';
 export { default as GranularRectLayout } from './GranularRectLayout.ts';
-export { default as MultiLayout } from './MultiLayout.ts';
-export { default as PileupLayout } from './PileupLayout.ts';
-export type { PileupLayoutOptions, PileupRectangle } from './PileupLayout.ts';
-export { default as PrecomputedLayout } from './PrecomputedLayout.ts';
-export type { Layout } from './PrecomputedLayout.ts';
-export { default as SceneGraph } from './SceneGraph.ts';
+export { placeRect } from './placeRect.ts';

package/esm/util/layouts/index.js

@@ -1,6 +1,2 @@
-export * from "./BaseLayout.js";
-export { default as GranularRectLayout } from "./GranularRectLayout.js";
-export { default as MultiLayout } from "./MultiLayout.js";
-export { default as PileupLayout } from "./PileupLayout.js";
-export { default as PrecomputedLayout } from "./PrecomputedLayout.js";
-export { default as SceneGraph } from "./SceneGraph.js";
+export { default as GranularRectLayout } from './GranularRectLayout.js';
+export { placeRect } from './placeRect.js';

package/esm/util/layouts/intervalUtils.d.ts

@@ -1,3 +1,14 @@
-export declare function isRangeClear(intervals: number[], left: number, right: number): boolean;
+/**
+ * Shared utilities for interval-based layout algorithms, used by
+ * GranularRectLayout.
+ */
+/**
+ * Find insertion point for a new interval in a sorted interval array.
+ * Returns the index where [left, right] should be inserted.
+ */
 export declare function findInsertionPoint(intervals: number[], left: number): number;
+/**
+ * Insert an interval into a sorted interval array using manual shift
+ * (avoids splice GC pressure).
+ */
 export declare function insertInterval(intervals: number[], idx: number, left: number, right: number): void;

package/esm/util/layouts/intervalUtils.js

@@ -1,34 +1,11 @@
-export function isRangeClear(intervals, left, right) {
-    const len = intervals.length;
-    if (len === 0) {
-        return true;
-    }
-    if (len < 40) {
-        for (let i = 0; i < len; i += 2) {
-            if (intervals[i + 1] > left && intervals[i] < right) {
-                return false;
-            }
-        }
-        return true;
-    }
-    let low = 0;
-    let high = len >> 1;
-    while (low < high) {
-        const mid = (low + high) >>> 1;
-        const midIdx = mid << 1;
-        if (intervals[midIdx + 1] <= left) {
-            low = mid + 1;
-        }
-        else {
-            high = mid;
-        }
-    }
-    const idx = low << 1;
-    if (idx >= len) {
-        return true;
-    }
-    return intervals[idx] >= right;
-}
+/**
+ * Shared utilities for interval-based layout algorithms, used by
+ * GranularRectLayout.
+ */
+/**
+ * Find insertion point for a new interval in a sorted interval array.
+ * Returns the index where [left, right] should be inserted.
+ */
 export function findInsertionPoint(intervals, left) {
     const len = intervals.length;
     if (len < 40) {
@@ -39,6 +16,7 @@ export function findInsertionPoint(intervals, left) {
         }
         return len;
     }
+    // Binary search
     let low = 0;
     let high = len >> 1;
     while (low < high) {
@@ -52,6 +30,10 @@ export function findInsertionPoint(intervals, left) {
     }
     return low << 1;
 }
+/**
+ * Insert an interval into a sorted interval array using manual shift
+ * (avoids splice GC pressure).
+ */
 export function insertInterval(intervals, idx, left, right) {
     const len = intervals.length;
     intervals.push(0, 0);

package/esm/util/layouts/placeRect.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal row-packing primitive for integer-indexed 1D layouts.
+ *
+ * `rows[y]` is a flat `[s1,e1,s2,e2,...]` sorted ascending by start, where
+ * intervals within a row never overlap. `placeRect` finds the first row
+ * with no collision (or appends a new row), inserts `[start, end+2]`,
+ * and returns the row INDEX (0, 1, 2, ...).
+ *
+ * How this differs from `GranularRectLayout` in this same folder, and
+ * why this exists as a separate primitive:
+ *
+ * - **Keys:** GranularRectLayout keys rectangles by string ID in a
+ *   `Map`, so re-adding an id returns the row it already holds;
+ *   `placeRect` has no ID and no rectangle object. Callers with numeric
+ *   indices (e.g. BAM read indices) don't pay the cost of allocating
+ *   string IDs, Rectangle objects, or the outer Map — they use a
+ *   `Uint16Array` of row indices instead.
+ *
+ * - **Scaling / height:** GranularRectLayout has `pitchX`, `pitchY`,
+ *   multi-row rectangle heights, `maxHeight` / `hardRowLimit`, and
+ *   returns pixel `top` values. `placeRect` is unit-agnostic (bp or
+ *   px), one-row-per-rect, no limits, and returns a row index.
+ *
+ * - **State ownership:** GranularRectLayout is a class with internal
+ *   state; `placeRect` is a pure function operating on a caller-owned
+ *   `number[][]` array, so memory lifetime matches the caller's scope.
+ *
+ * Neither hit-tests: both are packing only, and consumers that need
+ * hit-testing build a Flatbush over the result.
+ *
+ * Use `placeRect` for tight per-call layouts over typed-array data
+ * (alignments pileup and chain rendering). Use `GranularRectLayout`
+ * when rects have variable heights or the layout needs a row limit
+ * (feature/gene tracks).
+ *
+ * Per-row complexity:
+ *   - O(1) append when the row's last end ≤ new start (start-sorted
+ *     input — the common case)
+ *   - O(log M) collision + insertion-point lookup for wide rows via
+ *     binary search on ends. Ends are monotone within a row because
+ *     intervals are non-overlapping and sorted by start.
+ *   - O(M) for the splice shift when inserting mid-row; only taken
+ *     once per placement, and only when the fast-path misses.
+ *
+ * @param rows  mutable `number[][]` — each row is `[s1,e1,s2,e2,...]`
+ * @param start rect start (any numeric unit — bp, px, etc.)
+ * @param end   rect end (exclusive)
+ * @returns     the row index the rect was placed in
+ */
+export declare function placeRect(rows: number[][], start: number, end: number): number;