forma-embedded-view-sdk/dist/internal/geometry.d.ts

The Forma Embedded View SDK is a JavaScript library for creating custom extensions in Autodesk Forma (previously Spacemaker).

import type { IframeMessenger } from "./iframe-messenger.js";
/**
 * Geometry representation of an element describing its projection on the ground.
 */
export type Footprint = {
    type: "LineString" | "Polygon";
    /** List of xy-coordinates for the points which make up the footprint. */
    coordinates: [x: number, y: number][];
};
/**
 * Read geometry data from Forma.
 *
 * @remarks
 * Available via {@link auto.Forma | Forma}.{@link index.EmbeddedViewSdk.geometry | geometry}.
 */
export declare class GeometryApi {
    #private;
    /** @hidden */
    constructor(iframeMessenger: IframeMessenger);
    /**
     * Fetch paths of all elements in a proposal tagged with a specific category.
     * Traverses the element tree to also find any nested children tagged as well.
     *
     * @returns
     * List of paths to elements tagged with the given category.
     *
     * @example
     * // Fetch all paths to buildings in the current proposal.
     * const buildingPaths = await Forma.geometry.getPathsByCategory({ category: "buildings" })
     */
    getPathsByCategory(request: {
        /** Category to search for, such as "buildings" or "site_limit". */
        category: string;
        /** Root URN of the proposal to obtain paths for. If not provided, the current proposal is used. */
        urn?: string;
    }): Promise<string[]>;
    /**
     * Fetch the paths of all elements in a proposal with the property 'virtual' set to true.
     * Traverses the element tree to also find any nested children tagged as well.
     *
     * The virtual property can be used to describe something that isn't real,
     * like a constraint or an illustrative boy with balloon. If this is set,
     * analyses and possibly other modes will ignore the element.
     *
     * @returns
     * List of paths to elements tagged as virtual.
     *
     * @example
     * // Fetch paths to all elements in the current proposal that are virtual.
     * const virtualElementPaths = await Forma.geometry.getPathsForVirtualElements()
     */
    getPathsForVirtualElements(request?: {
        /** Root URN of the proposal to obtain paths for. If not provided, the current proposal is used. */
        urn?: string;
    }): Promise<string[]>;
    /**
     * Fetch footprint representation of an element. Does not traverse children of
     * the element, so if any of them have footprint representations which
     * are of interest they need to be fetched separately using their complete path.
     *
     * @returns
     * Footprint representation of the element pointed to by the given path.
     *
     * @example
     * // Fetch footprint of the first found proposal site limit.
     * const siteLimitPaths = await Forma.geometry.getPathsByCategory({ category: "site_limit" })
     * const siteLimitFootprint = await Forma.geometry.getFootprint({ path: siteLimitPaths[0] })
     */
    getFootprint(request: {
        /** Path of the element to obtain footprint for, relative to root. */
        path: string;
        /** Root URN of the proposal to obtain paths for. If not provided, the current proposal is used. */
        urn?: string;
    }): Promise<Footprint | undefined>;
    /**
     * Fetch mesh representation of an element and its children. Traverses the
     * element tree to also find any nested children with the `volumeMesh` representation.
     * All found meshes are concatenated into a flat list of triangles.
     *
     * @returns
     * Mesh representation (list of triangles with vertex coordinates represented
     * as `Float32`s) of the element pointed to by the given path and its children.
     *
     * @example
     * // Fetch mesh representation for the entire proposal and count the number of triangles.
     * const mesh = await Forma.geometry.getTriangles()
     * const numberOfVertices = mesh.length / 3
     * const numberOfTriangles = numberOfVertices / 3
     *
     * @example
     * // Fetch mesh representation for one of the elements with category building and its children.
     * const buildingPaths = await Forma.geometry.getPathsByCategory({category: "building"})
     * if (buildingPaths.length > 0 ) {
     *    const mesh = await Forma.geometry.getTriangles({path: buildingPaths[0]})
     * }
     *
     * @example
     * // Fetch mesh representation for the entire proposal except elements with category vegetation and their children.
     * const vegetationPaths = await Forma.geometry.getPathsByCategory({category: "vegetation"})
     * const mesh = await Forma.geometry.getTriangles({excludedPaths: vegetationPaths})
     */
    getTriangles(request?: {
        /**
         * Path of the element to recursively obtain mesh for.
         *
         * The path is relative to the root URN.
         *
         * @defaultValue "root"
         *
         * @example "root/a"
         * */
        path?: string;
        /**
         * Paths to elements that are recursively excluded from the resulting mesh.
         *
         * The paths are relative to the root URN.
         *
         * @defaultValue Empty list, i.e. no excluded paths.
         *
         * @example "root/a/b"
         * */
        excludedPaths?: string[];
        /** Root URN of the proposal to obtain paths for. If not provided, the current proposal is used. */
        urn?: string;
    }): Promise<Float32Array>;
    /**
     * Get all paths where the element's geometry has at least one vertex or point
     * inside at least one of the provided polygons.
     *
     * Useful in cases where you need all buildings inside a site limit,
     * without needing to do all the calculations yourself.
     *
     * For elements under the proposal, if an element is inside the polygon,
     * it is assumed that all its children are also inside the polygon.
     * Additionally, if a child is inside an element, it is assumed that
     * the parent is inside as well.
     *
     * @example
     * const polygon = someSiteLimitPolygon
     * const pathsInside = await Forma.analysis.selection.getPathsInsidePolygons({
     *  polygons: [someSiteLimitPolygon]
     * })
     */
    getPathsInsidePolygons(request: {
        /**
         * The list of polygons that you want to check for overlap between
         */
        polygons: [number, number][][];
    }): Promise<string[]>;
}