forma-embedded-view-sdk
Version:
The Forma Embedded View SDK is a JavaScript library for creating custom extensions in Autodesk Forma (previously Spacemaker).
258 lines (257 loc) • 9.22 kB
TypeScript
import type { IframeMessenger } from "./iframe-messenger.js";
/**
* Analysis record containing metadata for a given Forma analysis.
*/
export type Analysis = {
/** Unique identifier for the analysis */
analysisId: string;
/** Type of analysis, such as sun, noise or wind */
analysisType: string;
/** ISO timestamp for the creation of the analysis record */
createdAt: number;
/** Root URN of the proposal which the analysis was triggered on */
elementUrn: string;
/** Unique identifier for the proposal */
proposalId: string;
/** Unique identifier for the revision of the proposal */
proposalRevision: string;
/** Current status of the analysis, possible values:
* - CREATED
* - IN_PROGRESS
* - SUCCEEDED
* - STOPPED
* - FAILED */
status: string;
/** ISO timestamp for the latest update of the analysis record */
updatedAt?: number | undefined;
};
/**
* The parameters used to run a sun analysis.
*/
export type SunAnalysisParameters = {
/** List of element paths the analysis was run on*/
selectedElementPaths: string[];
/** The date of the year the analysis was run for */
sunDate: {
month: number;
date: number;
};
/** The project's timezone */
timezone: string;
/** The [lat, long] coordinates of the project */
geoLocation: [number, number];
/** Meters between each sample point on the ground */
groundResolution: number;
/** Number of samples per point per hour */
sunPositionsPerHour: number;
};
export type SunAnalysis = Analysis & {
/** ISO timestamp for when the analysis completed */
completedAt?: number | undefined;
parameters: SunAnalysisParameters;
};
/**
* The parameters used to run a noise analysis.
*/
export type NoiseAnalysisParameters = {
/** List of element paths the analysis was run on*/
selectedElementPaths: string[];
/** Meters between each sample point on the ground */
groundResolution: number;
/** Whether the analysis contains roads with traffic data */
hasRoad: boolean;
/** Whether the analysis contains railways with traffic data */
hasRail: boolean;
};
export type NoiseAnalysis = Analysis & {
/** ISO timestamp for when the analysis completed */
completedAt?: number | undefined;
parameters: NoiseAnalysisParameters;
};
/**
* Ground grid for analysis results in row-major order.
*
* <img src="../media/analysis-ground-grid.png" width="600px"/>
*/
export type AnalysisGroundGrid = {
/** Flat list of the result values. The data type and format of the grid depends on the analysis type, so we refer to [the docs](https://aps.autodesk.com/en/docs/forma/v1/embedded-views/useful-concepts/analysis/) for details. */
grid: Float32Array | Uint8Array;
/** Boolean array which denotes if each sample point is valid. For `Float32Array` grids, this is also signaled by NaN values in the `grid`. Invalid sample points are for example under buildings. */
mask?: Uint8Array | undefined;
/** Number of points in the horizontal direction (columns) in the ground grid. */
width: number;
/** Number of points in the vertical direction (rows) in the ground grid. */
height: number;
/** x-coordinate of the upper left corner of the ground grid. */
x0: number;
/** y-coordinate of the upper left corner of the ground grid. */
y0: number;
/** Meters between each sample point in the grid per direction
* @deprecated use `resolution` instead
*/
scale: {
x: number;
y: number;
};
/** Meters between each sample point */
resolution: number;
};
/**
* Interact with Forma's native [analysis functionality](https://aps.autodesk.com/en/docs/forma/v1/embedded-views/useful-concepts/analysis/).
*
* @remarks
* Available via {@link auto.Forma | Forma}.{@link index.EmbeddedViewSdk.analysis | analysis}.
*/
export declare class AnalysisApi {
#private;
/** @hidden */
constructor(iframeMessenger: IframeMessenger);
/**
* Fetch analysis records connected to the currently open proposal.
*
* @returns
* List of relevant analysis records.
*
* @example
* // Fetch all sun analysis records.
* // Filter to only include those in SUCCEEDED state.
* const sunAnalyses = await Forma.analysis.list({ analysisTypes: ["sun"] })
* const succeededSunAnalyses = sunAnalyses.filter(analysis => analysis.status === "SUCCEEDED")
*/
list(request: {
/**
* Authcontext to use with the request. As of now, the currently
* open project id is both default and only allowed value.
*/
authcontext?: string | undefined;
/**
* First part of root element URN -- enables filtering based on URN pattern.
*/
elementUrnPrefix?: string | undefined;
/**
* Allowedlist of analysis types (such as sun, noise and wind) to filter for.
*/
analysisTypes?: string[] | undefined;
}): Promise<Analysis[]>;
/**
* @beta
* Trigger a
* [noise analysis](https://aps.autodesk.com/en/docs/forma/v1/embedded-views/useful-concepts/analysis/noise/)
* based on the traffic data connected to roads and railways in the proposal. Computes A-weighted decibel levels.
*
* Requires edit access. See {@link EmbeddedViewSdk.getCanEdit | getCanEdit} for more info.
*
* @returns Analysis record for the newly triggered analysis.
*
* @example
* // Trigger noise analysis on selected elements
* const currentlySelected = await Forma.selection.getSelection()
* const sunAnalysis = await Forma.analysis.triggerNoise({
* selectedElementPaths: currentlySelected
* })
* @remarks
* Noise analysis is a Beta feature of Autodesk Forma.
*
*/
triggerNoise(request: {
/**
* List of element paths to trigger noise analysis on.
*/
selectedElementPaths: string[];
/**
* Root URN corresponding to the proposal which the selected element
* paths belong to. Defaults to the currently open proposal.
*/
rootUrn?: string | undefined;
}): Promise<Analysis>;
/**
* Trigger a
* [sun analysis](https://aps.autodesk.com/en/docs/forma/v1/embedded-views/useful-concepts/analysis/sun/)
* for a specific day of the year. Computes sun exposure in hours.
*
* Requires edit access. See {@link EmbeddedViewSdk.getCanEdit | getCanEdit} for more info.
*
* @returns
* Analysis record for the newly triggered analysis.
*
* @example
* // Trigger sun analysis on selected elements for the summer solstice
* const currentlySelected = await Forma.selection.getSelection()
* const sunAnalysis = await Forma.analysis.triggerSun({
* selectedElementPaths: currentlySelected,
* month: 6,
* date: 21
* })
*/
triggerSun(request: {
/**
* List of element paths to trigger sun analysis on.
*/
selectedElementPaths: string[];
/**
* Month of the year (1-12).
*/
month: number;
/**
* Day of the month (1-31).
*/
date: number;
/**
* Root URN corresponding to the proposal which the selected element
* paths belong to. Defaults to the currently open proposal.
*/
rootUrn?: string | undefined;
}): Promise<Analysis>;
/**
* Fetch a specific sun analysis.
*
* @returns
* Information about the sun analysis.
*/
getSunAnalysis(request: {
/**
* Unique identifier for the analysis
*/
analysisId: string;
}): Promise<SunAnalysis>;
/**
* Fetch a specific noise analysis.
*
* @returns
* Information about the noise analysis.
*
* @remarks
* Noise analysis is a Beta feature of Autodesk Forma.
*/
getNoiseAnalysis(request: {
/**
* Unique identifier for the analysis
*/
analysisId: string;
}): Promise<NoiseAnalysis>;
/**
* Fetch
* [ground grid result](https://aps.autodesk.com/en/docs/forma/v1/embedded-views/useful-concepts/analysis/)
* for a sun or noise analysis.
*
* Requires edit access. See {@link EmbeddedViewSdk.getCanEdit | getCanEdit} for more info.
*
* @returns
* Ground grid containing results for the requested analysis.
*
* @example
* // Fetch ground grid for the first listed succeeded sun analysis
* const sunAnalyses = await Forma.analysis.list({ analysisTypes: ["sun"] })
* const succeededSunAnalyses = sunAnalyses.filter(analysis => analysis.status === "SUCCEEDED")
* const groundGrid = await Forma.analysis.getGroundGrid({ analysis: succeededSunAnalyses[0] })
*
* @remarks
* Noise analysis is a Beta feature of Autodesk Forma.
*/
getGroundGrid(request: {
/**
* Analysis record to fetch ground grid results for.
*/
analysis: Analysis;
}): Promise<AnalysisGroundGrid | undefined>;
}