@itwin/core-geometry 4.4.0-dev.9 → 4.5.0-dev.0

package/lib/esm/polyface/RangeTree/PolyfaceRangeTreeContext.js

@@ -0,0 +1,80 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module RangeSearch
+ */
+import { Geometry } from "../../Geometry";
+import { Polyface } from "../Polyface";
+import { PolyfaceQuery } from "../PolyfaceQuery";
+import { RangeTreeNode, RangeTreeOps } from "./RangeTreeNode";
+import { SingleTreeSearchHandlerForClosestPointOnPolyface, TwoTreeSearchHandlerForFacetFacetCloseApproach } from "./RangeTreeSearchHandlers";
+/**
+ * Handler class for searching a range tree containing the facets of a polyface.
+ * * Facilitates multiple searches for closest point and close approach calculations.
+ * @public
+ */
+export class PolyfaceRangeTreeContext {
+    /** Constructor: capture inputs, initialize debug counters */
+    constructor(rangeTreeRoot, visitor, convexFacets = false) {
+        this.visitor = visitor;
+        this.convexFacets = convexFacets;
+        this._rangeTreeRoot = rangeTreeRoot;
+        this.numRangeTestTrue = 0;
+        this.numRangeTestFalse = 0;
+        this.numFacetTest = 0;
+        this.numSearch = 0;
+    }
+    /**
+     * Create a range tree context for the Polyface facets.
+     * * This is a very simple construction that splits "right and left parts" of the facet sequence.
+     * * Facets with any recognizable "left to right" or "top to bottom" sequencing will have very effective search structures.
+     * @param visitor access to facets, captured if PolyfaceVisitor
+     * @param maxChildPerNode maximum children per range tree node (default 4)
+     * @param maxAppDataPerLeaf maximum facet indices per leaf node (default 4)
+     * @param convexFacets whether all facets are known to be convex (cf. [[PolyfaceQuery.areFacetsConvex]]) (default false)
+     */
+    static createCapture(visitor, maxChildPerNode = 4, maxAppDataPerLeaf = 4, convexFacets = false) {
+        if (visitor instanceof Polyface)
+            return this.createCapture(visitor.createVisitor(0), maxChildPerNode, maxAppDataPerLeaf, convexFacets);
+        const numFacet = PolyfaceQuery.visitorClientFacetCount(visitor);
+        const rangeTreeRoot = RangeTreeOps.createByIndexSplits((index) => { visitor.moveToReadIndex(index); return visitor.range(); }, (index) => { return index; }, numFacet, maxChildPerNode, maxAppDataPerLeaf);
+        return rangeTreeRoot ? new PolyfaceRangeTreeContext(rangeTreeRoot, visitor, convexFacets) : undefined;
+    }
+    /**
+     * Search the range tree for closest facet(s) to spacePoint.
+     * @param spacePoint point to test
+     * @param maxDist collect points at no more than this distance from spacePoint. If undefined, return only the closest point.
+     * @param searchFacetInterior whether to include facet interiors in search. Default is false: just consider facet boundaries.
+     * @return closest point detail(s) with detail.a set to the distance from spacePoint to detail.point
+     */
+    searchForClosestPoint(spacePoint, maxDist, searchFacetInterior = false) {
+        const handler = new SingleTreeSearchHandlerForClosestPointOnPolyface(spacePoint, this, maxDist, searchFacetInterior);
+        this.numSearch++;
+        const numFacet = PolyfaceQuery.visitorClientFacetCount(this.visitor);
+        // seed the search with a few points -- this reduces early trips deep into early ranges that are far from spacePoint.
+        const numTest = Geometry.clamp(Math.floor(numFacet / 20), 2, 7);
+        const testStep = Math.floor(numFacet / numTest);
+        handler.processAppData(0);
+        handler.processAppData(numFacet - 1);
+        for (let i = testStep; i + 1 < numFacet; i += testStep)
+            handler.processAppData(i);
+        this._rangeTreeRoot.searchTopDown(handler);
+        return handler.searchState.savedItems.length <= 1 ? handler.getResult() : handler.getSavedItems();
+    }
+    /**
+     * Search the range trees for closest approach(es) between the polyfaces.
+     * @param contextA first polyface context
+     * @param contextB second polyface context
+     * @param maxDist collect close approaches separated by no more than this distance. If undefined, return only the closest approach.
+     * @param searchFacetInterior whether to include facet interiors in search (`context.convexFacets` must be true for both contexts). Default is false: just consider facet boundaries.
+     * @return closest approach detail pair(s), one per context, with detail.a set to the approach distance
+    */
+    static searchForClosestApproach(contextA, contextB, maxDist, searchFacetInterior = false) {
+        const handler = new TwoTreeSearchHandlerForFacetFacetCloseApproach(contextA, contextB, maxDist, searchFacetInterior);
+        RangeTreeNode.searchTwoTreesTopDown(contextA._rangeTreeRoot, contextB._rangeTreeRoot, handler);
+        return handler.searchState.savedItems.length <= 1 ? handler.getResult() : handler.getSavedItems();
+    }
+}
+//# sourceMappingURL=PolyfaceRangeTreeContext.js.map

package/lib/esm/polyface/RangeTree/PolyfaceRangeTreeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolyfaceRangeTreeContext.js","sourceRoot":"","sources":["../../../../src/polyface/RangeTree/PolyfaceRangeTreeContext.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module RangeSearch\n */\n\nimport { Geometry } from \"../../Geometry\";\nimport { Point3d } from \"../../geometry3d/Point3dVector3d\";\nimport { Range3d } from \"../../geometry3d/Range\";\nimport { FacetLocationDetail, FacetLocationDetailPair } from \"../FacetLocationDetail\";\nimport { Polyface, PolyfaceVisitor } from \"../Polyface\";\nimport { PolyfaceQuery } from \"../PolyfaceQuery\";\nimport { RangeTreeNode, RangeTreeOps } from \"./RangeTreeNode\";\nimport { SingleTreeSearchHandlerForClosestPointOnPolyface, TwoTreeSearchHandlerForFacetFacetCloseApproach } from \"./RangeTreeSearchHandlers\";\n\n/**\n * Handler class for searching a range tree containing the facets of a polyface.\n * * Facilitates multiple searches for closest point and close approach calculations.\n * @public\n */\nexport class PolyfaceRangeTreeContext {\n  /** Visitor for the polyface being searched */\n  public visitor: PolyfaceVisitor;\n  /** Whether all facets to visit are known to be convex. */\n  public convexFacets: boolean;\n\n  /** Diagnostic: number of range tests that have returned true. */\n  public numRangeTestTrue: number;\n  /** Diagnostic: number of range tests that have been returned false */\n  public numRangeTestFalse: number;\n  /** Diagnostic: number of facet tests. */\n  public numFacetTest: number;\n  /** Diagnostic: number of searches performed. */\n  public numSearch: number;\n\n  /** Range tree, whose appData are facet (read) indices */\n  private _rangeTreeRoot: RangeTreeNode<number>;\n\n  /** Constructor: capture inputs, initialize debug counters */\n  private constructor(rangeTreeRoot: RangeTreeNode<number>, visitor: PolyfaceVisitor, convexFacets: boolean = false) {\n    this.visitor = visitor;\n    this.convexFacets = convexFacets;\n    this._rangeTreeRoot = rangeTreeRoot;\n    this.numRangeTestTrue = 0;\n    this.numRangeTestFalse = 0;\n    this.numFacetTest = 0;\n    this.numSearch = 0;\n  }\n  /**\n   * Create a range tree context for the Polyface facets.\n   * * This is a very simple construction that splits \"right and left parts\" of the facet sequence.\n   * * Facets with any recognizable \"left to right\" or \"top to bottom\" sequencing will have very effective search structures.\n   * @param visitor access to facets, captured if PolyfaceVisitor\n   * @param maxChildPerNode maximum children per range tree node (default 4)\n   * @param maxAppDataPerLeaf maximum facet indices per leaf node (default 4)\n   * @param convexFacets whether all facets are known to be convex (cf. [[PolyfaceQuery.areFacetsConvex]]) (default false)\n   */\n  public static createCapture(visitor: Polyface | PolyfaceVisitor, maxChildPerNode: number = 4, maxAppDataPerLeaf: number = 4, convexFacets: boolean = false): PolyfaceRangeTreeContext | undefined {\n    if (visitor instanceof Polyface)\n      return this.createCapture(visitor.createVisitor(0), maxChildPerNode, maxAppDataPerLeaf, convexFacets);\n    const numFacet = PolyfaceQuery.visitorClientFacetCount(visitor);\n    const rangeTreeRoot = RangeTreeOps.createByIndexSplits<number>(\n      (index: number): Range3d => { visitor.moveToReadIndex(index); return visitor.range(); },\n      (index: number): number => { return index; },\n      numFacet,\n      maxChildPerNode,\n      maxAppDataPerLeaf,\n    );\n    return rangeTreeRoot ? new PolyfaceRangeTreeContext(rangeTreeRoot, visitor, convexFacets) : undefined;\n  }\n  /**\n   * Search the range tree for closest facet(s) to spacePoint.\n   * @param spacePoint point to test\n   * @param maxDist collect points at no more than this distance from spacePoint. If undefined, return only the closest point.\n   * @param searchFacetInterior whether to include facet interiors in search. Default is false: just consider facet boundaries.\n   * @return closest point detail(s) with detail.a set to the distance from spacePoint to detail.point\n   */\n  public searchForClosestPoint(spacePoint: Point3d, maxDist?: number, searchFacetInterior: boolean = false): FacetLocationDetail | FacetLocationDetail[] | undefined {\n    const handler = new SingleTreeSearchHandlerForClosestPointOnPolyface(spacePoint, this, maxDist, searchFacetInterior);\n    this.numSearch++;\n    const numFacet = PolyfaceQuery.visitorClientFacetCount(this.visitor);\n    // seed the search with a few points -- this reduces early trips deep into early ranges that are far from spacePoint.\n    const numTest = Geometry.clamp(Math.floor(numFacet / 20), 2, 7);\n    const testStep = Math.floor(numFacet / numTest);\n    handler.processAppData(0);\n    handler.processAppData(numFacet - 1);\n    for (let i = testStep; i + 1 < numFacet; i += testStep)\n      handler.processAppData(i);\n    this._rangeTreeRoot.searchTopDown(handler);\n    return handler.searchState.savedItems.length <= 1 ? handler.getResult() : handler.getSavedItems();\n  }\n  /**\n   * Search the range trees for closest approach(es) between the polyfaces.\n   * @param contextA first polyface context\n   * @param contextB second polyface context\n   * @param maxDist collect close approaches separated by no more than this distance. If undefined, return only the closest approach.\n   * @param searchFacetInterior whether to include facet interiors in search (`context.convexFacets` must be true for both contexts). Default is false: just consider facet boundaries.\n   * @return closest approach detail pair(s), one per context, with detail.a set to the approach distance\n  */\n  public static searchForClosestApproach(contextA: PolyfaceRangeTreeContext, contextB: PolyfaceRangeTreeContext, maxDist?: number, searchFacetInterior: boolean = false): FacetLocationDetailPair | FacetLocationDetailPair[] | undefined {\n    const handler = new TwoTreeSearchHandlerForFacetFacetCloseApproach(contextA, contextB, maxDist, searchFacetInterior);\n    RangeTreeNode.searchTwoTreesTopDown(contextA._rangeTreeRoot, contextB._rangeTreeRoot, handler);\n    return handler.searchState.savedItems.length <= 1 ? handler.getResult() : handler.getSavedItems();\n  }\n}\n"]}

package/lib/esm/polyface/RangeTree/RangeTreeNode.d.ts

@@ -0,0 +1,274 @@
+/** @packageDocumentation
+ * @module RangeSearch
+ */
+import { Range3d } from "../../geometry3d/Range";
+/** Type name FlexData is shorthand for a member or parameter which can be:
+ * * undefined
+ * * an array of values of type T
+ * * a singleton of type T
+ */
+type FlexData<T> = undefined | T[] | T;
+/**
+ * Type name IndexToType is shorthand for a member or parameter which can be:
+ * * an array of values of type T
+ * * a function from integers to type T.
+ */
+type IndexToType<T> = T[] | ((index: number) => T);
+/**
+ * Abstract class for handler objects called during traversal of a single range tree.
+ * @internal
+ */
+export declare abstract class SingleTreeSearchHandler<AppDataType> {
+    /** Return true if appData within the range should be offered to `processAppData`. */
+    abstract isRangeActive(range: Range3d): boolean;
+    /**
+     * Called for a (single) child referenced by a tree.
+     * * This is only called when range checks on the path from root have been passed.
+     * @param item child (of type AppDataType) in the tree.
+     */
+    abstract processAppData(item: AppDataType): void;
+    /**
+     * Query to see if the active search has been aborted.
+     * * Default implementation returns false so query runs to completion.
+     * * Search processes check this after range tests and child processing.
+     */
+    isAborted(): boolean;
+}
+/**
+ * Abstract class for handler objects called during traversal of two range trees.
+ * @internal
+ */
+export declare abstract class TwoTreeSearchHandler<AppDataType> {
+    /** Return true if appData within the ranges should be offered to `processAppDataPair`. */
+    abstract isRangePairActive(leftRange: Range3d, rightRange: Range3d): boolean;
+    /**
+     * Called with AppDataType items from left tree and right tree.
+     * * This is only called when range tests have been passed.
+     * @param leftItem
+     * @param rightItem
+     */
+    abstract processAppDataPair(leftItem: AppDataType, rightItem: AppDataType): void;
+    /**
+     * Query to see if the active search has been aborted.
+     * * Default implementation returns false so query runs to completion.
+     * * Search processes check this after range tests and child processing.
+     */
+    isAborted(): boolean;
+}
+/**
+ * This class refines the TwoTreeSearchHandler with an implementation of `isRangePairActive` appropriate for computing the minimum distance between trees.
+ * * The concrete class must implement `getCurrentDistance()` method to provide the best-so-far distance.
+ * * The implementation of `isRangePairActive` returns true if the distance between ranges is less than or equal to the `getCurrentDistance()` value.
+ * @internal
+ */
+export declare abstract class TwoTreeDistanceMinimizationSearchHandler<AppDataType> extends TwoTreeSearchHandler<AppDataType> {
+    /**
+     * Provides the allowable distance between ranges.
+     * * Range pairs with more than this distance separation are rejected.
+     * * The implementation may alter (probably reduce) the getCurrentDistance() value as the search progresses.
+     */
+    abstract getCurrentDistance(): number;
+    /**
+     * Method called to decide whether to process subtrees and immediate child appData items from a left tree node and right tree node.
+     * @param leftRange range from a node in the left tree
+     * @param rightRange range from a node in the right tree.
+     * @returns true if the smallest distance from leftRange to rightRange is less than or equal to getCurrentDistance()
+     */
+    isRangePairActive(leftRange: Range3d, rightRange: Range3d): boolean;
+}
+/**
+ * * TREE STRUCTURE
+ *   * A RangeTreeNode is part of a range tree.
+ *   * TREE is used here in a strictly _structural_ sense, which has no broad promises about data members.
+ *   * Each RangeNode points to 0, 1 or many children.
+ *   * Each child has (but does not point back to) a single parent.
+ *   * The overall tree has a single root.
+ *   * Each node is effectively the root of the tree of its children.
+ * * NON-TREE DATA MEMBERS
+ *   * Data members in each node (in addition to children) are
+ *     * _range = the union of ranges below in the heap
+ *     * _appData = application data associated with the node.
+ *       * Construction methods may place multiple _appData items in each node.
+ * * In common use, only the leaves will have _appData. However, the class definitions allow _appData at all nodes, and search algorithms must include them.
+ * * CONSTRUCTION
+ *   * The RangeTreeNode.createByIndexSplits method constructs the tree with simple right-left splits within an array of input items.
+ *     * The appData is placed entirely in the leaves.
+ *     * caller can specify:
+ *       * the number of _appData items per leaf
+ *       * the number of children per node within the tree.
+ *     * "deep" trees (2 children per node and one appData per leaf) may have (compared to shallow trees with many children per node and many appData per leaf)
+ *       * faster search because lower nodes have smaller ranges that will be skipped by search algorithms.
+ *       * larger memory use because of more nodes
+ *   * For future construction methods:
+ *      * _appData "above the leaves" may allow nodes below to have smaller ranges, but add complexity to search.
+ * @internal
+ */
+export declare class RangeTreeNode<AppDataType> {
+    private _range;
+    private _appData;
+    private _children;
+    /** an id assigned sequentially as nodes are created.  For debugging use only. */
+    private _id;
+    /**
+     * CONSTRUCTOR
+     * CAPTURE (not copy)
+     * * range = range for search algorithms
+     * * appData = application data relevant to this node.
+     * * children = child node reference(s).
+     */
+    private constructor();
+    /** Simplest public create: capture the range, appData, and children. */
+    static createCapture<AppDataType>(range: Range3d, appData: FlexData<AppDataType>, children: FlexData<RangeTreeNode<AppDataType>>): RangeTreeNode<AppDataType>;
+    /** copy (not capture) from given data into the range in this RangeEntry */
+    setRange(data: Range3d): void;
+    /** return (a copy of) the range in this RangeEntry */
+    getRange(data?: Range3d): Range3d;
+    /** return (a reference to) the range in this RangeEntry */
+    getRangeRef(): Range3d;
+    /**
+     * Access a child by index.
+     * * If the child data is an array, this dereferences the array.
+     * * If the child data is a singleton, treat it as index 0.
+     * * return undefined if there are no children.
+     * @param index index of item to access.
+     */
+    getChildByIndex(index: number): RangeTreeNode<AppDataType> | undefined;
+    /**
+     * * Access an appData by index.
+     * * If the appData data is an array, this dereferences the array.
+     * * If the appData data is a singleton, treat it as if it is at index 0 in an array
+     * * return undefined if there are no appData or for any index out of range.
+     * @param index index of item to access.
+     */
+    getAppDataByIndex(index: number): AppDataType | undefined;
+    /** Access the children or child (does not clone). */
+    getAllChildren(): FlexData<RangeTreeNode<AppDataType>>;
+    /** Access the appData array or singleton (does not clone). */
+    getAllAppData(): FlexData<AppDataType>;
+    /**
+     * Count the direct children in this node of the tree.
+     * * This is not recursive. For a recursive count, use `RangeTreeOps.getRecursiveNodeCount`.
+     */
+    getNumChildren(): number;
+    /**
+     * Count the appData items in this node of the tree.
+     * * This is not recursive. For a recursive count, use `RangeTreeOps.getRecursiveAppDataCount`.
+     */
+    getNumAppData(): number;
+    /**
+     * Depth-first tree iteration, calling `announceNode` on each node.
+     * @param announceNode callback that returns true to recurse into children
+     */
+    recurseIntoTree(announceNode: (node: RangeTreeNode<AppDataType>) => boolean): void;
+    /**
+     * Depth-first tree iteration via handler.
+     * * if handler decides the instance range is active, process appData, then recurse on children
+     * * if handler decides to abort after processing an appData, skip processing rest of appData and children
+     */
+    searchTopDown(handler: SingleTreeSearchHandler<AppDataType>): void;
+    /**
+     * Apply the handler.processAppDataPair method to each pair of appData items from leftAppData and rightStack.
+     * @param leftAppData singleton or array with data "from left"
+     * @param rightStack stack of nodes to process from right path.
+     * @param reverseArgs true if the caller is exchanging the sense of left and right and this should be undone in the actual call to handler.processAppDataPair.
+     * @param handler search handler
+     */
+    private static processAppDataAndAppDataStack;
+    /**
+     * Apply the handler.processAppDataPair method to each pair of appData items from leftAppData and rightAppData.
+     * @param leftAppData singleton or array with data "from left"
+     * @param rightAppData singleton or array with data "from right"
+     * @param reverseArgs true if the caller is exchanging the sense of left and right and this should be undone in the actual call to handler.processAppDataPair.
+     * @param handler search handler
+     */
+    private static processAppDataAndAppData;
+    /**
+     * Push the tip node to stack(s).
+     * @param tip new node (to be pushed)
+     * @param fullPath complete path, which is always extended
+     * @param partialPath partial path, which is only extended if the tip has _appData.
+     */
+    private static pushPaths;
+    /**
+     * Pop the tip node from stack(s).
+     * @param tip should match the fullPath tip.
+     * @param fullPath complete path, which is always popped
+     * @param partialPath partial path, which is only popped if the tip has _appData.
+     */
+    private static popPaths;
+    /**
+     * Process nodes from left and right trees of dual search.
+     * * The separate stacks for nodes that have appData is for efficiency.
+     * * If data is entirely in the leaves (or just in a few nodes), the stacks will all be empty (or very small) and no time will be wasted looking up the stacks for appData to process with the other tip.
+     * @param leftTip tip node being explored on left
+     * @param leftStack stack of prior left nodes
+     * @param leftStackWithAppData stack of prior left nodes which have appData.
+     * @param rightTip tip node being explored on right.
+     * @param rightStack stack of prior right nodes.
+     * @param rightStackWithAppData stack of prior right nodes which have appData.
+     * @param handler search handler
+     */
+    private static recursivePairSearch;
+    /**
+     * Recurse below the tip of leftTip, offering each level's appData to the appData of rightTip and rightStackWithAppData.
+     * @param leftTip tip node being explored on left. Its appData is not processed.
+     * @param rightTip tip node being explored on right. It has no children.
+     * @param rightStackWithAppData stack of prior right nodes which have appData.
+     * @param reverseArgs true if the caller is exchanging the sense of left and right
+     * @param handler search handler
+     */
+    private static leftRecursivePairSearch;
+    /**
+     * Recursive search down two trees, with range tests and child processing under control of a handler.
+     * @param leftRoot root of left tree
+     * @param rightRoot root of right tree
+     * @param handler handler for range tests and child process
+     */
+    static searchTwoTreesTopDown<AppDataType>(leftRoot: RangeTreeNode<AppDataType>, rightRoot: RangeTreeNode<AppDataType>, handler: TwoTreeSearchHandler<AppDataType>): void;
+}
+/**
+ * Utilities for various operations on RangeTree
+ * @internal
+ */
+export declare class RangeTreeOps {
+    /** Count nodes in this tree. */
+    static getRecursiveNodeCount<AppDataType>(root: RangeTreeNode<AppDataType>): number;
+    /** Count appData in this tree. */
+    static getRecursiveAppDataCount<AppDataType>(root: RangeTreeNode<AppDataType>): number;
+    /**
+     * Create a leaf referencing appData items indexed index0<=index<index1 and with combined range of the same indices
+     * @param ranges access to ranges
+     * @param appData access to AppDataType items
+     * @param index0 first index for block of items
+     * @param index1 upper limit index for block of items.
+     * @param arrayLength one more than the largest range/appData index
+     * @returns newly created node.
+     */
+    private static createLeafInIndexRange;
+    /**
+     * Split the array entries appData[index0 <= i < index1] into blocks of at most maxChildPerNode * maxAppDataPerLeaf and assemble into a tree structure.
+     * @param ranges access to ranges
+     * @param appData access to AppDataType items
+     * @param index0 start index of the block to access
+     * @param index1 terminal index for the block (one after final)
+     * @param arrayLength one more than the largest range/appData index
+     * @param maxChildPerNode max number of child nodes in each interior node
+     * @param maxAppDataPerLeaf max number of appData items in each leaf.
+     * @returns
+     */
+    private static createRecursiveByIndexSplits;
+    /**
+     * Create a range tree by simple left-right split of given ranges.
+     * * Leaves carry the inputs in left-to-right order.
+     * * Each leaf range is labeled by its corresponding object(s) in the appData array.
+     * @param ranges access to ranges.
+     * @param appData access to AppDataType items (for leaves).
+     * @param arrayLength one more than the largest range/appData index
+     * @param maxChildrenPerNode max number of child nodes allowed for each interior node.
+     * @param maxAppDataPerLeaf max number of appData items allowed in each leaf.
+     * @returns the root of the new tree, or undefined if array lengths differ or are zero.
+     */
+    static createByIndexSplits<AppDataType>(ranges: IndexToType<Range3d>, appData: IndexToType<AppDataType>, arrayLength: number, maxChildrenPerNode?: number, maxAppDataPerLeaf?: number): RangeTreeNode<AppDataType> | undefined;
+}
+export {};
+//# sourceMappingURL=RangeTreeNode.d.ts.map

package/lib/esm/polyface/RangeTree/RangeTreeNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeTreeNode.d.ts","sourceRoot":"","sources":["../../../../src/polyface/RangeTree/RangeTreeNode.ts"],"names":[],"mappings":"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"}