SearchGraph

dia.SearchGraph is a subclass of the dia.Graph class, specifically designed to optimize spatial queries for cells.

It uses a quadtree to index cells by their bounding boxes and overrides dia.Graph methods to enable more efficient search capabilities.

import { dia, shapes } from '@joint/plus';

const graph = new dia.SearchGraph({}, { cellNamespace: shapes });

Check out our learn section to see how to use the SearchGraph in practice.

Methods

The SearchGraph class inherits all methods of the parent Graph class with the following modifications and additions:

findCellsAtPoint()

searchGraph.findCellsAtPoint(
    point: dia.Point,
    opt?: dia.SearchGraph.FindAtPointOptions
): dia.Cell[];

Same as graph.findCellsAtPoint(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is at the point (just that there is something there), you can use the hasCellsAtPoint() method instead.

findCellsInArea()

searchGraph.findCellsInArea(
    area: dia.BBox,
    opt?: dia.SearchGraph.FindInAreaOptions
): dia.Cell[];

Same as graph.findCellsInArea(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is in the area (just that there is something there), you can use the hasCellsInArea() method instead.

findCellsUnderElement()

searchGraph.findCellsUnderElement(
    element: dia.Element,
    opt?: dia.SearchGraph.FindUnderElementOptions
): dia.Cell[];

Same as graph.findCellsUnderElement(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

findElementsAtPoint()

searchGraph.findElementsAtPoint(
    point: dia.Point,
    opt?: dia.SearchGraph.FindAtPointOptions
): dia.Element[];

Same as graph.findElementsAtPoint(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is at the point (just that there is something there), you can use the hasElementsAtPoint() method instead.

findElementsInArea()

searchGraph.findElementsInArea(
    area: dia.BBox,
    opt?: dia.SearchGraph.FindInAreaOptions
): dia.Element[];

Same as graph.findElementsInArea(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is in the area (just that there is something there), you can use the hasElementsInArea() method instead.

findElementsUnderElement()

searchGraph.findElementsUnderElement(
    element: dia.Element,
    opt?: dia.SearchGraph.FindUnderElementOptions
): dia.Element[];

Same as graph.findElementsUnderElement(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

findLinksAtPoint()

searchGraph.findLinksAtPoint(
    point: dia.Point,
    opt?: dia.SearchGraph.FindAtPointOptions
): dia.Link[];

Same as graph.findLinksAtPoint(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is at the point (just that there is something there), you can use the hasLinksAtPoint() method instead.

findLinksInArea()

searchGraph.findLinksInArea(
    area: dia.BBox,
    opt?: dia.SearchGraph.FindInAreaOptions
): dia.Link[];

Same as graph.findLinksInArea(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

tip

If you do not need to know precisely what is in the area (just that there is something there), you can use the hasLinksInArea() method instead.

findLinksUnderElement()

searchGraph.findLinksUnderElement(
    element: dia.Element,
    opt?: dia.SearchGraph.FindUnderElementOptions
): dia.Link[];

Same as graph.findLinksUnderElement(), with one modification:

If opt.useIndex is set to false, this SearchGraph's index filter is bypassed. See searchGraph.setQuadTreeIndexFilter() for more information.

hasCellsAtPoint()

searchGraph.hasCellsAtPoint(
    point: dia.Point,
    options: dia.SearchGraph.FindAtPointOptions
): boolean;

Return true if there is at least one cell (element or link) at the given point. point is an object with x and y properties.

If opt.strict is set to true, the point must lie inside a cell's bounding box (not on the border).

hasCellsInArea()

searchGraph.hasCellsInArea(
    area: dia.BBox,
    options: dia.SearchGraph.FindInAreaOptions
): boolean;

Return true if there is at least one cell (element or link) whose bounding box intersects a certain area in the graph. area is an object with x, y, width and height properties.

If opt.strict is set to true, a cell must be fully contained within the area.

hasElementsAtPoint()

searchGraph.hasElementsAtPoint(
    point: dia.Point,
    options: dia.SearchGraph.FindAtPointOptions
): boolean;

Return true if there is at least one element at the given point. point is an object with x and y properties.

If opt.strict is set to true, the point must lie inside an element's bounding box (not on the border).

hasElementsInArea()

searchGraph.hasElementsInArea(
    area: dia.BBox,
    options: dia.SearchGraph.FindInAreaOptions
): boolean;

Return true if there is at least one element whose bounding box intersects a certain area in the graph. area is an object with x, y, width and height properties.

If opt.strict is set to true, an element must be fully contained within the area.

hasLinksAtPoint()

searchGraph.hasLinksAtPoint(
    point: dia.Point,
    options: dia.SearchGraph.FindAtPointOptions
): boolean;

Return true if there is at least one link at the given point. point is an object with x and y properties.

If opt.strict is set to true, the point must lie inside a link's bounding box (not on the border).

hasLinksInArea()

searchGraph.hasLinksInArea(
    area: dia.BBox,
    options: dia.SearchGraph.FindInAreaOptions
): boolean;

Return true if there is at least one link whose bounding box intersects a certain area in the graph. area is an object with x, y, width and height properties.

If opt.strict is set to true, a link must be fully contained within the area.

invalidateQuadTree()

searchGraph.invalidateQuadTree(): void;

Invalidate the quadtree. This will force the quadtree to be rebuilt on the next search query.

setQuadTreeBoundary()

searchGraph.setQuadTreeBoundary(
    boundary: dia.BBox,
    autoGrow: boolean = false
): void;

Set the initial boundary of the quadtree.

If autoGrow is true, the boundary is automatically expanded when a cell is added outside of the boundary.

searchGraph.setQuadTreeBoundary(boundary: null): void;

If the boundary is null, the boundary is automatically computed from the cells in the graph and the autoGrow parameter is ignored.

This is the default behavior of the search graph.

setQuadTreeCapacity()

searchGraph.setQuadTreeCapacity(capacity: number): void;

Set the capacity of the quadtree. The capacity is the maximum number of cells in a quadtree node before it splits into four subnodes.

The default node capacity is 16.

setQuadTreeIndexFilter()

searchGraph.setQuadTreeIndexFilter(
    filter: ((cell: dia.Cell) => boolean) | null
): void;

Set the index filter. The index filter is a callback function that controls which cells should be indexed based on custom criteria (e.g. cell visibility).

Cells which are not indexed will not be considered by any SearchGraph find_() nor has_() function calls (e.g. findCellsAtPoint(), hasCellsAtPoint()).

note

If you need to bypass the index filter for a single SearchGraph query, you can pass useIndex: false as an option to the function call (e.g. searchGraph.findCellsAtPoint(point, { useIndex: false }), searchGraph.hasCellsAtPoint(point, { useIndex: false })).

setQuadTreeLazyMode()

searchGraph.setQuadTreeLazyMode(lazyMode: boolean): void;

Set the lazy mode of the quadtree. In lazy mode, the quadtree is not updated automatically when cells are added or removed. Instead, the quadtree is updated only when the first search is performed.

setQuadTreeMaxDepth()

searchGraph.setQuadTreeMaxDepth(maxDepth: number): void;

Set the maximum depth of the quadtree. The maximum depth is the maximum number of levels the quadtree can have.

The default maximum depth is 6.

Types

FindAtPointOptions

interface FindAtPointOptions extends dia.Graph.FindAtPointOptions {
    useIndex?: boolean;
}

FindInAreaOptions

interface FindInAreaOptions extends dia.Graph.FindInAreaOptions {
    useIndex?: boolean;
}

FindUnderElementOptions

interface FindUnderElementOptions extends dia.Graph.FindUnderElementOptions {
    useIndex?: boolean;
}