Functions
Project
int	setProjectNumber (string s, bool overwriteExisting=false)

int	setProjectShortDescription (string s, bool overwriteExisting=false)

int	setProjectLongDescription (string s, bool overwriteExisting=false)

void	setTempValue (string name, var value)

var	getTempValue (string name)

array< string >	getListOfTempValues ()

void	clearListOfTempValues ()

Models
string	getModelByElement (string id, string domainFilter="all")

array< string >	getModelListByName (string name, string domain="geometry")

array< string >	getModelListByDomain (string domainFilter="all")

string	getRootNodeByModel (string modelId)

array< string >	getRootNodeListByDomain (string domainFilter="all")

array< string >	getRootContainerList (string modelName)

string	createModel (string name, bool createRootC=true, string domain="geometry")

object	getModelMetaData (string modelId)

int	deleteModel (string id)

object	getImportOptions (string modelId)

Objects / Lookup
array< string >	getAllElements (string domainFilter="geometry")

bool	hasElement (string id)

array< string >	filterByProperty (array< string > inputList, string propertyName, string propertyDatatype, string filterPattern, bool checkInherited=true, string domains="geometry")

array< string >	filterByStatus (array< string > inputList, string status, bool value=true, string domains="geometry")

void	itClear ()

int	itByFilter (string propName, string propDatatype, string filterPattern, bool checkInh=true, string domain="geometry")

int	itFilterByStatus (string status, bool enabled=true, string domain="geometry")

int	itByObjectList (string idList)

string	itGetObjectList ()

bool	itHasNext ()

string	itNext ()

int	itCount ()

void	itToFront ()

array< var >	itGetAvailablePropertyValues (string propName, string propDatatype, int maxValues)

void	itSetupDbCache (string propName, string propType)

void	itSetMaterial (string matId)

void	itColorCode (string propName, string propDT)

void	itColorCodeNumber (string propName, string propDT, double intervalSize)

void	itCalcOOBB (double eps)

void	itUpdateOOBB (double eps)

void	itCalcOOBBxy (double eps)

void	itUpdateOOBBxy (double eps)

string	findContainerByName (string parentId, string name, string lookupDomain="all")

bool	isContainer (string id)

Object Manipulation
int	startProjectTransaction (string domain="geometry")

int	endProjectTransaction (string domain="geometry")

var	createObject (string parentID, object objectMap)

string	createObjectFromXml (string parentId, string objectXML)

int	deleteObjects (string idList)

object	getAsJSON (string objId)

int	setAsComposite (string id, bool composite)

Object Links
int	setLinkedObjects (string elementID, string IDList)

int	removeAllLinkedObjects (string id)

int	removeLinkedObjects (string id, string linkedIdList)

int	updateRuleBasedLinks (string domainName, bool visibleOnly=false)

int	removeRuleBasedLinks (string domainName)

Locking of Objects
void	lockObjects (string idList)

void	unlockObjects (string idList)

void	unlockAllObjects ()

string	getLocked ()

int	countLocked ()

Object Tooltips
array< string >	getListOfObjTooltips ()

void	addObjectListToTooltip (string idList, string tooltipname)

void	removeObjectListFromTooltip (string idList, string tooltipname)

Property Types
int	createPropertyType (string propName, string propDatatype, string uomCode, bool isInh, int target, string domainName="all")

int	setPropertyTypeMetaData (string pName, string ptype, object metadata)

int	deletePropertyType (string propertyName, string propertyDatatype, string domainName="all")

array< var >	getPropertyTypeBookmarkList ()

object	getPropertyTypeBookmarkByID (string bookmarkId)

int	activatePropertyTypeBookmark (string bkmId)

bool	setPropertyTypeActive (string pName, string ptype, string domain, bool active)

int	setAllPropertyTypesActive ()

int	removePropertyTypeBookmarkByID (string bkmId)

string	addPropertyTypeBookmark (object bookmarkConfig)

Properties
int	setPropertyValue (string objId, string propName, string propDataType, var value)

int	deleteProperty (string objId, string propName, string propDatatype)

array< var >	getPropertyValues (string propName, string propDatatype, int maxValues=0, string domainName="all", bool getNullValues=false)

array< var >	getPropertyValuesByObjectList (string propertyName, string propertyDatatype, bool checkInherited, var objectIdList, int maxValues=0, string domains="all", bool getNullValues=false)

object	getPropertyListAsJSON (object options)

void	setPropertyListAsJSON (object propmap, object opt)

Property Scripts
object	getPropertyScriptList () const

string	getPropertyScriptCode (string domain, string pname, string datatype) const

string	getPropertyScriptFgColor (string domain, string pname, string datatype) const

string	getPropertyScriptBgColor (string domain, string pname, string datatype) const

int	setPropertyScriptCode (string domain, string pname, string datatype, string code)

int	setPropertyScriptFgColor (string domain, string pname, string datatype, string code)

int	setPropertyScriptBgColor (string domain, string pname, string datatype, string code)

object	addPropertyScript (string domain, string pname, string datatype, string code=string())

int	removePropertyScript (string domain, string pname, string datatype)

void	propertyScriptClearCache (string domain="all", string pname="", string datatype="")

object	getPropertyScriptOptions (string domain, string pname, string datatype)

int	setPropertyScriptOptions (string domain, string pname, string datatype, object opt)

Documents
int	synchronizeDocumentContainer (string containerId, bool waitForCompletion=false)

void	resetDocumentMetaData (string objId)

array< object >	findDocumentsByLocationGps (double lat, double lon, double distance, array< string > idList=array< string >())

array< object >	findDocumentsByLocationRangeGps (array< string > gpsCoordinates, double distance, array< string > idList=array< string >())

array< object >	findDocumentsByLocationGk (double rw, double hw, double distance, array< string > idList=array< string >())

array< string >	findDocumentsByDate (date start, date end, array< string > idList=array< string >(), bool useRef=false)

Activities - Calendar
string	createCalendar (string name, string comment)

int	removeCalendar (string calendarID)

array< string >	getCalendarList ()

string	getCalendarByName (string name)

string	getDefaultCalendar ()

string	getCalendarByTask (string taskID, bool checkInh=true)

int	setCalendar (string taskID, string calendarID)

int	removeCalendarFromTask (string taskID)

int	setCalendarOptions (string calendarID, object options)

object	getCalendarOptions (string calendarID)

array< object >	getCalendarExceptions (string calendarID)

int	addCalendarExceptions (string calendarID, array< object > exceptions)

int	removeCalendarException (string calendarID, var date)

int	clearCalendarExceptions (string calendarID)

int	setCalendarWorkingTime (string calendarID, object workingTime)

object	getCalendarWorkingTime (string calendarID)

int	calcWorkInMinutes (date start, date finish, string calendarID=string())

Activities - Task Restrictions
array< string >	getTaskRestrictionsList ()

string	getTaskRestrictionsByName (string name)

int	setTaskRestrictions (string taskID, string restrictionsID)

int	removeTaskRestrictions (string taskID)

Activities - Task Visualisations
object	getVisualisationList ()

int	setVisualisationByID (string taskIDList, string visID)

int	removeVisualisation (string taskIDList)

Activities - Tools
int	setTaskMode (string taskID, int mode)

int	recalculateActivityProject (string taskID=string(), bool visibleOnly=false)

object	calcPropertyValuesOverTime (string propName, string propType, object options)

int	createTimeSchedule (object config)

Geometry
int	hasContact (string objId1, string objId2, object options=object())

string	createContactObject (string parentId, string objId1, string objId2, string matId, object options=object())

array< string >	cutObject (string parentId, string objId, object plane=object(), bool closeCuts=true, bool splitUnconnectedParts=true)

string	mergeObjects (string parentContainerId, string idList, bool skipClosed=false, bool keepTransparency=false, bool keepCommonProperties=false, bool replaceParent=false)

bool	isIncludedIn (string objId1, string objId2)

int	isPointIncludedIn (double x, double y, double z, string objId, double tol=1.e-5)

int	checkIntersection (string objId1, string objId2, double tolerance=-0.00001)

int	transformObject (string objId, string transformation)

int	setAsOpening (string objId, string openingIDList)

string	getProjectionAsSvg (string idList, object options=object())

double	calcDistance (string objId1, string objId2)

var	calculateDistance (string meshID1, string meshID2)

int	swapOrientationOfTriangles (array< object > idList)

Geometry - Materials
string	createMaterial (string matXml, string modelId=string())

int	deleteMaterial (string matId)

array< string >	getMaterialList ()

string	getMaterialAsXmlByID (string matId)

object	getMaterial (string matId)

string	getMaterialIDByName (string matName)

void	updateMaterial (string matId, string xmlMat)

int	setMaterialToObjects (string matId, var objectIds)

int	setTransparency (string objectIds, float defaultTransparency=0.95)

void	resetMaterials (bool updateUI=true)

void	colorCodeObjects (array< string > objectIds, string propertyName, string propertyDatatype, double intervalSize=1.0)

Geometry - Color Schema
string	createColorSchema (string setContainerId, string name)

string	createColorSchemaFromCurrentMaterials (string name, bool updateExisting, object options=object())

int	deleteColorSchema (string namePattern)

array< string >	getColorSchemaList ()

string	getCurrentColorSchema ()

bool	activateColorSchemaByName (string name)

Geometry - Wire Mode
void	showWireModeSchema (string name)

void	clearWireMode ()

void	setObjectsToWireMode (string ids, bool wired)

string	createWireModeSchema (string ids, string wmName, bool overwrite=false)

string	getWired ()

int	countWired ()

Geometry - Bounding Box
double	getBBoxMinX ()

double	getBBoxMaxX ()

double	getBBoxMinY ()

double	getBBoxMaxY ()

double	getBBoxMinZ ()

double	getBBoxMaxZ ()

void	updateBoundingBox3DView ()

int	calcOOBB (var objectIds, double eps=0.001)

int	updateOOBB (var objectIds, double eps=0.001)

int	calcOOBBxy (var objectIds, double eps=0.001)

int	updateOOBBxy (var objectIds, double eps=0.001)

object	getBoundingBoxCommon (var objectIds)

object	getOOBBCommon (var objectIds)

object	getOOBBxyCommon (var objectIds)

double	checkOverlapOBB (string id1, string id2, double eps=0.001)

Selection Sets
string	createSelectionSets (string propertyTypes, string rootName, object config=object())

array< string >	getRootNodeListSelectionSets (string domainFilter="all")

int	addToSelectionSetGeometry (string setId, string objectIDList)

int	removeFromSelectionSetGeometry (string setId, string objectIDs)

string	createSelectionSet (string name, string parentID=string())

bool	removeSelectionSet (string selsetID)

int	updateSmartSets (array< string > smartSetIDs=array< string >())

Regions of Alignments
string	addRegionToAlignment (string alignmentId, object setting)

int	removeAllRegionsFromAlignment (string alignmentId)

int	addRangeToRegion (string regionId, double fromStation, double toStation, string alignmentId=string())

int	removeRangeFromRegion (string regionId, double fromStation, double toStation, string alignmentId=string())

int	removeAllRangesFromRegion (string regionId, string alignmentId=string())

File Operations
int	createDirectory (string path, string dirName)

bool	writeFile (string filePath, string content, string encoding=string())

bool	appendToFile (string filePath, string content, string encoding=string())

bool	removeFile (string filePath)

bool	copyFile (string fnFrom, string fnTo)

bool	moveFile (string fnFrom, string fnTo)

bool	checkIfFileExists (string filePath)

bool	openFile (string filePath, string encoding=string())

bool	writeToFile (string content)

bool	closeFile ()

array< string >	readTextFile (string filename, bool ignoreLineBreakesInDoubleQuotes=false, string codec=string())

string	readTextFileAsString (string filename, string codec=string())

var	readFileInChunks (string filePath, object options)

object	readCsvFile (string filePath, string delimiter=";", string encoding="Windows-1252")

int	csvOpen (string filePath, string delimiter=";", string encoding="Windows-1252")

array< string >	csvNextLine ()

bool	csvHasNextLine ()

bool	csvClose ()

string	readImageFile (string filename, string targetFormat="", bool applyExifRotation=false)

array< object >	getDirectoryEntryList (string dirPath, bool filesOnly=false, string orderBy="Name")

Database
bool	dbIsLocalCopy ()

string	dbGetFilepath () const

int	dbOpen (const var connectionData=var())

bool	dbClose ()

void	dbCheckIn ()

void	dbCheckOut (array< string > propList)

bool	dbQueryExec (string sqlQuery)

object	dbQueryRecordset (string sqlQuery, string key, int maxNumberOfRows=0)

bool	dbEndQueryExec ()

bool	dbQueryNext ()

var	dbQueryValue (int column)

string	dbQueryLastError ()

int	setPropertyValueDB (string objIdList, string propName, string propDataType, string propDomain, var value, bool createType=true)

int	writePropertyValueDB (string objIdList, string propName, string propDataType, string propDomain, var value, bool createType=true)

bool	startTransaction ()

bool	endTransaction ()

bool	dbGetImmediateUpdate ()

void	dbSetImmediateUpdate (bool)

int	dbClearCache (string propName, string propType)

void	dbClearCacheAll ()

int	dbDeleteProperty (string objIdList, string propName, string propType)

int	dbAssertTable (string tableName, array< string > columnsList)

Model Check / Clash Detection
bool	setCheckActive (string checkRunID, bool active)

int	runCheck (string checkRunID)

int	clearCheckResults (string checkRunID)

int	setCheckOptions (string checkRunID, object options)

object	getCheckOptions (string checkRunID) const

int	setCheckFilterList (string checkRunID, array< object > filterList, bool rightSet=false)

array< object >	getCheckFilterList (string checkRunID, bool rightSet=false) const

int	setCheckItems (string checkRunID, array< string > elementIDist, bool rightSet=false)

array< string >	getCheckItems (string checkRunID, bool rightSet=false) const

int	setPostProcessingCode (string checkRunID, string code)

string	addCheckRule (string checkRunID, object rule, string parentRuleID=string())

int	removeCheckRule (string checkRunID, string type, string ruleID)

int	clearCheckRules (string checkRunID, string ruleTypeFilter=string())

object	getCheckRules (string checkRunID, string ruleTypeFilter=string())

Geo Location
void	enableGeoLocation (int msecInterval=60)

void	disableGeoLocation ()

object	currentGeoPosition ()

Tools / Miscellaneous
int	setBoQBreakdownStructure (string boqModelID, string templateStr)

int	sortContainerByProperty (string containerId, string propName, string propType, bool ascending=true, int maxDepth=0)

int	validateIfcCompatibiliy (string bsModelID)

Functions inherited from CoreAPI
string	addDays (string dateStr, int nrDays)

int	getCalendarWeek (date dt)

string	createID ()

long	calcHashcode (string str)

string	compressToIfcGuid (string id)

string	uncompressFromIfcGuid (string ifcGuid)

bool	checkRegExp (string value, string pattern)

double	calcSlantedArea (string objId, double angleMin=0.0, double angleMax=45.0)

object	calcGpsCoordsByStation (string objId, double station)

object	calcGpsCoordsByModelCoords (double x, double y)

object	calcModelCoordsByGpsCoords (double lat, double lon)

object	calcGkCoordsByModelCoords (double x, double y, double z)

object	calcModelCoordsByGkCoords (double r, double h)

object	calcGkCoordsByGpsCoords (double lat, double lon)

object	calcGpsCoordsByGkCoords (double rw, double hw)

string	idListToStr (array< string > idList)

array< string >	strToIdList (string strIDList)

var	getFileInfo (string filePath)

string	getAbsolutePath (string filePath)

string	getBaseName (string filePath)

string	getFileName (string filePath)

string	getApplicationDirectory ()

string	getApplicationFilename ()

string	getApplicationLanguage ()

string	getVersionAsString ()

object	getVersion ()

bool	requireVersion (int major, int minor, int patch)

string	getDomainByElement (string objId)

string	getUserName ()

string	getProjectName ()

string	getProjectDirectory ()

object	getProjectLocation () const

object	getProjectInfo ()

array< string >	getContainedElements (string containerId, int maxDepth, bool loadExternal=true)

int	countContainedElements (string containerId, int maxDepth, bool loadExternal=true)

string	getParent (string objId)

array< string >	getOpenings (string objId)

array< string >	getParts (string objId)

array< string >	getLinkedObjects (string objectIDList, string resultDomains="all", string objectLookupDomains="all")

bool	isVisible (string objId)

bool	isSelected (string objId)

bool	isLocked (string objId)

bool	isWired (string objId)

var	getPropertyValue (string objId, string propName, string propType, bool inh=true)

array< object >	getPropertyValuesByObject (string objId, string filterpattern="*")

var	getPropertySource (string objId, string propName, string propType, bool inh=true)

string	getPropertyUnit (string propName, string propType)

var	getPropertyValueByDate (string objId, string propName, string propType, bool inh=true)

array< object >	getPropertyDateList (string objectId, string propertyBaseName, string propertyType)

object	getPropertyTypeMetaData (string propName, string propType)

array< object >	getPropertyTypeList (string domain="all", string filterPattern="*", bool activeOnly=false)

array< object >	getPropertyTypeListByObject (string objId, string filterPattern="*")

bool	isPropertyInherited (string objId, string propName, string propType)

string	getPropertyValueRange (string idList, string propName, string propType, string domainFilter="geometry")

var	evaluateFormula (string code, string id, string id_otherdomain=string())

string	prepareJsCode (string code, string id, int dec=-1, string frmt="%L1", int fieldWidth=10, QChar fillChar=QChar())

array< string >	extractPropertyNames (string code, string startTag="[[", string endTag="]]")

array< object >	getGlobalProjectProperties ()

array< object >	getPointList (string objId)

object	getPointOnAlignmentAtStation (string alignmentId, double d)

double	getStationOfProjectedPoint (string alignmentId, double x, double y, double z=0.0)

array< string >	getRegionsOfAlignment (string alignmentId)

array< object >	getRangesOfRegion (string alignmentID, string regionID)

double	getValueOfAlignmentRegion (string alignmentID, string regionID)

int	getTaskMode (string taskID)

string	getTaskVisualisation (string taskID)

string	getTaskRestrictionsByTask (string taskID)

Signals
void	synchronizationFinished (bool success)

void	fileChunkReceived (string data)

void	geoPositionUpdated (object pos)

Function Documentation

◆ activateColorSchemaByName

bool activateColorSchemaByName ( string name )

function

Activate color scheme with given name (case sensitive). If name is empty, materials will be restored. View will be repainted.

Returns: true if color scheme was activated, else false (e.g. when name does not exist)

See also: resetMaterials(bool emitSignal = true);

Since: 2.0.4, 26 oct 2016, sl

◆ activatePropertyTypeBookmark

int activatePropertyTypeBookmark ( string bkmId )

function

Returns: -1 : Could not activate bookmark
0 : undefined
1 : OK

Since: 2.2.4, 27 oct 2018, jh

◆ addCalendarExceptions

int addCalendarExceptions	(	string	calendarID,
		array< object >	exceptions
	)

function

Set exceptions (user defined days or holidays) to calendar. Existing dates will be overwritten.

Parameters

calendarID	ID of the calendar
exceptions	List of exceptions

See also: array< object > getCalendarExceptions(string calendarID)

Since: 2.9.2, 03 Mar 2022

◆ addCheckRule

string addCheckRule	(	string	checkRunID,
		object	rule,
		string	parentRuleID = `string()`
	)

function

Add rule to check run. Only Attribute Rules can be nested.

Parameters

checkRunID	ID of (model) check run
rule	Object which defines the check rule. For rules of type 'AttributeRule', valid sub-types are 'simple' (no child rules allowed), 'conditional' and 'group'.
parentRuleID	ID of parent rule (attribute rule groups and conditional rules only)

Returns: ID (type 'AttributeRule' and 'ScriptRule') or empty string (UniquePattern)

Since: 2.9.3, 24 Mar 2022

Example:

var checkRunID = '0e40e665-a342-4948-b592-c95a6c6beca3';
var rule1 = {
    "Type": "UniquePattern",
    "Pattern": "[[cpID##xs:ID]]",
    "Comment": "Check uniqueness of GUIDs"
    };
desiteAPI.addCheckRule(checkRunID, rule1);
var rule2 = {
    "Type": "ScriptRule",
    "Name": "newRule",
    "Comment": "",
    "IsActive": true,
    "ResumeOnError": false,
    "Code": "// write some code here"
    };
desiteAPI.addCheckRule(checkRunID, rule2);
var rule3 = {
    "Type": "AttributeRule",
    "SubType": "conditional",
    "PropertyTypeKey": "ifcType##xs:string",
    "Pattern": "IfcSpace"
    };
var rule4 = {
    "Type": "AttributeRule",
    "SubType": "simple",
    "PropertyTypeKey": "Pset_SpaceCommon:IsExternal##xs:boolean",
    "Pattern": "*"
    };
var ruleID = desiteAPI.addCheckRule(checkRunID, rule3);
desiteAPI.addCheckRule(checkRunID, rule4, ruleID);

◆ addObjectListToTooltip

void addObjectListToTooltip	(	string	idList,
		string	tooltipname
	)

function

Add object list to tooltip.

Parameters

idList	List of objects
tooltipname	Name of the tooltip template

Since: 1.3.2, 28 mar 2014, jh

◆ addPropertyScript

object addPropertyScript	(	string	domain,
		string	pname,
		string	datatype,
		string	code = `string()`
	)

function

Since: 2.5.0, 10 mar 2019, jh

◆ addPropertyTypeBookmark

string addPropertyTypeBookmark ( object bookmarkConfig )

function

Add property type bookmark.

Parameters

bookmarkConfig Bookmark config information map. For format description see getPropertyTypeBookmarkByID()

Returns: ID of new bookmark. If the given ID (in the passed object) is already used, a new ID is created.

Since: 2.2.4, 27 oct 2018, jh

◆ addRangeToRegion

int addRangeToRegion	(	string	regionId,
		double	fromStation,
		double	toStation,
		string	alignmentId = `string()`
	)

function

Add an ADDITIONAL range to a region (a region can have several - possibly disjunct - ranges with the same value).

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
fromStation	Lower bound of range
toStation	Upper bound of range
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: 1 success
-1 alignment ID not found
-2 region ID not found
-3 invalid range parameters

Since: 2.2.1, 20 apr 2018, sl

◆ addRegionToAlignment

string addRegionToAlignment	(	string	alignmentId,
		object	setting
	)

function

Add a region with a first given range and value to an alignment (simplified, linear representation of a road or track).
A region is represented by a strip along an alignment with a name, value and color and is used to visualize different properties/data, indicated by a color and a value, along the alignment. Further ranges (which will get the same name, color and value) can be added to this region afterwards. At the beginning of each range, the name and the value set will be drawn (like stations).

Parameters

alignmentId	ID of alignment
options	Options, given as json object (see below).

See also: addRangeToRegion()

Example

var options =
{
    name:      'Test',
    range:     [100.0,126.5],
    value:     123.456,
    offset:    2.0,
    offsetZ:   0.0,
    width:     1.0,
    color:     '#ff00cc',
    textcolor: '#000000',
    textscale: 0.5
}

Returns: ID of region created
-1 alignment ID not found
-3 invalid settings
-4 region range outside range of alignment

Since: 2.2.1, 26 apr 2018, sl

◆ addToSelectionSetGeometry

int addToSelectionSetGeometry	(	string	setId,
		string	objectIDList
	)

function

Add objects to selection set in domain 'geometry'.

Returns: 1 Ok
-1 Selection Set not found in domain 'geometry' -2 Object not found in domain 'geometry'

Since: 2.2.2, 28 aug 2018, jh

◆ appendToFile

bool appendToFile	(	string	filePath,
		string	content,
		string	encoding = `string()`
	)

function

Append a string to a file. User does not need to take care of opening and closing the file.

Parameters

filePath	Name and path of the file to be written. If no path is given, the current project's path will be used.
content	Data to be appended to the end of the file
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64" and encode the string accordingly.

Returns: true if file was written successfully, else false

Since: 2.0.16, 27 Oct 2017; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ calcDistance

double calcDistance	(	string	objId1,
		string	objId2
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Calculate distance between two mesh objects.

Parameters

objId1	ID of first object
objId2	ID of second object

Returns: Distance, if no error occurred. If objects intersect, distance is zero.
-1 Could not find objects/wrong type.

Since: 2.2.2, 31 Aug 2018; 3.2.2, 11 Apr 2023 : deprecated

Deprecated:: Use calculateDistance() instead.

◆ calcOOBB

int calcOOBB	(	var	objectIds,
		double	eps = `0.001`
	)

function

Calculate optimized, orientated bounding box (OOBB) of all given geometric objects and set it to them. The bounding box is only calculated and set if an object has no OOBB yet.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ calcOOBBxy

int calcOOBBxy	(	var	objectIds,
		double	eps = `0.001`
	)

function

Calculate optimized, orientated bounding box in xy-plane (OOBBxy) of all given geometric objects and set it to them. The bounding box is only calculated and set if an object has no OOBBxy yet.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ calcPropertyValuesOverTime

object calcPropertyValuesOverTime	(	string	propName,
		string	propType,
		object	options
	)

function

Calculate property values over time. Returns an object with a list of property values for each day between startDay and endDay.

Options:

var options = {
    'StartDay':       '2018-09-10', // if invalid the current date is set
    'EndDay':         '2018-09-20', // if invalid the current date is set
    'VisibleTasks':   false,        // consider only visible tasks
    'CheckInherited': false,        // check inherited values
    'BaseIndex':      0             // 0 = Default, 1 = Actual, 2 = Baseline
};
var pv = desiteAPI.calcPropertyValuesOverTime( 'cpCost', 'xs:double', opt );

Return:

{
    "2018-09-10": 3.5,
    "2018-09-11": 3,
    "2018-09-12": 0,
    "2018-09-13": 0,
    "2018-09-14": 3,
    "2018-09-15": 0,
    "2018-09-16": 3,
    "2018-09-17": 3,
    "2018-09-18": 36,
    "2018-09-19": 3,
    "2018-09-20": 0
}

Since: 2.2.3, 14 Sep 2018

◆ calculateDistance

var calculateDistance	(	string	meshID1,
		string	meshID2
	)

function

Calculate distance between two mesh objects.

Parameters

meshID1	ID of first mesh
meshID2	ID of second mesh

Returns: Object containing error information, the calculated distance, and the points of closest approach of the two meshes.
Example:
{
"closestPoints": [
{
"x": 18.747232434082033,
"y": 13.39334411315918,
"z": 3.000000022888184
},
{
"x": 18.747232434082033,
"y": 13.39334411315918,
"z": 6.000000045776368
}
],
"distance": 3.000000022888184,
"error": {
"code": 0,
"message": "OK"
}
}

On error (e.g. if one of the two input IDs could not be found or is not a mesh), "closestPoints" and "distance" will be missing from the output.
If the two meshes intersect, "distance" will be 0.0.

Since: 3.2.2, 11 Apr 2023

◆ calcWorkInMinutes

int calcWorkInMinutes	(	date	start,
		date	finish,
		string	calendarID = `string()`
	)

function

Calculate working time in minutes between two given dates by specifying a calendar.

Parameters

start	Start date and time
finish	Finish date and time
calendarID	ID of calendar (if empty the default calendar is used)

Returns: 1 Ok
-1 Invalid start or finish
-2 Could not find calendar

Since: 2.8.5, 14 Oct 2021

◆ checkIfFileExists

bool checkIfFileExists ( string filePath )

function

Checks if a file exists

Parameters

filePath Name and path of the file. If no path is given, the current project's path will be used.

Returns: true if file exists, else false

Remarks: 2.4.2, 01 mar 2019, ah : changed behavior when no path is given (using project directory instead of application directory)

Since: 1.9.0, 05 jul 2016, mm

◆ checkIntersection

int checkIntersection	(	string	objId1,
		string	objId2,
		double	tolerance = `-0.00001`
	)

function

Check if two geometric objects intersects.

Parameters

objId1	: ID of object #1
objId2	: ID of object #2
tolerance	: Numerical tolerance (default -0.00001). If tolerance is set to a small negative value, objects may overlap without intersection detected. A value > 0 means approach.

Returns: 1 Objects do intersect
0 Objects do not intersect
-1 No Object with given ID objId1 or objId2 or of wrong type

Since: 1.9.0, 13 Apr 2016

◆ checkOverlapOBB

double checkOverlapOBB	(	string	id1,
		string	id2,
		double	eps = `0.001`
	)

function

Check overlap of oriented bounding boxes of two given objects. If an OOBB has not been already calculated for each object, it will be calculated with numerical precision eps (default 0.01).

Parameters

id1	ID of first object
id2	ID of second object
eps	Precision for generating missing OOBBs

Returns: A value between [0, 1] indicating the overlapping factor (of the smaller box).

Note: In case of two OBBs with the same orientation it is the exact percentage of overlap, else only a indicative value. If no geometric object exists for one of both IDs, 0.0 will be returned.

Since: 1.4.10, 01 jun 2015, sl

◆ clearCalendarExceptions

int clearCalendarExceptions ( string calendarID )

function

Removes all exceptions from a calendar.

Parameters

calendarID ID of the calendar

Returns: 1 Ok
-1 Could not find calendar

Since: 2.9.2, 03 Mar 2022

◆ clearCheckResults

int clearCheckResults ( string checkRunID )

function

Remove all check results from check.

Parameters

checkRunID ID of checkRun

Returns

1 Ok
-1 Check run with given id not found

Since: 2.9.0, 21 Sep 2021

◆ clearCheckRules

int clearCheckRules	(	string	checkRunID,
		string	ruleTypeFilter = `string()`
	)

function

Remove all check rules from check run.

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be removed. "ScriptRule" "AttributeRule" "UniquePattern"

Returns

Error code

1 Ok
-1 Check run with given id not found
-2 Unknown rule type

Since: 2.9.3, 24 Mar 2022

◆ clearWireMode

void clearWireMode ( )

function

Set all objects to normal mode, 3D view will be refreshed.

Since: 1.3.0, 13 nov 2013, jh

◆ closeFile

bool closeFile ( )

function

Close an open file. There can only be one open file at once!

Returns: true - success
false - file is not open

Since: 1.3.0, 30 Oct 2013

◆ colorCodeObjects

void colorCodeObjects	(	array< string >	objectIds,
		string	propertyName,
		string	propertyDatatype,
		double	intervalSize = `1.0`
	)

function

Assign a distinct color to objects that share a common property value.
For numerical values, an interval can be set.

Parameters

objectIds	IDs of geometric objects to color-code
propertyName	Property name
propertyDatatype	Property data type
intervalSize	[optional] Interval for grouping numerical property values (xs:int, xs:long, xs:float, xs:double). Will be ignored for properties of other types. Default is 1.0.

Since: 2.9.3, 18 Mar 2022

◆ copyFile

bool copyFile	(	string	fnFrom,
		string	fnTo
	)

function

Copy file 'fnFrom' to file 'fnTo'.

Since: 2.0.18, 31 jan 2018, jh

◆ countLocked

int countLocked ( )

function

Count locked objects.

Returns: Number of locked objects

Since: 1.3.6, 25 apr 2014, jh

◆ countWired

int countWired ( )

function

Count objects which are in wireframe mode.

Since: 1.9.0, 03 mar 2016, sl

◆ createCalendar

string createCalendar	(	string	name,
		string	comment
	)

function

Create a new calendar.

Parameters

name	Name of calendar (should be unique, must not be empty)
comment	Comment

Returns: ID of calendar created.

Since: 2.9.2, 03 Mar 2022

◆ createColorSchema

string createColorSchema	(	string	setContainerId,
		string	name
	)

function

Create color schema with given name from the hierarchy (content) given by a container.

Parameters

setContainerId	ID of container whose content defines the color schema. For each contained container a material is created with the container names.
name	Name of new color schema. If name already exists it is augmented by an index, e.g. '~(2)'.

Returns: Name of new Color Schema

Since: 1.0.20, 18 jan 2013, jh

◆ createColorSchemaFromCurrentMaterials

string createColorSchemaFromCurrentMaterials	(	string	name,
		bool	updateExisting,
		object	options = `object()`
	)

function

Create color scheme with given name from current material settings.

Parameters

name	Name of new color scheme
updateExisting	If 'true' an already existing color scheme is updated, otherwise a new color scheme is created. If name already exists it is augmented by an index, e.g. '~(2)'.
options	See below for possible keys and values

Options:

{
    legend: true
}

Returns: Name of new color scheme.

Since: 1.3.0, 15 nov 2013, jh

◆ createContactObject

string createContactObject	(	string	parentId,
		string	objId1,
		string	objId2,
		string	matId,
		object	options = `object()`
	)

function

Create contact object (contact surface) between two objects. If angle > 0, the resulting surface may differ for each object. In this case the projection on object 1 ist choosen.

Parameters

parentId	: ID of container the newly created object should be added.
objId1	: ID of object 1.
objId2	: ID of object 2.
matId	: ID of material of the newly created object. If empty, a default material (dark orange) will be chosen.
options	: Options encoded as JSON. If not specified, the default values of the code snipped (see below) will be chosen.

Returns: ID of new object, else "" if no contact could be calculated, or
-1 - error, object 'objId1' not found or of wrong type
-2 - error, object 'objId2' not found or of wrong type
-3 - error, IContainer 'parentId' not found or of wrong type
-4 - error, model not found or model is read-only

var opt = {
    locflag: 7,   // 1 = contact at top, 2 = contact at bottom, 4 = contact at sides (and combinations)
    tol: 0.001,   // maximum distance tolerance [m]
    oppdir: true, // flag that indicates that normal vectors of contacting faces must point in opposite directions
    angle: 2.0    // maximum angle deviation between normal vectors of opposite faces [�]
}
var idnew = desiteAPI.createContactObject( parentId, id1, id2, "", opt );

Since: 1.5.0, 07 Jan 2015

◆ createDirectory

int createDirectory	(	string	path,
		string	dirName
	)

function

Create new directory at given file path. Resulting directory path is path + '/' + dirName.

Parameters

dirName	Name of new directory
path	File path of directory in which new directory should be created (relative paths are allowed)

Returns: error code:
1 - success
0 - directory already exists, no changes
-1 - error -2 - execution blocked

Since: 1.5.0, 16 Mar 2016

◆ createMaterial

string createMaterial	(	string	matXml,
		string	modelId = `string()`
	)

function

Create a new material for visualization. If the material already exists the existing material is not changed.

Parameters

matXml	Material encoded as XML. If a tag is missing, default values are set.
modelId	Create a new material in this model. If the model is not found or the string is empty (default) the default model of the geometry project is used.

Returns: ID of new material, empty string if material could not be created.
If the material already exists, the existing material is returned.
An existing material can be located in an other model than 'modelId'.

Example:

var matXml =
'<material ID="default-mat-11" name="default-mat-11"> \
 <diff r="140" b="40" g="150" a="1"/> \
 <amb r="140" b="40" g="150" a="1"/> \
 <spec r="255" b="255" g="255" a="1"/> \
 <trans v="0"/> \
 <shin v="0.5"/> \
 </material>';
var matId = desiteAPI.createMaterial(matXml,'12345');

See also: deleteMaterial()

Since: 1.0.20, 14 jan 2013, jh

◆ createModel

string createModel	(	string	name,
		bool	createRootC = `true`,
		string	domain = `"geometry"`
	)

function

Create a new model in a specified domain.

For models within the geometry and documents domain, a root container has to be created. to access the rootnode in the model use method getRootNodeByModel(). The model itself is not visible in the GUI.

Parameters

name	Name of model
domain	Domain in which the model is created.
createRootC	If true, create a root container (in domain 'geometry': a container on which transformations can be applied) with the same name as the new model (only for domains: geometry/documents!)

Returns: ID of new model.
-1 Model could not be created.
-2 Domain is unknown or not unique

Since: 1.3.0, 21 Jan 2014

◆ createObject

var createObject	(	string	parentID,
		object	objectMap
	)

function

Create an object encoded as a JavaScript object map.
If a key "ID" is not given or if the ID is already used, a new ID will be generated.

Parameters

parentID	ID of parent container
objectMap	JavaScript object; see examples below

Returns: either ID of newly created object or one of the error codes listed below

Error Codes:

 0 : Undefined
-1 : Could not find parentId
-2 : parent (identified by parentId) is not a container or does not have the required type
-3 : could not find model of parentId
-4 : could not create new object
-5 : parsing Error
-10 : unsupported object type (tag name)

DOMAIN ISSUES

Available objects

container
issue
viewpoint

Examples

{"container": {"ID": "IdOfIssuesContainer", "name": "container-1"}}

{
    "issue": {
        "ID": "98f7ae3f-403a-413e-a3ae-e8b8b2a9fed7",
        "name": "issue-1",
        "description": "Some description.",
        "status": "Open",
        "assignedTo": "someone@thinkproject.com",
        "priority": "Normal",
        "due": "2021-11-25T12:00:00.000"
    }
}

The elements "description", "status", "assignedTo", "priority" and "due" are optional. If "status" or "priority" are omitted, default values will be set according to the project configuration.
If the project is configured to only allow a fixed set of values for Priority and/or Status, non-compliant values are replaced by defaults.
IDs of issues must be GUIDs.

{
    "viewpoint": {
        "ID": "950a65f2-3590-48ca-9e7b-0409063116ce",
        "camera": { ... },
        "clippingPlanes": [ ... ],
        ...
        }
}

See ProjectAPI::getViewpointData() for a full example of all the data fields.

Since: 1.0.17, 16 Jun 2012, for creating empty attribute objects; 2.9.0, 24 Nov 2021, re-implemented as a way to create objects from JS objects

◆ createObjectFromXml

string createObjectFromXml	(	string	parentId,
		string	objectXML
	)

function

Create a new object encoded by XML.
If ID (attribute ID="..." in code) is not given or is already used in the project, a new ID will be created.
If the attribute matID is used, the material must exist in the same model as the object! If this attribute is not used, a default material will be created in the same model as the object.

Parameters

parentId	ID of parent element
objectXML	XML code

Returns: ID of new object, else
error code if object cannot be created.

Error Codes:

 0 : Undefined
-1 : Could not find parentId
-2 : parent (identified by parentId) is not a container or does not have the required type
-3 : could not find model of parentId
-4 : could not create new object
-5 : parsing Error
-10 : unsupported object type (tag name)

DOMAIN GEOMETRY

Available objects

<object3D>
<objectLines>
<objectText>
<genericObject>
<container>
<objectProxy>
<objectPoint>

Examples

<object3D ID="ABCxyz123" name="object-1" matID="mat-abcxyz" >
 <p nr="0" x="1.0" y="1.0" z="1.5" />
 <p nr="1" x="10.0" y="20.0" z="1.5" />
 <p nr="2" x="1.0" y="10.0" z="1.5" />
 <t p1="0" p2="1" p3="2" />
</object3D>

<objectLines ID="ABCxyz123" name="line-1" matID="mat-xyz">
 <p nr="0" x="1.0" y="1.0" z="1.5" />
 <p nr="1" x="10.0" y="20.0" z="1.5" />
 <l p1="0" p2="1" />
</objectLines>

<objectText ID="ABCxyz123" name="text-1" matID="mat-xyz">
  <textItem c="Der Text" h="1.0" rx="0.0" ry="0.0" rz="0.0" x="0.0" y="0.0" z="0.0"></textItem>
</objectText>

<container ID="IdOfContainer" name="container-1" />
// create composite
<container ID="idabc" name="c1" composite="true" />

<objectPoint ID="IdOfPoint" name="point-1" matId="mat-xyz">
  <p x="1.0" y="1.0" z="1.5" />
</objectPoint>

DOMAIN ACTIVITIES

Available objects

<task>

Note: If WBS is empty, it will be automatically created from parent task WBS and child index of the new task.

Examples

DOMAIN BUILDING STRUCTURE

Available objects

Available types:

typeBsUnknown
typeBsContainer
typeBsSection (general containment)
typeBsSite
typeBsBuilding
typeBsBuildingStorey
typeBsLevel (arbitrary level)
typeBsUnit (e.g. an apartment unit)
typeBsSpace (room)
typeBsLocation (any location point)
typeBsAlignment (e.g. road)
typeBsStation (station point of alignment)
typeBsSegment (e.g. line, curve or spiral)
typeBsTakt
typeBsGroup (group, zone, system)

Examples

Create two nested sections in the building structure

var objXml = '<section name="Building A" type="typeBsBuilding"/>';
var id = desiteAPI.createObjectFromXml( parentId, objXml );
objXml = '<section name="00EG" type="typeBsBuildingStorey"/>';
var id2 = desiteAPI.createObjectFromXml( id, objXml );

DOMAIN DOCUMENTS

Available objects

<document>
<documentDir>
<container>

Examples

<document ID="xyz123" path="C:/file.json" created="2016-03-16T12:27:34" createdBy="user" refDateTimeStart="" refDateTimeFinish="">
    <location refID="abc321" lon="45.55523" lat="7.04567" refFrom="" refTo="" />
</document>

Note that a "document" object can be used either as a file link or as a URL.
A "documentDir" will scan contained directories recursively, so deeply nested directory structures may incur a performance penalty.

DOMAIN BoQ (Bill of Quantities)

Available objects

<item>

Examples

<item wbs="1.1" ID="3" name="newItem" type="2">
   <attr>
     <qty>0</qty>
     <unit></unit>
     <up>0</up>
   </attr>
 </item>

Available types:
1 - Category (LV-Bereich)
2 - BOQ-Item (LV-Position)
3 - Markup Item (Zuschlagsposition)
4 - Remark (Hinweistext)
5 - Performance Description (Ausfuehrungsbeschreibung)
6 - Sub-Description (Unterbeschreibung)
7 - Invalid, reserved for internal use
8 - AddText (Zusatztext)
9 - Take-Off Sheet (Aufmassblatt)
10 - Take-Off Row (Aufmasszeile)

qty is the quantity as floating point number (double). unit is the unit of measurements as text. up is the unit price as a floating point number (double).

Example JavaScript:

var id = desiteAPI.createID();
var xml = '<item wbs="1.1" ID="' + id + '" name="Stahlbeton Decken" type="2"> \
    <attr> \
        <qty>10.123</qty> \
        <unit>m2</unit> \
        <up>0</up> \
    </attr> \
</item>';
var parentId = '32b098cf-6942-4abf-a9fc-81fe229db767';
var ret = desiteAPI.createObjectFromXml( parentId, xml );
ret;

DOMAIN RESOURCES

Available objects

Examples

var parentId = '';
var c = desiteAPI.itByFilter( 'cpName', 'xs:string', '*TRANSPORT*', false, 'res' );
if( c == 0 ) {
    // create model, get id of root node
    var id = desiteAPI.createModel( "TRANSPORT", false, 'res' );
    parentId = desiteAPI.getRootNodeByModel( id );
} else {
    // use first element in list as parent
    parentId = desiteAPI.itNext();
}
var xmlStr = '<resourceItem name="T1"/>';
desiteAPI.createObjectFromXml( parentId, xmlStr );
xmlStr = '<resourceInstance name="T2"/>';
desiteAPI.createObjectFromXml( parentId, xmlStr );

DOMAIN TYPES

Available objects

Examples

ID, prefix and comment are optional.

DOMAIN PROCESS COMPONENTS

Available objects

Examples

DOMAIN CLASH DETECTION

Available objects

<cdRun>

Examples

DOMAIN MODEL CHECK

Available objects

Examples

DOMAIN ISSUES

Available objects

<container>
<issue>
<viewpoint>

Examples

<issue ID="98f7ae3f-403a-413e-a3ae-e8b8b2a9fed7" name="issue-1">
    <description>Some description.</description>
    <status>Open</status>
    <assignedTo>someone@thinkproject.com</assignedTo>
    <priority>Normal</priority>
    <due>2021-11-25T12:00:00.000</due>
</issue>

The elements "description", "status", "assignedTo", "priority" and "due" are optional. If "status" or "priority" are omitted, default values will be set according to the project configuration.
If the project is configured to only allow a fixed set of values for Priority and/or Status, non-compliant values are replaced by defaults.
IDs of issues must be GUIDs.

<viewpoint ID="950a65f2-3590-48ca-9e7b-0409063116ce" name="API Demo">
    <camera>
        ...
    </camera>
    <clippingPlanes>
        ...
    </clippingPlanes>
    ...
</viewpoint>

See ProjectAPI::getViewpointData() for a full example of all the data fields, which then must be adapted into XML elements.
Prefer using createObject(), which accepts data in JavaScript object format rather than XML.

Since: 1.5.0, 06 Jul 2015; 2.0.8, 05 Jan 2017, support for domain BoQ; 2.0.11, 04 Apr 2017, support for domain Resources; 2.1.0, 24 Apr 2017, support for domain Types; 2.2.1, 25 May 2018, support for domain ProcessComponents; 2.4.1, 31 Jan 2019, support for containers in domain Documents; 2.4.3, 28 May 2019, support for types 9 and 10 in domain BoQ; 2.5.4, 08 Feb 2020, attribute "type" added to "section" element in domain BuildingStructure; 2.9.0, 24 Nov 2021, support for domain Issues

◆ createPropertyType

int createPropertyType	(	string	propName,
		string	propDatatype,
		string	uomCode,
		bool	isInh,
		int	target,
		string	domainName = `"all"`
	)

function

Returns: 0 undefined
1 Property Type created
2 Property Type already exists
-1 Error, could not create Property Type
-2 Error, undefined target

Parameters

uomCode	Unit of Measurement
target	1 - Project Repository 2 - Database

Since: 2.0

◆ createSelectionSet

string createSelectionSet	(	string	name,
		string	parentID = `string()`
	)

function

Parameters

name	Name of new Selection Set
parentID	Parent of new Selection Set. If empty the set is created on top level.

Since: 2.5.1, 30 apr 2019, jh

◆ createSelectionSets

string createSelectionSets	(	string	propertyTypes,
		string	rootName,
		object	config = `object()`
	)

function

Create selections sets of geometry objects.
For each value of a given property type a selection set is created.

Parameters

propertyTypes

A concatenation of Property Type Keys, each containing a name and datatype.
Example:

'cpName##xs:string;cpVolume##xs:double'

Prior to version 2.2.1, it was only possible to give a single property name, and the type was always String. Example: 'cpName'.
This is still possible, but deprecated.

Parameters

rootName Name of the Selection Set Container to be created. If the name is empty, the name is constructed from property type key names. If the name is already used, a suffix will be added.

config

Object/map containing options.

Default Values:
{
"maxItems" : 0,
"considerCompositeParts" : true,
"considerOpenings" : true,
"considerParts" : true,
"intervalSize" : 0.5,
"visibleOnly" : false,
"createAsSmartSet" : false
}
Note:
The option "visibleOnly":true only works for selection sets, not smart sets
If "maxItems" is greater the zero, this will define the maximum allowed nesting depth (used property types)

Usage examples:

desiteAPI.createSelectionSets('cpName', 'selSet1');             // deprecated!
desiteAPI.createSelectionSets('cpName##xs:string', 'selSet2');  // better! (since 2.2.1)
desiteAPI.createSelectionSets('cpName##xs:string; cpVolume##xs:double', 'selSet3', { intervalSize: 1.0 });

Returns: ID of new selection sets.
Empty string if selection set could not be created.

Since: 1.4.0; 2.2.1, 07 Aug 2018 : extended first parameter to support list of Property Type Keys; 2.8.4, 13 Aug 2021 : extended options to consider visible object only; 2.8.5, 11 Dec 2021 : extended options to create smart sets

◆ createTimeSchedule

int createTimeSchedule ( object config )

function

Create a time schedule from building structure and process components (Tools 4D).

Parameters

config

Calculation settings

{
    'pcRootID' : 'dab8cd58-e961-4419-87f8-d493261bd540',    // ID of process components root node
    'bsRootID' : '5c3abb0e-47b4-42e6-91a5-116a3eb38cc8-oh', // ID of building structure root node
    'calendarID' : '',                                      // ID of calendar (optional). If empty, the default calendar is used
    'projectStart' : '2022-01-03T08:00:00'                  // Project start date/time (ISO string or Date) (optional). If empty, the current date is used
}

Returns: 1 - Ok
0 - No Tools4D module
-1 - Error, could not find element 'pcRootID'
-2 - Error, could not find element 'bsRootID'
-3 - Error, could not find calendar
-4 - Error, invalid date/time

Since: 2.9.2, 18 Mar 2022

◆ createWireModeSchema

string createWireModeSchema	(	string	ids,
		string	wmName,
		bool	overwrite = `false`
	)

function

Create a wire mode schema for objects.

Parameters

ids	String of semicolon-separated object IDs
wmName	Name of new wire-frame mode
overwrite	If 'true' an existing schema will be overwritten with current settings (default: 'false')

Returns: Name of the schema created

Since: 1.3.0, 13 nov 2013, jh

Remarks: 1.9.0, 17 Jun 2016, ar, changed to return name of the schema created

◆ csvClose

bool csvClose ( )

function

Finish/cleanup of reading a CSV file, started by csvOpen().

Returns: false if there's no active CSV file

Since: 2.2.4, 30 Oct 2018

◆ csvHasNextLine

bool csvHasNextLine ( )

function

Checks if CSV file opened by csvOpen() has another line of data.

See also: csvNextLine()

Returns: true if CSV file has another line of data.

Since: 2.2.4, 30 Oct 2018

◆ csvNextLine

array< string > csvNextLine ( )

function

Returns next line of a CSV file initialized by csvOpen().

Returns: cell data as array of strings (or empty array if no CSV file has been opened, or end of file reached)

See also: csvHasNextLine()

Since: 2.2.4, 30 Oct 2018

◆ csvOpen

int csvOpen	(	string	filePath,
		string	delimiter = `";"`,
		string	encoding = `"Windows-1252"`
	)

function

Open text file in CSV format for reading.

Parameters

filePath	Name and path of file (if path is missing, file is expected in the project directory)
delimiter	One character as delimiter of cells, most common are semicolon or tab.
encoding	File Encoding, by default "Windows-1252". Other options are "UTF-8", "UTF-16", "ISO 8859-1".

Returns: 1 - successful
-1 - invalid parameter (wrong length of delimiter or unrecognized encoding)
-2 - unused since 3.2.3 (treat like -1) -3 - file not found
-4 - error reading file
-5 - execution blocked

Since: 2.2.4, 30 Oct 2018; 2.4.5, 13 Aug 2019 : changed behavior when no path is given (using project directory instead of application directory); 3.2.3, 11 May 2023 : re-implemented to support multibyte characters, added optional encoding parameter

◆ currentGeoPosition

object currentGeoPosition ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Returns the current geo position, this is the cached position signaled by geoPositionUpdated.
Location tracking has to be active, otherwise call desiteAPI.enableGeoLocation.

Returns: {
"Lat": 35.23028571362665,
"Lon": 37.6603185283756
}

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI; 3.1.0, 27 Jun 2022 : deprecated

Deprecated:: The function is not useful when called immediately after enableGeoLocation(), as the sensor won't have any data yet.
Instead, connect to signal geoPositionUpdated.
If you only want a "one shot", you can disconnect immediately after having received the geo data:

desiteAPI.enableGeoLocation();
desiteAPI.geoPositionUpdated.connect(function onGeoPositionUpdated(pos)
{
    console.log('Latitude: ' + pos['Lat'] + ', Longitude: ' + pos['Lon']);
    desiteAPI.geoPositionUpdated.disconnect(onGeoPositionUpdated);
    desiteAPI.disableGeoLocation();
});

◆ cutObject

array< string > cutObject	(	string	parentId,
		string	objId,
		object	plane = `object()`,
		bool	closeCuts = `true`,
		bool	splitUnconnectedParts = `true`
	)

function

Cut object into subparts.

Parameters

parentId	ID of parent container. If empty, subparts will be added to object.
objId	ID of object
plane	Cutting plane encoded as JSON. If not specified, the default values of the code snipped (see below) will be chosen.
closeCuts	Close mesh of cut parts.
splitUnconnectedParts	Split cut parts which are not connected (e.g. when cutting an U-shape horizontally).

Returns: ID list of subparts, empty list if an error occurs.

Example: Cut object ID="ABCxyz123" by xy-plane (through origin) and append parts to object (parent=""):

var plane = {
    px : 0.0,
    py : 0.0,
    pz : 0.0,
    nx : 0.0,
    ny : 0.0,
    nz : 1.0,
}
var idList = desiteAPI.cutObject( "", "ABCxyz123", plane );

Since: 1.5.0, 05 Aug 2015

◆ dbAssertTable

int dbAssertTable	(	string	tableName,
		array< string >	columnsList
	)

function

Check if database has a specific table with certain columns.

Parameters

tableName	Table name
columnsList	List of columns specified in the format [columnname columndatatype]

Example:

var tblName = "TestTable";
var colList = [ 'RecID string', 'colNmbr real' ];
desiteAPI.dbAssertTable( tblName, colList );

Returns: 1: Ok
-1: No database connection
-2: Failed to create table
-3: Execution blocked

Since: 2.0

◆ dbCheckIn

void dbCheckIn ( )

function

Database check-in.

Since: 1.0.17, 18 jul 2012, jh

Remarks: 1.5.0, 15 dec 2014, moved to class AutomationAPI

◆ dbCheckOut

void dbCheckOut ( array< string > propList )

function

Check out properties in local database. Only properties which are checked out can be edited. All other properties are locked in local database.

Parameters

propList List of properties in such format: propName##propType

Since: 1.0.17, 18 jul 2012, jh

◆ dbClearCache

int dbClearCache	(	string	propName,
		string	propType
	)

function

Returns: 1 - Ok
-1 - Error

Since: 1.3.6, 28 apr 2014, jh

◆ dbClearCacheAll

void dbClearCacheAll ( )

function

See also: To setup cached values see also itSetupDbCache()

Since: 1.3.6, 28 apr 2014, jh

◆ dbClose

bool dbClose ( )

function

Close the currently connected DB. Returns false if no DB was connected.

Since: 2.4.1, 2019-01-28, ah

◆ dbDeleteProperty

int dbDeleteProperty	(	string	objIdList,
		string	propName,
		string	propType
	)

function

Delete properties from database.

Parameters

objIdList The properties are removed and deleted from these objects.

Returns: 0 undefined
-3 execution blocked
-4 database is not open
-5 no objects found in domain projects

Since: 1.4.9, 12 dec 2015, jh

◆ dbEndQueryExec

bool dbEndQueryExec ( )

function

Free all resources bound to the last dbQueryExec.

Returns: true if there was an open dbConnection and has been closed successfully

Since: 2.1.6, 02 mar 2018, ar

◆ dbGetFilepath

string dbGetFilepath ( ) const

function

If the connected DB is file-based, returns the filename and path. Otherwise, an empty string is returned.

Since: 2.4.1, 2019-01-17, ah

◆ dbGetImmediateUpdate

bool dbGetImmediateUpdate ( )

function

See also: dbSetImmediateUpdate()

Since: 1.3.0, 14 nov 2013, jh

◆ dbIsLocalCopy

bool dbIsLocalCopy ( )

function

Check if current database is a local copy.

Since: 1.0.17, 18 jul 2012, jh

◆ dbOpen

int dbOpen ( const var connectionData = var() )

function

Open and connect a project database. Will do nothing if a database connection is already open.
Pass connection data as object.

Example:

{
    "FileName": "C:/db/test.db"
}

You can pass an empty object or no connection data at all. In that case, a DB will be opened with default parameters (in the current project's directory). Project must have been saved first.

Returns: 1 - Success
2 - DB already open and connected
-1 - Connection Error
-2 - Input Error (e.g. FileName missing and no project open)
-3 - Execution blocked

Since: 2.4.1, 2019-01-28, ah

◆ dbQueryExec

bool dbQueryExec ( string sqlQuery )

function

Create a database query by a SQL statement. To iterate over the query result use dbQueryNext() and get the values of the current record by dbQueryValue().

Parameters

sqlQuery Database query as SQL statement

Returns: true - success
false - query has failed

Since: 1.0.18, 14 aug 2012, jh

◆ dbQueryLastError

string dbQueryLastError ( )

function

Get the error message that the last executed SQL query returned (if any).

Since: 2.3.1, 12 dec 2018, ah

◆ dbQueryNext

bool dbQueryNext ( )

function

Go to next record of last query.

Returns: true - success
false - iterator is at end, no next query

See also: dbQueryExec()

Since: 1.0.18, 14 aug 2012, jh

◆ dbQueryRecordset

object dbQueryRecordset	(	string	sqlQuery,
		string	key,
		int	maxNumberOfRows = `0`
	)

function

Create a database query by SQL statement.

Parameters

sqlQuery	the SQL query string.
key	the field name used as key in record set returned. For more than one key value only the last one will be returned.
maxNumberOfRows	max number of rows in result set returned, left open or 0 for unlimited.

Example call: desiteAPI.dbQueryRecordset("SELECT matchKey, price FROM tblPrices", "matchKey", 0);

Returns: object holding a 'recordset' as a 2-dimensional array.

Example:

{
    "recordSet": {
        "96.62.003.0160": [424.7039],
        "96.62.003.0170": [424.70398],
        "96.62.004.0000": [0]
        },
    "fieldNames": [price],
    "key": "matchKey",
    "rowsFetched": 3,
    "rowsRequested": 0
}

Since: 2.1.6, 18 mar 2018, ar

◆ dbQueryValue

var dbQueryValue ( int column )

function

Since: 1.0.18, 14 aug 2012, jh

◆ dbSetImmediateUpdate

void dbSetImmediateUpdate ( bool )

function

See also: dbGetImmediateUpdate()

Since: 1.3.0, 14 nov 2013, jh

◆ deleteColorSchema

int deleteColorSchema ( string namePattern )

function

Remove and delete color scheme by name (pattern).

Parameters

namePattern Name of the color scheme that should be deleted. Could be a pattern such as 'csXYZ*', which means that all CS which name starts with 'csXYZ' are removed and deleted.

Returns: Number of deleted color schemes.

Since: 2.2.1, 04 jul 2018, jh

◆ deleteMaterial

int deleteMaterial ( string matId )

function

Delete material with given ID. Only materials of the default model which are not used (e.g. by north arrow) can be deleted.

Parameters

matId ID of material to be deleted

Returns: ErrorCode
1 - Success
-1 - Material could not be found
-2 - Material could not be deleted

Since: 1.0.20, 14 jan 2013, jh

◆ deleteModel

int deleteModel ( string id )

function

Delete Model.

Contained elements are removed from all locations where they are used (links, viewpoints, ...) and will be deleted afterwards.

Parameters

id	ID of model

Returns: Error Code:
1 - Ok, model was deleted
-1 - Error, ID does not exist
-2 - Error, model is write protected
-3 - Error, model could not be removed

Since: 2.0.13, 25 Apr 2017

◆ deleteObjects

int deleteObjects ( string idList )

function

Delete and remove one or more objects or containers. Model root nodes will not be deleted!

Contained elements are also removed and deleted. Also these elements are removed from all other locations where they are used (links, viewpoints, ...)

Parameters

idList List of object/container IDs separated by ';'

Returns: Number of deleted objects and containers

Since: 1.3.0, 02 jan 2014, jh

◆ deleteProperty

int deleteProperty	(	string	objId,
		string	propName,
		string	propDatatype
	)

function

Delete property 'propName' with data type 'propDatatype' from the element identified by 'objId'.

Parameters

objId ID of element. Use 'GlobalProject' to remove and delete a global project property.

Returns: 0 - undefined
1 - ok, property does not exist for given object
2 - ok, property has been deleted
-1 - error, object 'objId' not found
-2 - error, no model found in which obj is contained
-3 - error, model is read only
-4 - error deleting a db or core property

Since: 1.5.0, 14 mar 2015, jh

◆ deletePropertyType

int deletePropertyType	(	string	propertyName,
		string	propertyDatatype,
		string	domainName = `"all"`
	)

function

Remove property type from domain. All affected properties will be deleted.
Note that for DB property types, this will only work if the type is defined for a single domain only. (To delete DB property types across all domains, use the database widget.)

Parameters

propertyName	Name of property type
propertyDatatype	Data type of property type
domainName	Name of domain (default: "all", combinations are allowed)

Returns: 1 - ok
0 - undefined
-1 - error, empty propertyName
-2 - error, invalid propertyType
-3 - error, invalid domainName
-4 - property type could not be deleted

Since: 1.5.0, 14 Dec 2015

◆ disableGeoLocation

void disableGeoLocation ( )

function

Disable tracking of your current geo location.

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ enableGeoLocation

void enableGeoLocation ( int msecInterval = 60 )

function

Enable tracking of your current geo location, position will be updated by given interval in milliseconds.

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ endProjectTransaction

int endProjectTransaction ( string domain = "geometry" )

function

Finish transaction on project of given domain.

See also: startProjectTransaction()

Returns: number of currently open project transactions

Since: 2.2.1, 02 aug 2018, sl

◆ endTransaction

bool endTransaction ( )

function

Finish database transaction.

Since: 1.0.18, 20 aug 2012, jh

◆ fileChunkReceived

void fileChunkReceived ( string data )

signal

Emitted by readFileInChunks() for transmitting data.

See also: readFileInChunks()

Since: 3.2.5, 22 Aug 2023

◆ filterByProperty

array< string > filterByProperty	(	array< string >	inputList,
		string	propertyName,
		string	propertyDatatype,
		string	filterPattern,
		bool	checkInherited = `true`,
		string	domains = `"geometry"`
	)

function

Apply a property filter on a list of elements.

Parameters

inputList	Source list of element IDs that the filter will be applied to
propertyName	Property name
propertyDatatype	Property data type ('xs:string', 'xs:double', 'xs:long', ...)
filterPattern	Filter string. This can either be in standard DESITE filter format (supports asterisks, space means OR, not case sensitive) or a Regular Expression in JavaScript notation.
checkInherited	[optional] Check inherited properties, too (true by default)
domains	[optional] Domain(s) to be checked ('geometry' by default)

Returns: List of element IDs that passed the filter

Example:
Filter and show geometric elements with more than 100 vertices and which names begin with "Basic"

var filteredList = desiteAPI.getAllElements('geometry');
filteredList = desiteAPI.filterByProperty(filteredList, 'cpCountVertices', 'xs:long', '>100', false, 'geometry');
filteredList = desiteAPI.filterByProperty(filteredList, 'cpName', 'xs:string', 'Basic*', false, 'geometry');
desiteAPI.showElementsOnly(filteredList);

Since: 2.9.3, 17 Mar 2022

◆ filterByStatus

array< string > filterByStatus	(	array< string >	inputList,
		string	status,
		bool	value = `true`,
		string	domains = `"geometry"`
	)

function

Apply a status filter on a list of elements.

Parameters

inputList	Source list of element IDs that the filter will be applied to
status	Status as string, one of ['visible', 'selected', 'wired', 'locked']
value	[optional] Value of status, either true (default) or false
domains	[optional] Domain(s) to be checked ('geometry' by default)

Returns: List of element IDs that passed the filter

Example:
Filter for selected geometric elements

var filteredList = desiteAPI.getAllElements('geometry');
filteredList = desiteAPI.filterByStatus(filteredList, 'selected', true, 'geometry');
console.log(filteredList);

Since: 2.9.3, 17 Mar 2022

◆ findContainerByName

string findContainerByName	(	string	parentId,
		string	name,
		string	lookupDomain = `"all"`
	)

function

Get container with name 'name' and parent node 'parentId'. If the container does not exist, an empty string is returned.
Note that a name is not necessarily unique; this method will only return the first match.

Parameters

parentId	Parent node ID
name	Name of the container
lookupDomain	Lookup container 'name' in this domain, default = 'all'

Returns: container ID

Since: 1.5.0, 10 Dec 2014

◆ findDocumentsByDate

array< string > findDocumentsByDate	(	date	start,
		date	end,
		array< string >	idList = `array< string >()`,
		bool	useRef = `false`
	)

function

Get documents where the creation date is between a given range or where the reference date is between a given range.

Parameters

start	Start of date range
end	End of date range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.
useRef	(optional) Flag determining if documents are searched by their create or reference date

Since: 2.0.0, 20 jun 2016

◆ findDocumentsByLocationGk

array< object > findDocumentsByLocationGk	(	double	rw,
		double	hw,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point in Gauss-Krueger coordinates by a given distance.

Parameters

rw	'Rechtswert' (x-coordinate) of search point
hw	'Hochwert' (y-coordinate) of search point
distance	Search range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.

Since: 2.0.0, 20 Jun 2016

◆ findDocumentsByLocationGps

array< object > findDocumentsByLocationGps	(	double	lat,
		double	lon,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point in GPS coordinates by a given distance.

Parameters

lat	Latitude of search point
lon	Longitude of search point
distance	Search range
idList	(optional) List of IDs of documents. If empty, all documents will be considered.

Since: 2.0.0, 20 Jun 2016

◆ findDocumentsByLocationRangeGps

array< object > findDocumentsByLocationRangeGps	(	array< string >	gpsCoordinates,
		double	distance,
		array< string >	idList = `array< string >()`
	)

function

Get documents which are located around a given point list in GPS coordinates by a given distance.

Parameters

gpsCoordinates	List of GPS coordinates (lat/lon) as string, delimited by ';', e.g. ['51.4556;7.0116',...]
distance	Search range
idList	(optional) List of IDs of documents

Since: 2.0.0, 20 Jun 2016; 3.0.0, 19 Apr 2022 Changed delimiter from '#' to ';' as used by properties

◆ geoPositionUpdated

void geoPositionUpdated ( object pos )

signal

Emitted when current geo position got updated.
Location tracking has to be active (call desiteAPI.enableGeoLocation).

Example:

desiteAPI.geoPositionUpdated.connect(function(pos)
{
    console.log('Latitude: ' + pos['Lat'] + ', Longitude: ' + pos['Lon']);
});

Since: 2.9.0, 11 Oct 2021; 3.1.0, 04 May 2022 : moved from CoreAPI

◆ getAllElements

array< string > getAllElements ( string domainFilter = "geometry" )

function

Get IDs of all elements as an array.

Parameters

domainFilter Get all IDs of given domain(s)

Returns: List of element IDs

Since: 2.2.4, 06 Nov 2018; 3.1.3, 02 Dec 2022 : moved from ProjectAPI to AutomationAPI

◆ getAsJSON

object getAsJSON ( string objId )

function

Get geometric object data.

Example:

var objidList = desiteAPI.getSelected();
var idList = objidList.split(';');
for ( n in idList ) {
    var id = idList[n];
    if( id.length < 1 ) continue;
    var objJSON = desiteAPI.getAsJSON(id);
    console.log( JSON.stringify(objJSON, undefined, 2) );
}

A 3D-object that contains vertices, triangles and faces (uv is available only if texture is attached on the surface).
Note: the triangle list - unlike the face list - is not grouped; each consecutive triple of vertex indices forms a triangle
Example Result:

{
  "ElementType": "surface",
  "ID": "ccf5ac9b-6eeb-4134-a9d0-558bf92b9a8e",
  "Name": "Basisdecke [2409746]",
  "faceList": [
    [
      0,
      1
    ]
  ],
  "triangleList": [
    0,
    1,
    3,
    3,
    2,
    0
  ],
  "uv": [
    105.5401840209961,
    152.18524169921875,
    105.5401840209961,
    134.1296844482422,
    126.3735122680664,
    134.1296844482422,
    126.3735122680664,
    134.1296844482422,
    126.3735122680664,
    152.18524169921875,
    105.5401840209961,
    152.18524169921875
  ],
  "vertexList": [
    18.99723345336914,
    27.393344219970704,
    2.600000019836426,
    18.99723345336914,
    24.143344921875002,
    2.600000019836426,
    22.74723246459961,
    27.393344219970704,
    2.600000019836426,
    22.74723246459961,
    24.143344921875002,
    2.600000019836426
  ]
}

Since: 2.1.0, 2017-05-30, jh; 2.7.3, 2021-01-11, ek: faceList added

◆ getBBoxMaxX

double getBBoxMaxX ( )

function

Get maximal x-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMaxY

double getBBoxMaxY ( )

function

Get maximal y-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMaxZ

double getBBoxMaxZ ( )

function

Get maximal z-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinX

double getBBoxMinX ( )

function

Get minimal x-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinY

double getBBoxMinY ( )

function

Get minimal y-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBBoxMinZ

double getBBoxMinZ ( )

function

Get minimal z-coordinate of overall bounding box of all geometric objects (visible and hidden) in the project.

Since: 1.4

◆ getBoundingBoxCommon

object getBoundingBoxCommon ( var objectIds )

function

Get common bounding box of all given objects. If an object ID represents a composite (geometric container), all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with min and max coordinates of bounding box, e.g.
{
minX: 0.0,
minY: 0.0,
minZ: 0.0,
maxX: 2.0,
maxY: 2.0,
maxZ: 2.0
}

Since: 1.4.10, 10 Jun 2015; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getCalendarByName

string getCalendarByName ( string name )

function

Get first calendar with given name.

Parameters

name	Name of calendar

Returns: ID of calendar, empty string else

Since: 2.8.5, 14 Oct 2021

◆ getCalendarByTask

string getCalendarByTask	(	string	taskID,
		bool	checkInh = `true`
	)

function

Get calendar assigned to a task. Note: If no calendar is explicitly assigned to a task, the ID of the default calendar will be returned.

Parameters

taskID	ID of task
checkInh	Also check inherited calendars

Returns: ID of calendar

Since: 2.8.5, 14 Oct 2021

◆ getCalendarExceptions

array< object > getCalendarExceptions ( string calendarID )

function

Get list of calendar exceptions (user defined days or holidays).

Parameters

calendarID ID of the calendar

Returns: List with exceptions

Example return:

[
    {
        "Date" : "2022-12-24",
        "WorkingTime" : [["08:00","12:00"]],
        "Comment" : "Christmas Evening"
    },
    {
        "Date" : "2023-01-01",
        "WorkingTime" : [],
        "Comment" : "New Year"
    }
]

Since: 2.9.2, 03 Mar 2022

◆ getCalendarList

array< string > getCalendarList ( )

function

Get available calendars.

Returns: List of calendar IDs

Since: 2.8.5, 14 Oct 2021

◆ getCalendarOptions

object getCalendarOptions ( string calendarID )

function

Get default options of calendar.

Parameters

calendarID ID of the calendar

Returns: Options

Example return:

{
    "DefaultStartTime" : "08:00",
    "DefaultFinishTime" : "17:00",
    "HoursPerDay" : 8,
    "HoursPerWeek" : 40,
    "DaysPerMonth" : 20
}

Since: 2.8.6, 28 Feb 2022

◆ getCalendarWorkingTime

object getCalendarWorkingTime ( string calendarID )

function

Get weekly working time.

Parameters

calendarID ID of the calendar

Returns: Weekly working time

Example return:

{
    "Monday" : [["08:00","12:00"],["13:00","17:00"]],
    "Tuesday" : [["08:00","12:00"],["13:00","17:00"]],
    "Wednesday" : [["08:00","12:00"],["13:00","17:00"]],
    "Thursday" : [["08:00","12:00"],["13:00","17:00"]],
    "Friday" : [["08:00","14:00"]],
    "Saturday" : [],
    "Sunday" : []
}

Since: 2.9.2, 03 Mar 2022

◆ getCheckFilterList

array< object > getCheckFilterList	(	string	checkRunID,
		bool	rightSet = `false`
	)		const

function

Get object filter for check- or clash run.

Parameters

checkRunID	ID of checkRun
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns: List of filter items, empty list if check run with given ID does not exist

Since: 2.9.0, 01 Oct 2021

◆ getCheckItems

array< string > getCheckItems	(	string	checkRunID,
		bool	rightSet = `false`
	)		const

function

Get elements (explicitly set) to be processed by check- or clash run. Note: The IDs of the element/containers to be checked are returned, not the IDs of the check items itself

Parameters

checkRunID	ID of checkRun
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns: List of element ids, empty list if check run with given ID does not exist

Since: 2.9.0, 14 Jan 2022

◆ getCheckOptions

object getCheckOptions ( string checkRunID ) const

function

Get options of a check- or clash run as object.

Parameters

checkRunID ID of checkRun

Returns: Options as object, empty object if check run with given ID does not exist

See also: int setCheckOptions(string checkRunID, object options)

Since: 2.9.0, 01 Oct 2021

◆ getCheckRules

object getCheckRules	(	string	checkRunID,
		string	ruleTypeFilter = `string()`
	)

function

Get check rules of check run.

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be returned. "ScriptRule" "AttributeRule" "UniquePattern"

Returns: {
"ScriptRules" : [
{
"Comment": "",
"ID": "cb41d9fa-ad4f-4eb5-8ba7-a3a983511f47",
"IsActive": true,
"Name": "newRule",
"ResumeOnError": true,
"Code": "// write some code here"
}
],
"AttributeRules" : [
{
"Comment": "If-Check for rooms",
"ID": "06527951-b45c-4f78-9a50-63a405ca132e",
"ParentID": "",
"Pattern": "IfcSpace",
"PropertyTypeKey": "ifcType##xs:string",
"SubType": "conditional"
},
{
"Comment": "Comment3",
"ID": "1389dabd-b76e-4506-8c4a-1cc8f942b391",
"ParentID": "06527951-b45c-4f78-9a50-63a405ca132e",
"Pattern": "A*",
"PropertyTypeKey": "cpName##xs:string",
"Type": "simple"
}
],
"UniquePatterns" : [
{
"CheckInherited": true, // currently unused!
"Comment": "Check uniqueness of element IDs",
"Pattern": "[[cpID##xs:ID]]"
}
],
}

Since: 2.9.3, 24 Mar 2022

◆ getColorSchemaList

array< string > getColorSchemaList ( )

function

Get all color schemes.

Returns: List of names of all color schemes

Since: 1.0.16

◆ getCurrentColorSchema

string getCurrentColorSchema ( )

function

Get current (applied) color scheme.

Returns: Name of current color scheme, empty string if no color scheme is active

Since: 1.0.16

◆ getDefaultCalendar

string getDefaultCalendar ( )

function

Get default calendar.

Returns: ID of calendar

Since: 2.9.3, 08 Mar 2022

◆ getDirectoryEntryList

array< object > getDirectoryEntryList	(	string	dirPath,
		bool	filesOnly = `false`,
		string	orderBy = `"Name"`
	)

function

Return a list of all files and (optionally) subdirectories in the given directory.
The list will NOT include system and hidden files.
A Windows environment variable can be used, but only once in the string (e.g. 'userprofile%/pictures')
Objects in the returned list will contain the following keys:

Name
AbsoluteFilePath
AbsolutePath
SizeInBytes
CreationDateTime
LastModifiedDateTime
IsReadable
IsWritable
IsDirectory

Parameters

dirPath	Full path to the directory to scan
filesOnly	(default false) if this is set to true, subdirectories will not be included in the list
orderBy	Sort the result list either by "Name" (alphabetically, default), "Size" (largest first), or "Time" (most recently modified first)

Returns: Object list with each object representing a file or a subdirectory found in the given directory.
If the source directory was not found or an error occurred, the list will be empty.

Since: 2.0.16, 17 oct 2017, ah

◆ getImportOptions

object getImportOptions ( string modelId )

function

Get import options from model. Only models of domain geometry are considered yet.

Parameters

modelID ID of model

Since: 3.0.1, 14 May 2022

◆ getListOfObjTooltips

array< string > getListOfObjTooltips ( )

function

Get list of tooltip templates.

Since: 1.3.2, 28 mar 2014, jh

◆ getListOfTempValues

array< string > getListOfTempValues ( )

function

Get list of temporary values.

Since: 2.4.1, 11 feb 2019, jh

◆ getLocked

string getLocked ( )

function

Get all locked objects.

Returns: List of IDs of locked objects (separated by ';')

Since: 1.3.6, 25 apr 2014, jh

◆ getMaterial

object getMaterial ( string matId )

function

Get material as object.

Parameters

matId ID of Material

Example return:

{
    "ID": "{16e8fe62-6af7-4b9c-8598-479d310bea1e}-49",
    "Name": "m:0091c926",
    "ambi": [0,0.5686274766921997,0.7882353663444519,0.15294110774993896],
    "diff": [0,0.5686274766921997,0.7882353663444519,0.15294110774993896],
    "shin": 0.5,
    "spec": [1,1,1,0.15294110774993896],
    "tran": 0.847058892250061
}

Since: 2.3.1, 19 dec 2018, ah

◆ getMaterialAsXmlByID

string getMaterialAsXmlByID ( string matId )

function

Get material encoded by XML.

Parameters

matId ID of Material

Returns: Material as XML string

Since: 1.4

◆ getMaterialIDByName

string getMaterialIDByName ( string matName )

function

Get ID of material with given name.

Parameters

matName Name of material

Returns: ID of material. If material does not exist an empty string is returned.

Since: 1.0.20, 14 jan 2013, jh

◆ getMaterialList

array< string > getMaterialList ( )

function

Get list of all available materials.

Returns: Material list as list of material IDs

Since: 1.0.20, 14 jan 2013, jh

◆ getModelByElement

string getModelByElement	(	string	id,
		string	domainFilter = `"all"`
	)

function

Lookup the parent model of the element with the given ID. If the model could not be found, this method returns an empty string.

Parameters

id	Element ID to find the model of
domainFilter	[optional] Domain(s) to look in; by default "all". The lookup may be faster if you narrow the search to specific domains.

Since: 1.9.0, 13.05.2016, jh

◆ getModelListByDomain

array< string > getModelListByDomain ( string domainFilter = "all" )

function

Return a ID-list of all models in a given domain.
NOTE: The model ID is not identical to the ID of the model root nodes in the element hierarchies.

Parameters

domainFilter Given domain(s) (default = 'all'). Different domain names have to be separated by ';'.

See also: getRootNodeListByDomain()

Since: 1.5.0, 28 oct 2015, jh

◆ getModelListByName

array< string > getModelListByName	(	string	name,
		string	domain = `"geometry"`
	)

function

Get a list of IDs of all models with name 'name'.
NOTE: The model ID is not identical to the ID of the model root nodes in the element hierarchies.

name : Name of the model domain : Domain name combination. Default is 'geometry'

See also: DOMAINS

Returns: model IDs as list

See also: string getRootNodeByModel(string modelId)

Since: 1.3.0, 02 jan 2014, jh

◆ getModelMetaData

object getModelMetaData ( string modelId )

function

Get meta data of a given model as JSON object.

Keys of JSON object:

ExportFileName
ExportFileNameUser
ExportCreated
ExportCreatedBy
SourceModelID
SourceApp
SourceFormat
SourceFileName
ProjectFileName
ProjectModelRecID
ProjectDbLink
ProjectUrl
Imported
ImportedBy
ExportFormatName
ExportFormatVersion

Since: 1.5.0, 28 oct 2015, jh

◆ getOOBBCommon

object getOOBBCommon ( var objectIds )

function

Calculate the common OOBB of all given objects. The OOBB is not explicitly set to affected objects and cannot be re-used (see properties cpOOBB... and so on). If an object ID represents a composite or geometric container, all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with 4 arrays specifying the origin and the 3 axis which define the OOBB, e.g.
{
origin: [0.0,0.0,0.0],
axis1: [1.0,0.0,0.0],
axis2: [0.0,1.0,0.0],
axis3: [0.0,0.0,1.0]
}

Since: 2.1.0, 09 May 2017; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getOOBBxyCommon

object getOOBBxyCommon ( var objectIds )

function

Calculate the common OOBBxy of all given objects. The OOBBxy is not explicitly set to affected objects and cannot be re-used (see properties cpOOBBxy... and so on). If an object ID represents a composite or geometric container, all parts of it will be taken into account.

Parameters

objectIds IDs of objects to be affected (array or string, using ';' as separator)

Returns: JSON object with 4 arrays specifying the origin and the 2 axis and a height which define the OOBBxy, e.g.
{
origin: [0.0,0.0],
axis1: [1.0,0.0],
axis2: [0.0,1.0],
height: 1.2
}

Since: 2.1.0, 09 May 2017; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getProjectionAsSvg

string getProjectionAsSvg	(	string	idList,
		object	options = `object()`
	)

function

Get projection of given geometric objects as SVG.

Parameters

idList	Given geometric objects, list of IDs separated by ';'
options	Options as JSON object If an empty JSON object is passed to this method, the size and viewBox is adjusted to the drawn objects.

Returns: Picture as SVG

Example Options:

{
    "width": 600,
    "height": 200,
    "viewBox": "10 10 800 400",
    "resolution": 1

resolution - resolution in DPI, default is 72

Since: 2.0.9, 03 Feb 2017

◆ getPropertyListAsJSON

object getPropertyListAsJSON ( object options )

function

Get list of properties.

This is the same format as the export/import of properties used by the GUI.

Parameters

opt	Options to configure the export.

Example:

var opt = {
    "ExportVisibleObjects":         true,                                           // default: false (means all, visible or not)
    "ActivePropertiesBookmark":     "EXP_STATUS",                                   // if no bookmark is given, all properties are returned,
                                                                                    // if "PropertyTypeList" is used, this setting will be ignored altogether
    "ExportInheritedProperties":    true,                                           // default: true
    "EvaluateProperties":           true,                                           // default: true
    "PropertyTypeList":             [ "cpCount##xs:long", "WebTest##xs:string" ],   // export contained property types. this will override "ActivePropertiesBookmark".
    "Domains":                      [ "geometry" ],                                 // passing a string (semicolon-separated) instead of a "true" list will also work (default: all)
    "ReportNull":                   true                                            // Get also property values as 'null' if property does not exist for a specific object (default: false)
};
var g = desiteAPI.getPropertyListAsJSON(opt);
console.log( JSON.stringify(g) );

Since: 2.2.1, 20 jun 2018, jh

Remarks: , 2.5.3, jh, Parameter 'ReportNull' added

◆ getPropertyScriptBgColor

string getPropertyScriptBgColor	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (background) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptCode

string getPropertyScriptCode	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (value) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptFgColor

string getPropertyScriptFgColor	(	string	domain,
		string	pname,
		string	datatype
	)		const

function

Get code (foreground) of property script.

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptList

object getPropertyScriptList ( ) const

function

Get list of property scripts as JSON object.

Example:

{
    "activities": [
        {
            "DataType": "xs:double",
            "DisplayName": "PROP_B",
            "Name": "PROP_B",
            "Unit": ""
        }
    ],
    "boq": [],
    "building": [],
    "cd": [],
    "documents": [],
    "geometry": [
        {
            "DataType": "xs:string",
            "DisplayName": "PROP_A",
            "Name": "PROP_A",
            "Unit": ""
        }
    ],
    "pc": [],
    "qa": [],
    "res": [],
    "type": []
}

Since: 2.5.0, 06 mar 2019, jh

◆ getPropertyScriptOptions

object getPropertyScriptOptions	(	string	domain,
		string	pname,
		string	datatype
	)

function

options {
    "IsCached": true,
    "IsInherited": true,
    "Unit": "m2",
    "DisplayName": "abc"
}

Since: 2.5.0, 10 mar 2019, jh

◆ getPropertyTypeBookmarkByID

object getPropertyTypeBookmarkByID ( string bookmarkId )

function

Get a property type bookmark as an object.
The 'Type' of the bookmark is 1 for User-defined and 2 for Global.

{
    "ID": "a0373145-30f9-4f81-84cb-65d1186dc7a0",
    "Name": "AREA",
    "Type": 2,
    "PropertyTypes": {
        "activities": [],
        "boq": [],
        "building": [],
        "cd": [],
        "documents": [],
        "geometry": [{
            "name": "cpLateralArea",
            "type": "xs:double"
        },
        {
            "name": "cpTopArea",
            "type": "xs:double"
        }],
        "pc": [],
        "qa": [],
        "res": [],
        "type": []
    }
}

Parameters

bookmarkId ID of the bookmark to look up. If the ID isn't found, an empty object is returned.

Since: 2.2.4, 27 oct 2018, jh

◆ getPropertyTypeBookmarkList

array<var> getPropertyTypeBookmarkList ( )

function

Return list of property types bookmarks.

Example:

[
    {
        "ID": "57d490e2-8900-42cd-b04d-4cbf84f1da8f",
        "Name": "EXPORT_BBOX",
        "Type": 2
    },
    {
        "ID": "8ddf3747-a6d7-428e-afa9-5cc3ecb20ad5",
        "Name": "BKM2",
        "Type": 2
    },
    {
        "ID": "a0373145-30f9-4f81-84cb-65d1186dc7a0",
        "Name": "AREA",
        "Type": 2
    }
]

Since: 2.2.4, 27 oct 2018, jh

◆ getPropertyValues

array<var> getPropertyValues	(	string	propName,
		string	propDatatype,
		int	maxValues = `0`,
		string	domainName = `"all"`,
		bool	getNullValues = `false`
	)

function

Get all available property values for a given property type and domain.

Parameters

propName	Name of property type
propDatatype	Data type of property type
maxValue	Max. number of values which should be returned. If 'maxValue' = 0 all available values will be returned.
domainName	Name of domain (default: "all", combinations are allowed)

Returns: Array with all property values
Empty array if an error occurred or no property values are found in given domain(s)

See also: getPropertyValuesByObjectList()

Since: 1.5.0, 15 dez 2015, sl

◆ getPropertyValuesByObjectList

array<var> getPropertyValuesByObjectList	(	string	propertyName,
		string	propertyDatatype,
		bool	checkInherited,
		var	objectIdList,
		int	maxValues = `0`,
		string	domains = `"all"`,
		bool	getNullValues = `false`
	)

function

Get all available different property values for a given property type, list of objects and domain.

Parameters

propertyName	Name of property type
propertyDatatype	Data type of property type
checkInherited	true = Consider inherited properties, false = Check direct properties only
objectIdList	IDs of objects to check property values of
maxValues	[optional] Max. number of values which should be returned (pass <= 0 for all)
domains	[optional] Domain(s) to check (default: "all")
getNullValues	[optional] Set true if result list shall contain NULL values for objects not having this property.

Returns: Array with all property values
Empty array if an error occurred or no property values are found in given domain(s)

See also: getPropertyValues()

Since: 1.5.0, 15 Dez 2015; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ getRootContainerList

array< string > getRootContainerList ( string modelName )

function

Get a list of IDs of all root containers of all models with name 'modelName'. Works only in domain geometry, because not the model roots but the 'red' root containers (where transformations can be applied) are returned.

Parameters

modelName : Name of the model(s)

Returns: Container IDs as list

Since: 1.0.18, 19 Aug 2012

◆ getRootNodeByModel

string getRootNodeByModel ( string modelId )

function

Get ID of root node of a given model.

Each model has a container as root node in which the whole object hierarchy of a model is stored. This root node is visible in the tree view. The model itself is not visible in the GUI but can be accessed by methods in the API.

Returns: ID of root node, else empty string if 'modelId' is not an ID of any model.

See also: getRootNodeListByDomain()

Since: 1.5.0, 28 oct 2015, jh

◆ getRootNodeListByDomain

array< string > getRootNodeListByDomain ( string domainFilter = "all" )

function

Get list of IDs of root nodes of a given domain filter.

Each model has a container as a root node in which the whole object hierarchy of a model is stored.

Parameters

domainFilter Given domain(s) (default = 'all'). Different domain names have to be separated by ';'.

Since: 1.5.0, 28 oct 2015, jh

See also: getRootNodeByModel()

◆ getRootNodeListSelectionSets

array< string > getRootNodeListSelectionSets ( string domainFilter = "all" )

function

Get root nodes of selection sets. These root nodes are the top level selection sets in a domain project.

Remarks: Currently (2.2.2) domain 'geometry' is supported only.

Since: 2.2.2, 28 aug 2018, jh

◆ getTaskRestrictionsByName

string getTaskRestrictionsByName ( string name )

function

Get first task restriction with given name.

Parameters

name	Name of task restriction

Returns: ID of task restriction, empty string else

Since: 2.8.5, 14 Oct 2021

◆ getTaskRestrictionsList

array< string > getTaskRestrictionsList ( )

function

Get available task restrictions.

Returns: List of task restriction IDs

Since: 2.8.5, 14 Oct 2021

◆ getTempValue

var getTempValue ( string name )

function

Retrieve a temporarily stored property.

Since: 2.4.1, 02 feb 2019, ar

◆ getVisualisationList

object getVisualisationList ( )

function

Get list of visualization configurations as JSON object.

Example:

{
"list":[
        {
            "id":"{9ba5d816-1db8-43c1-8985-100d8c95610b}-6f",
            "name":"MW"
        },
        {
            "id":"{9ba5d816-1db8-43c1-8985-100d8c95610b}-70",
            "name":"StB"
        }
    ]
}

Since: 1.9.0, 16 jul 2016, jh

◆ getWired

string getWired ( )

function

Get all objects which are set to wireframe mode.

Since: 1.9.0, 03 mar 2016, sl

◆ hasContact

int hasContact	(	string	objId1,
		string	objId2,
		object	options = `object()`
	)

function

Check if two objects have contact.

Parameters

objId1	: ID of object 1
objId2	: ID of object 2
options	: Options encoded as JSON. If not specified, the default values of the code snipped (see below) will be chosen.

Returns: 1 if objects have contact using given options
0 - no contact -1 - error, object 'objId1' not found or of wrong type
-2 - error, object 'objId2' not found or of wrong type

var opt = {
    locflag: 7,     // 1 = contact at top, 2 = contact at bottom, 4 = contact at sides (and combinations)
    checkall: true, // if true, all given location combination checks must be true
    tol: 0.001,     // maximum distance tolerance [m]
    angle: 5.0,     // maximum angle deviation between normal vectors of opposite faces [�]
    oppdir: true,   // flag that indicates that normal vectors of contacting faces must point in opposite directions
}
desiteAPI.hasContact( id1, id2, opt );

Since: 1.5.0, 10 Dec 2014

◆ hasElement

bool hasElement ( string id )

function

Check if an object or container with the given ID exists.

Since: 1.3.0, 21 Jan 2014

◆ isContainer

bool isContainer ( string id )

function

Checks if the object with the given ID is a container.

Since: 16 Mar 2015

Parameters

id	: Object ID

Returns: true or false

◆ isIncludedIn

bool isIncludedIn	(	string	objId1,
		string	objId2
	)

function

Check if object with ID 'objId1' is included in object with ID 'objId2'.

Returns: false if there is no inclusion
true if object 1 is included in object 2 or is (geometrically) identical

Since: 1.5.0, 10 Dec 2014

◆ isPointIncludedIn

int isPointIncludedIn	(	double	x,
		double	y,
		double	z,
		string	objId,
		double	tol = `1.e-5`
	)

function

Check if point with given coordinates is included in object with ID 'objId'.

Parameters

x	: x coordinate of point
y	: y coordinate of point
z	: z coordinate of point
objId	: ID of object (mesh or composite)
tol	: numerical tolerance

Returns: 1 - point is inside
0 - point is on border
-1 - point is outside
-2 - object not found

Since: 2.0.13, 05 May 2017

◆ itByFilter

int itByFilter	(	string	propName,
		string	propDatatype,
		string	filterPattern,
		bool	checkInh = `true`,
		string	domain = `"geometry"`
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Get objects which match the filter. If the filter should be applied on all objects, make sure the object iterator is cleared first. Otherwise the filter is applied on an existing object iterator. The filter string is not case sensitive (except for data type xs:ID and xs::IDREF).

Parameters

propName	Property name
propDatatype	Property data type [xs:string, xs:double, xs:long, ... ]
checkInh	Check inherited properties
domain	[ all, geometry, activities, ... ]

Returns: Number of objects in iterator.

See also: itClear();

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use filterByProperty() instead.

◆ itByObjectList

int itByObjectList ( string idList )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Object Iterator is set to objects in idList.

Parameters

idList List of Object IDs as String separated by ';'.

Since: 1.3.0, 15 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use JavaScript to iterate over lists.

◆ itCalcOOBB

void itCalcOOBB ( double eps )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Calculate OptOBB of all contained 3D-objects. The bounding box is only calculated if an object has no OOBB.

Since: 1.4.7, 05 Sep 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use calcOOBB() instead.

◆ itCalcOOBBxy

void itCalcOOBBxy ( double eps )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Calculate OptOBBxy of all contained 3D-objects. The bounding box is only calculated if an object has no OOBBxy.

Since: 1.4.7, 05 Sep 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use calcOOBBxy() instead.

◆ itClear

void itClear ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Clear and delete an existing object iterator.

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.

◆ itColorCode

void itColorCode	(	string	propName,
		string	propDT
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Color code objects in current object iterator. If the current object iterator does not exist all objects are color coded by property 'propName'. An existing object iterator is deleted by calling itClear().

Parameters

propName	: property name
propDT	: property data type

Since: 1.3.0, 15 Nov 2013; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use colorCodeObjects() instead.

◆ itColorCodeNumber

void itColorCodeNumber	(	string	propName,
		string	propDT,
		double	intervalSize
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Color code objects in current object iterator. If the current object iterator is empty or does not exists all objects are color coded by property 'propName'. (An existing object iterator can be deleted by calling itClear() ).

Parameters

propName	: property name
propDT	: property data type
intervalSize	: Size of interval

Since: 1.3.0, 15 Nov 2013; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use colorCodeObjects() instead.

◆ itCount

int itCount ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Count the elements in current object iterator.

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.

◆ itFilterByStatus

int itFilterByStatus	(	string	status,
		bool	enabled = `true`,
		string	domain = `"geometry"`
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Filter objects in iterator list by their status.

Parameters

status	Status as string ['visible', 'selected', 'wired' or 'locked']
enabled	Value of status [true, false]
domain	Domain as string to check ['geometry', 'activities', 'documents, 'building', 'boq', 'qto', 'pc', 'cd', 'qa', 'type', 'res', 'all]', combinations are allowed (separated by ';')

Returns: amount of objects found, 0 if none or undefined, -1 if an error occurred

Since: 1.9.0, 18 May 2016; 2.4.3, 21 May 2019 : changed default domain to 'geometry'; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use filterByStatus() instead.

◆ itGetAvailablePropertyValues

array<var> itGetAvailablePropertyValues	(	string	propName,
		string	propDatatype,
		int	maxValues
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Get property values of objects in current object iterator.

Since: 1.3.1, 24 Mar 2014; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use getPropertyValuesByObjectList() instead.

◆ itGetObjectList

string itGetObjectList ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Get list of IDs of current object iterator.

Since: 1.3.7, 01 May 2014; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use JavaScript to iterate over lists.

◆ itHasNext

bool itHasNext ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Check if iterator is not at end.

Returns: true if the current object iterator has more elements.

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use JavaScript to iterate over lists.

◆ itNext

string itNext ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Get ID of next element in object iterator.

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use JavaScript to iterate over lists.

◆ itSetMaterial

void itSetMaterial ( string matId )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Set material to current objects of iterator.

Since: 1.3.7, 01 May 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use setMaterialToObjects() instead.

◆ itSetupDbCache

void itSetupDbCache	(	string	propName,
		string	propType
	)

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Setup cache for objects in iterator and property 'propname'.

Since: 1.3.6, 28 Apr 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.

◆ itToFront

void itToFront ( )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Set object iterator before first element. Call itNext(9 to get the first element.

Since: 1.3.0, 05 Nov 2013; 2.9.3, 17 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use JavaScript to iterate over lists.

◆ itUpdateOOBB

void itUpdateOOBB ( double eps )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Calculate OptOBB of all contained 3D-objects. The bounding box is always calculated.

Since: 1.4.7, 05 Sep 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use updateOOBB() instead.

◆ itUpdateOOBBxy

void itUpdateOOBBxy ( double eps )

function

Deprecated:: This method will be removed in future versions of DESITE and should not be used for new scripts anymore.

Calculate OptOBB of all contained 3D-objects. The bounding box is always calculated.

Since: 1.4.7, 05 Sep 2014; 2.9.3, 18 Mar 2022 : deprecated

Deprecated:: The current state of the iterator is stored internally, therefore this is not safe to use with the asynchronous API of 3.0 WebForms.
Use updateOOBBxy() instead.

◆ lockObjects

void lockObjects ( string idList )

function

Locks given objects.

Parameters

idList List of IDs of objects to lock (separated by ';')

Since: 1.3.6, 25 apr 2014, jh

◆ mergeObjects

string mergeObjects	(	string	parentContainerId,
		string	idList,
		bool	skipClosed = `false`,
		bool	keepTransparency = `false`,
		bool	keepCommonProperties = `false`,
		bool	replaceParent = `false`
	)

function

Merge objects into a new one. The material of the resulting object is the material of the object with the largest surface area, or, if flag 'keepTransparency' is set, the transparent material.
New: Source Objects must NOT be deleted manually if merging was successful.

Parameters

parentContainerId	: ID of container to which merged object should be added.
idList	: String of IDs of objects to be merged, separated by ';'
skipClosed	: Exclude closed meshes from merging.
keepTransparency	: Keep transparent material if any.
keepCommonProperties	: Keep common properties of merged objects.
replaceParent	: Replace parent container with merged object, if all children could be merged into one.

Returns: ID of merged object, else empty string if no objects were merged. In case of errors:
-1 No parent container with given ID
-2 No objects with given IDs
-3 Could not get model of parent container
-4 Parent could not be replaced. This could be the case if not all children are merged or the given parent is not the direct parent of the merged objects.
-5 No objects merged

Since: 1.5.0, 05 Aug 2015; 2.8.3, 28 Jul 2021, Added 2 parameters according to GUI functionality, method now works like the GUI tool.

◆ moveFile

bool moveFile	(	string	fnFrom,
		string	fnTo
	)

function

Move file 'fnFrom' to file 'fnTo'.

Since: 2.0.18, 31 jan 2018, jh

◆ openFile

bool openFile	(	string	filePath,
		string	encoding = `string()`
	)

function

Open a new file for writing. By default, local 8 bit encoding is used.
To change it, set encoding as optional second parameter.

Parameters

filePath	Name and path of the file to be opened. If no path is given, the current project's path will be used.
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64".

Returns: true if file was opened successfully, else false

Since: 1.3.0, 30 Oct 2013; 1.5.0, 23 Jul 2015 : added encoding parameter; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ propertyScriptClearCache

void propertyScriptClearCache	(	string	domain = `"all"`,
		string	pname = `""`,
		string	datatype = `""`
	)

function

Clear cache of property scripts.
Calling this function without parameters will clear the entire cache.

Since: 2.5.0, 10 Mar 2019

◆ readCsvFile

object readCsvFile	(	string	filePath,
		string	delimiter = `";"`,
		string	encoding = `"Windows-1252"`
	)

function

Read text file in CSV format and return an array of all rows/cells.

Parameters

filePath	Name and path of file (if path is missing, file is expected in the project directory)
delimiter	Single character as delimiter of cells, most common are semicolon or tab.
encoding	File Encoding, by default "Windows-1252". Other options are "UTF-8", "UTF-16", "ISO 8859-1".

Returns: Object with key "csv", containing an array of rows, each with an array of values.

Example:

var lvFile = "tab-separated-text-file.txt";
var csv = desiteAPI.readCsvFile(lvFile, ";", "Windows-1252");
console.log(JSON.stringify(csv, 0, 4));

... returns something like:

{
    "csv": [
        [
            "RECID",
            "konfignr",
            "FORMULA",
            "TEXT"
        ],
        [
            "1132042",
            "1",
            "",
            "Schalung der Innen- und Aussenwand, \nals glatte Schalung aus Schalungsplatten gleicher Groesse.\nBetonflaeche moeglichst absatzfrei."
        ],
        [
            "1129053",
            "1",
            "(2.683)*2",
            "Ortbeton fuer Aufzugsunterfahrt aus Stahlbeton,\nals Normalbeton fuer Aussenbauteile nach DIN 1045-1;-2, C 25/30 \nExpositionsklasse XC2 nach Vorgabe Planer pruefen."
        ]
    ]
}

Since: 2.0.9, 17 Jan 2017; 3.2.3, 11 May 2023 : re-implemented to support multibyte characters, added optional encoding parameter

◆ readFileInChunks

var readFileInChunks	(	string	filePath,
		object	options
	)

function

Read a file and return its contents in chunks via a signal/callback.
Currently, only text files are supported.
The signal fileChunkReceived() will be emitted for each chunk, with its single string parameter containing the data.
After reading is finished, fileChunkReceived() will be emitted one last time with an empty string, indicating EOF (end of file).

Note that for small files (< 64 MB), you can use the more convenient readTextFile().

Parameters

filePath	Name and path of the file to read.
options	Object specifying `'encoding'` and `'bufferSizeInCharacters'`. Please see the example script below.

Small (but complete) usage example:

let fileContent = '';
desiteAPI.fileChunkReceived.connect(function onFileChunkReceived(fileChunk)
{
    if (fileChunk)
    {
        fileContent += fileChunk;
    }
    else
    {
        console.log('empty chunk received -> eof');
        desiteAPI.fileChunkReceived.disconnect(onFileChunkReceived);
    }
});
const options = {
    'encoding': 'UTF-8',                    // also supported: 'UTF-16', 'ISO 8859-1'
    'bufferSizeInCharacters' : 1024*1024    // equals 1 MB for single byte characters (unicode characters can span multiple bytes, though)
};
const retObj = desiteAPI.readFileInChunks('C:/Temp/Test/SomeLargeFile.txt', options);
console.log(JSON.stringify(retObj, 0, 4));
console.log('received data length overall: ' + fileContent.length);

Returns: Object containing error information, number of transferred chunks, and total transferred data. Example:
{
"chunks": 206,
"error": {
"code": 0,
"message": "OK"
},
"totalLength": 215939530
}

Since: 3.2.5, 22 Aug 2023

◆ readImageFile

string readImageFile	(	string	filename,
		string	targetFormat = `""`,
		bool	applyExifRotation = `false`
	)

function

Read image file and return a Base64-encoded string.
By default, this just encodes the raw input data into Base64, but you can optionally add image format conversion and Exif rotation.

Parameters

filename	Name of image file
targetFormat	Optionally specify "png", "jpg", "bmp" or "gif" for target format if you want a conversion. If you want to keep the original source format, this parameter can be omitted (or set to "").
applyExifRotation	If set to true, Exif data (if present in the source file) is evaluated to rotate the image. This will only work if an output format is specified (because otherwise, the raw input data will only be encoded, but not otherwise processed).

Returns: Base64-encoded image; empty string on error

Since: 2.0.16, 2017-10-18, ah; 2.7.2, 2020-12-08, ah : added Exif processing

◆ readTextFile

array< string > readTextFile	(	string	filename,
		bool	ignoreLineBreakesInDoubleQuotes = `false`,
		string	codec = `string()`
	)

function

Read text file and return each line as string.

Parameters

filename	Name of file
ignoreLineBreakesInDoubleQuotes
code	Codec for reading the textfile, one of [ "ISO 8859-1", "UTF-8", "UTF-16" ]

Returns: List of strings containing each line of file

var lineList = desiteAPI.readTextFile( desiteAPI.getProjectDirectory () + '/WebForms/mat.csv' );
for( var i=0; i<lineList.length; i++) {
    console.append( lineList[i] );
}

Since: 1.3.6, 26 apr 2014, jh

Remarks: update 2.0.9, 17. jan 2017, ar handling quoted text

◆ readTextFileAsString

string readTextFileAsString	(	string	filename,
		string	codec = `string()`
	)

function

Read text file and return complete content.

Parameters

filename Name of file

Returns: Complete content in one string

Since: 1.5.0, 23 Aug 2015

◆ recalculateActivityProject

int recalculateActivityProject	(	string	taskID = `string()`,
		bool	visibleOnly = `false`
	)

function

Recalculate projected dates of Activity Project.

Parameters

taskID	ID of root task. If ID is empty, all time schedules will be considered.
visibleOnly	Use visible tasks only

Returns: 1 - Ok
-1 - Error, Could not find task 'taskID'
-2 - Error, dependencies contain cycles
-3 - Error, failed to recalculate START/FINISH of summary tasks

Since: 2.8.6, 24 Feb 2022

◆ removeAllLinkedObjects

int removeAllLinkedObjects ( string id )

function

Remove all linked objects from the element with the given ID.

Parameters

id	ID of element

Returns: 1 success
-1 element with given ID does not exist

Since: 1.0.17, 16 Jun 2012; 3.0.7, 13 Dec 2022 : Added reverse lookup

◆ removeAllRangesFromRegion

int removeAllRangesFromRegion	(	string	regionId,
		string	alignmentId = `string()`
	)

function

Remove all ranges from region.

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: number of ranges removed on success
-1 alignment ID not found
-2 region ID not found

Since: 2.2.1, 20 apr 2018, sl

◆ removeAllRegionsFromAlignment

int removeAllRegionsFromAlignment ( string alignmentId )

function

Remove all regions from an alignment with given ID.

Returns: number of regions removed on success
-1 alignment ID not found

See also: addRegionToAlignment( string alignmentID, object setting )

Since: 2.2.1, 12 apr 2018, sl

◆ removeCalendar

int removeCalendar ( string calendarID )

function

Removes a calendar. Note: The default calendar cannot be removed.

Parameters

calendarID ID of calendar

Returns: 1 Ok
-1 Could not find calendar
-2 Could not remove default calendar

Since: 2.9.2, 03 Mar 2022

◆ removeCalendarException

int removeCalendarException	(	string	calendarID,
		var	date
	)

function

Remove an exception from a calendar.

Parameters

calendarID	ID of the calendar
date	Date as ISO date string or Javascript Date(). When using Javascript Date, consider time differences (GMT).

Returns: 1 Ok
-1 Could not find calendar -2 Exception with given date does not exist

Since: 2.9.2, 03 Mar 2022

◆ removeCalendarFromTask

int removeCalendarFromTask ( string taskID )

function

Remove calendar from task. This will not affect inherited calendars.

Parameters

taskID ID of the task

Returns: 1 Ok
-1 Could not find task

Since: 2.8.5, 14 Oct 2021

◆ removeCheckRule

int removeCheckRule	(	string	checkRunID,
		string	type,
		string	ruleID
	)

function

Remove check rule from check run. In case of attribute rules, the ID is required, else the (unique!) name or property type key. (TODO)

Parameters

checkRunID	ID of (model) check run
ruleTypeFilter	Type of check rule. If empty, all check rules will be removed. "ScriptRule" "AttributeRule" "UniquePattern"
ruleID	ID of check rule (pattern for UniquePattern check)

Returns

1 Ok
-1 Check run with given id not found
-2 Unknown rule type

Since: 2.9.3, 24 Mar 2022

◆ removeFile

bool removeFile ( string filePath )

function

Remove a file

Parameters

filePath Name and path of file to be removed. If no path is given, the current project's path will be used.

Returns: true if file was removed successfully, else false

Since: 1.9.0, 24 jun 2016, mm

Remarks: 2.4.2, 01 mar 2019, ah : changed behavior when no path is given (using project directory instead of application directory)

◆ removeFromSelectionSetGeometry

int removeFromSelectionSetGeometry	(	string	setId,
		string	objectIDs
	)

function

Remove objects from selection set in domain 'geometry'.

Parameters

objectIDs String containing object IDs, separated by ';'.

Returns: 1 Ok
-1 Selection Set not found in domain 'geometry'
-2 Object(s) not found in domain 'geometry'

Since: 2.2.2, 28 aug 2018, jh

◆ removeLinkedObjects

int removeLinkedObjects	(	string	id,
		string	linkedIdList
	)

function

Remove links to a given list of objects from another object.

Returns: 1 success
-1 element with given ID does not exist

Since: 2.0.13, 1 may 2017, jh

◆ removeObjectListFromTooltip

void removeObjectListFromTooltip	(	string	idList,
		string	tooltipname
	)

function

Removes the object list from tooltip.

Parameters

idList	List of objects
tooltipname	Name of the tooltip template

Since: 1.3.2, 28 mar 2014, jh

◆ removePropertyScript

int removePropertyScript	(	string	domain,
		string	pname,
		string	datatype
	)

function

Since: 2.5.0, 10 mar 2019, jh

◆ removePropertyTypeBookmarkByID

int removePropertyTypeBookmarkByID ( string bkmId )

function

Since: 2.2.4, 27 oct 2018, jh

◆ removeRangeFromRegion

int removeRangeFromRegion	(	string	regionId,
		double	fromStation,
		double	toStation,
		string	alignmentId = `string()`
	)

function

Remove a range from a region. Example: Remove [110.0,300.0] from [0.0,350.0] => [0.0,110.0] + [300.0,350.0]

Parameters

regionId	ID of region (will be returned if region is successfully added to an alignment)
fromStation	Lower bound of range
toStation	Upper bound of range
alignmentId	ID of alignment. Optional parameter, if given, method is faster, because not all objects have to be searched

Returns: 1 success
-1 alignment ID not found
-2 region ID not found
-3 invalid range parameters

Since: 2.2.1, 20 apr 2018, sl

◆ removeRuleBasedLinks

int removeRuleBasedLinks ( string domainName )

function

Remove rule based object links for a given domain.

Parameters

domainName Name of domain

Returns: 1 ok
-1 error

Since: 2.6.1, 25 aug 2020, sl

◆ removeSelectionSet

bool removeSelectionSet ( string selsetID )

function

Remove selection set with given ID.

Returns: true if selection set could be removed, else false

Since: 2.5.1, 30 apr 2019, jh

◆ removeTaskRestrictions

int removeTaskRestrictions ( string taskID )

function

Remove task restriction from task.

Parameters

taskID ID of task

Returns: 1 Ok
-1 Could not find task

Since: 2.8.5, 14 Oct 2021

◆ removeVisualisation

int removeVisualisation ( string taskIDList )

function

Remove visualisation configuration from tasks.

Parameters

taskIDList IDs of task, separated by semicolon

Returns: 1 Ok
-1 Could not find any task

Since: 1.9.0, 16 jul 2016, jh

◆ resetDocumentMetaData

void resetDocumentMetaData ( string objId )

function

Forces the MetaDataThreadWorker to reread the meta data of document from URL.

Since: 1.9.0, 18 Jun 2016

◆ resetMaterials

void resetMaterials ( bool updateUI = true )

function

Reset all object materials to materials originally imported with the geometry model file.

Parameters

updateUI If set to true (default), an active color scheme will be unapplied and the 3D view will be repainted

Since: 1.0.20, 14 Jan 2013

◆ runCheck

int runCheck ( string checkRunID )

function

Run check in domain Model Check or Clash Detection.

Parameters

checkRunID ID of checkRun

Returns

1 Ok
-1 Check run with given id not found
-2 Check run is not active

Since: 2.9.0, 20 Aug 2021

◆ setAllPropertyTypesActive

int setAllPropertyTypesActive ( )

function

Set all property types active.

Since: 2.2.4, 27 oct 2018, jh

◆ setAsComposite

int setAsComposite	(	string	id,
		bool	composite
	)

function

Change container with given ID to composite and vice versa.

Parameters

id	ID of container/composite
composite	true: set as composite, false: set as container

Returns: 1 Ok
0 Container is already of desired type
-1 No container with the given ID was found in domain geometry

Since: 2.4.1, 06 Feb 2019

◆ setAsOpening

int setAsOpening	(	string	objId,
		string	openingIDList
	)

function

Set list of objects as opening elements to a given object. Objects in lists which have openings will be skipped.

Parameters

objId	ID of object for which to set openings
openingIDList	Objects to set as openings

Returns: number of objects set as openings
-1 Could not find object/wrong type -2 Empty opening list

Since: 2.0.3, 10 Oct 2016

◆ setBoQBreakdownStructure

int setBoQBreakdownStructure	(	string	boqModelID,
		string	templateStr
	)

function

Set BoQ model structure by template string.

Parameters

boqModelID	ID of BoQ model
templateStr	Text with information about the BoQ structure like "1122PPPPI"

Returns: 1 - Ok
-1 - Could not find model
-2 - Wrong template

Since: 2.8.5, 27 Oct 2021

◆ setCalendar

int setCalendar	(	string	taskID,
		string	calendarID
	)

function

Set a calendar for a task.

Parameters

taskID	ID of the task
calendarID	ID of calendar

Returns: 1 Ok
-1 Could not find task
-2 Could not find calendar

Since: 2.8.5, 14 Oct 2021

◆ setCalendarOptions

int setCalendarOptions	(	string	calendarID,
		object	options
	)

function

Set default options of calendar.

Parameters

calendarID ID of the calendar

Returns: 1 Ok
-1 Could not find calendar
-2 Invalid value passed in options

See also: object getCalendarOptions(string calendarID)

Since: 2.8.6, 28 Feb 2022

◆ setCalendarWorkingTime

int setCalendarWorkingTime	(	string	calendarID,
		object	workingTime
	)

function

Set weekly working time. Existing values will be overwritten, invalid input data will be ignored.

Parameters

calendarID	ID of the calendar
workingTime	Object holding weekly working time.

Returns: 1 Ok
-1 Could not find calendar

See also: object getCalendarWorkingTime(string calendarID);

Since: 2.9.2, 03 Mar 2022

◆ setCheckActive

bool setCheckActive	(	string	checkRunID,
		bool	active
	)

function

Set check active or inactive

Parameters

checkRunID	ID of checkRun
active	true/false

Returns

true - success
false - check run with given id not found

Since: 2.9.0, 20 Aug 2021

◆ setCheckFilterList

int setCheckFilterList	(	string	checkRunID,
		array< object >	filterList,
		bool	rightSet = `false`
	)

function

Set object filter for check- or clash run.

Parameters

checkRunID	ID of checkRun
filterList	Array holding filters, see below
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns

1 Ok
-1 Check run with given id not found

var filter = [
    {
        "propertyTypeKey": "cpName##xs:string",
        "pattern" : "ABC"
    },
    {
        "propertyTypeKey": "cpIsPartOfComposite##xs:boolean",
        "pattern" : false
    }
    ]
}

Since: 2.9.0, 01 Oct 2021

◆ setCheckItems

int setCheckItems	(	string	checkRunID,
		array< string >	elementIDist,
		bool	rightSet = `false`
	)

function

Explicitly set elements to be processed by check- or clash run. This can be done in addition to or instead of an object filter. Setting an empty list will clear the list of checked elements.

Parameters

checkRunID	ID of checkRun
elementIDList	Array holding IDs of elements/containers to be checked
rightSet	In case of clash runs, set filter for left (= false) or right (= true) object set

Returns

1 Ok
-1 Check run with given id not found

See also: int setCheckFilterList(string checkId, array< object > filterList, bool rightSet = false)

Since: 2.9.0, 14 Jan 2022

◆ setCheckOptions

int setCheckOptions	(	string	checkRunID,
		object	options
	)

function

Set options of a check- or clash run.

Parameters

checkRunID	ID of checkRun
options	Object holding options, see below

Returns

1 Ok
-1 Check run with given id not found

To get all available options, use

var id = '...';
var options = desiteAPI.getCheckOptions(id);
JSON.stringify(options);

Model Check:

var options = {
    "createFailed" : true,
    "createWarnings" : true,
    "createPassed" : true,
    "createIgnored" : false,
    "createUndefined" : false,
    "checkObjectsOnly" : true,
    "checkPartsOfComposites" : false
}

Clash Detection:

var options = {
    "ClashOptions": {
        "automaticSize": true,
        "calculateCuttingLines": false,
        "checkClashes": true,
        "checkClearanceSpacesLeft": false,
        "checkClearanceSpacesRight": false,
        "clearanceCreationMode": 0,
        "extrusion": 1,
        "tolerance": -0.01
    },
    "InclusionOptions": {
        "checkInclusionsLeft": false,
        "checkInclusionsRight": false,
        "tolerance": 0.001
    },
    "ContactOptions": {
        "checkBottom": true,
        "checkContacts": false,
        "checkLateral": true,
        "checkOppositeFacesOnly": true,
        "checkTop": true,
        "createContactsAsObjects": false,
        "deviationAngle": 5,
        "tolerance": 0.005
    },
    "EqualObjectOptions": {
        "checkEqualObjects": false,
        "checkEqualSurfaceArea": false,
        "checkEqualVolume": false,
        "eps": 0.01,
        "epsSurfaceArea": 0.01,
        "epsVolume": 0.01
    },
    "DistanceCheckOptions": {
        "checkDistances": false,
        "checkDistancesHorizontalOnly": false,
        "checkMaxDist": false,
        "checkMinDist": true,
        "maxDist": 5,
        "minDist": 1
    },
    "InverseResultOptions": {
        "reportNoResultsLeft": false,
        "reportNoResultsRight": false
    }
}

Since: 2.9.0, 01 Oct 2021

◆ setLinkedObjects

int setLinkedObjects	(	string	elementID,
		string	IDList
	)

function

Create a link (relation) between objects.

Parameters

elementID	ID of element to the linked.object links. The element can be of any domain (like geometry, activity etc).
IDList	List of objects to be linked to. List must be a semicolon-separated string. Currently, only geometric elements are supported as link targets.

Returns: Number of objects linked.
-1 element 'eleID' does not exist

Since: 1.0.17, 16 jun 2012, jh

Remarks: last modified 2.4.2, 21 feb 2019, ah

◆ setMaterialToObjects

int setMaterialToObjects	(	string	matId,
		var	objectIds
	)

function

Set material to given objects (elements of domain 'geometry').

Parameters

matId	ID of material
objectIds	Object IDs to which the material is to be assigned. Can be passed as an array or a string (semicolon-separated). If an ID is an ID of a container, the material is assigned to all contained objects.

Returns: Number of affected objects
-1 Error: Material not found

Since: 1.4; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ setObjectsToWireMode

void setObjectsToWireMode	(	string	ids,
		bool	wired
	)

function

Set objects to wire-frame mode based on condition.

Parameters

ids	String of semicolon-separated object IDs
wired	true = set objects to wire mode false = set objects to normal mode

Since: 1.3.0, 13 nov 2013, jh

◆ setPostProcessingCode

int setPostProcessingCode	(	string	checkRunID,
		string	code
	)

function

Set code for post processing

Parameters

checkRunID	ID of checkRun
code	Javascript code

Returns

1 Ok
-1 Check run with given id not found

Since: 2.9.2, 07 JAN 2022

◆ setProjectLongDescription

int setProjectLongDescription	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setProjectNumber

int setProjectNumber	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setProjectShortDescription

int setProjectShortDescription	(	string	s,
		bool	overwriteExisting = `false`
	)

function

Returns: 1 if successful, else -1

◆ setPropertyListAsJSON

void setPropertyListAsJSON	(	object	propmap,
		object	opt
	)

function

Set list of property values to objects.

Parameters

propmap List of properties as JSON object.

Example: Property List

{
    "domains": {
    "geometry": [{
        "ID": "Project Name::b1179c42-d5e9-4ae6-8e30-331aacaa30ec-00019c33",
        "name": "-",
        "3": "4"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019ce3",
        "name": "-",
        "3": "2"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019d0b",
        "name": "-",
        "3": "2"
    },
    {
        "ID": "Project Name::fa530fc1-55d3-4bbb-9cfb-daae0b400fc8-00019d54",
        "name": "-",
        "3": "4"
    }],
    "documents": [],
    "activities": [],
    "type": [],
    "boq": [],
    "cd": [],
    "pc": [],
    "res": []
    },
    "proptypes": {
        "3": {
        "name": "cp:STATUS",
        "type": "xs:long"
        }
    },
    "meta": {
        "created": "2018-08-03 14:24:04",
        "createdBy": "web@ceapoint.com"
    }
}

Parameters

opt	Options for setting property values. Target: 1: Database 2: Repo 3: Default HandleExisting: 0: overwrite 1: ignore 2: backupWithDate

Example: Options

var opt = {
    "Prefix": "PRE:",
    "Suffix": "@2018-03-04",
    "Target": 2,
    "HandleExisting": 0
};

Since: 2.2

◆ setPropertyScriptBgColor

int setPropertyScriptBgColor	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (background) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptCode

int setPropertyScriptCode	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (value) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptFgColor

int setPropertyScriptFgColor	(	string	domain,
		string	pname,
		string	datatype,
		string	code
	)

function

Set code (foreground) of property script.

Returns: 0 Property not found
1 Ok
-1 Internal Error: Project not set

Since: 2.5.0, 06 mar 2019, jh

◆ setPropertyScriptOptions

int setPropertyScriptOptions	(	string	domain,
		string	pname,
		string	datatype,
		object	opt
	)

function

Returns: -1 : Error
0 : Property not fount, no changes
1 : Options set to property

options {
    "IsCached": true,
    "IsInherited": true,
    "Unit": "m2",
    "DisplayName": "abc"
}

Since: 2.5.0, 10 mar 2019, jh

◆ setPropertyTypeActive

bool setPropertyTypeActive	(	string	pName,
		string	ptype,
		string	domain,
		bool	active
	)

function

Parameters

domain Domain(s) for which to set the active status, e.g. "geometry", "geometry;activities", "all"

Since: 2.6.1, 2020-08-26, ah

◆ setPropertyTypeMetaData

int setPropertyTypeMetaData	(	string	pName,
		string	ptype,
		object	metadata
	)

function

Set meta data of property type such as display name and unit.

Parameters

pName	Name of property type
pType	Data type of property type
metadata	Object containing data to set

Returns: 1 OK
0 undefined
-1 could not find property type

Example:

{
    "DisplayName": "Volume",
    "Unit": "m3",
    "Domain": "geometry",
    "Inheritable": false
}

Since: 2.0.13, 13 May 2017; 2.8.7, 22 Mar 2022 : added option 'Inheritable'

◆ setPropertyValue

int setPropertyValue	(	string	objId,
		string	propName,
		string	propDataType,
		var	value
	)

function

A Property value is set in the Project Repository, DB or model (the lookup sequence for this is the same as when setting a Property via the GUI).
If the Property Type does not exist, it is created in the Project Repository.

To set a global property use objId = GlobalProject.

Parameters

objId	ID of element to set the property value to
propName	Name of the Property
propDataType	Data Type of the Property in XML notation (for example 'xs:string' or 'xs:long')
value	Property Value

Returns: Code:
1 - ok
0 - undefined
-1 - error, object not found
-2 - error, unknown data type
-3 - error, writing was rejected, could be read only or wrong format
-4 - error, illegal value type

See also: setPropertyValueDB(); setPropertyValueRepo(); createPropertyType()

Since: 1.0.17, 28 jun 2012, jh

Remarks: 2.0.6, 18 nov 2016, ah: added data type check; 2.8.5, 22 nov 2021, sl: added var type check

◆ setPropertyValueDB

int setPropertyValueDB	(	string	objIdList,
		string	propName,
		string	propDataType,
		string	propDomain,
		var	value,
		bool	createType = `true`
	)

function

A property is set in the database.

Only datatypes supported by the database are provided. In SQLite DBs, datatypes xs:int and xs:float are mapped to xs:long and xs:double accordingly.

Parameters

objIdList	: List of objects (objIDs separated by ';') which should be affected.
propDomain	: Domains that the object IDs will be looked up in and the property will be created for. Example: "geometry;activities". If empty, "geometry" is used.
createType	: If true (default), a property type will be created if not yet existing; if false, the operation will fail if the property type does not already exist

Returns: Code:
1 - Ok
0 - Undefined
-1 - Error: DB error
-2 - Error: At least one Object in 'objIdList' not found, or list was empty or too large (>5000 elements)
-3 - Error: Property Type locked
-4 - Error: Property Type not found
-5 - Error: Data type unknown or invalid
-6 - Error: Execution blocked

See also: int setPropertyValue()

Since: 1.0.18, 18 aug 2012, jh

Changed in 1.3.0, 30 jan 2014:
Extended signature by parameter 'propDomain'.

Remarks: 1.9.0, 1 apr 2016, ah: added optional parameter 'createType'; 2.0.6, 18 nov 2016, ah: added data type check and return value -5

◆ setTaskMode

int setTaskMode	(	string	taskID,
		int	mode
	)

function

Set Task Mode:

taskmodeManuallyScheduled = 1, taskmodeAutomaticallyScheduled = 2

To get task mode see class CoreAPI.

Returns: 1 - Ok
-1 - Could not find task 'taskID'
-2 - Could not set task mode

Since: 2.1.6, 15 mar 2018, jh

◆ setTaskRestrictions

int setTaskRestrictions	(	string	taskID,
		string	restrictionsID
	)

function

Set task restrictions for a task.

Parameters

taskID	ID of the task
restrictionsID	ID of task restrictions

Returns: 1 Ok
-1 Could not find task
-2 Could not find task restrictions

Since: 2.8.5, 14 Oct 2021

◆ setTempValue

void setTempValue	(	string	name,
		var	value
	)

function

Stores the value for property name as long as the project is not closed or reloaded. Webform reload has no effect on it. No persistence. Information is lost when project is reloaded or DESITE ist closed, even when the project is saved before.

Since: 2.4.1, 02 feb 2019, ar

◆ setTransparency

int setTransparency	(	string	objectIds,
		float	defaultTransparency = `0.95`
	)

function

Objects get a transparent version of their original material. A new material is created if not already assigned to an object. '-T' is appended to the original name.

Parameters

objectIds	String of semicolon-separated IDs of objects to change material of.
defaultTransparency	Transparency value used (default: 0.95). Existing transparency remains unchanged.

Returns: Number of affected objects

Since: 1.3.5, 25 Apr 2014

◆ setVisualisationByID

int setVisualisationByID	(	string	taskIDList,
		string	visID
	)

function

Set visualisation configuration to task.

Parameters

taskIDList	IDs of task, separated by semicolon
visID	ID of visualisation

Returns: 1 Ok
-1 Could not find visualisation with given ID
-2 Could not get any task

Since: 1.9.0, 16 jul 2016, jh

◆ showWireModeSchema

void showWireModeSchema ( string name )

function

Apply wire mode schema with given name.

Parameters

name	Name of wire mode schema which should be applied. 'Reset' resets wire mode (draw all objects solid).

Since: 1.3.0, 30 oct 2013, jh

◆ sortContainerByProperty

int sortContainerByProperty	(	string	containerId,
		string	propName,
		string	propType,
		bool	ascending = `true`,
		int	maxDepth = `0`
	)

function

Sort the elements of a container (any domain) by their property values of a given type.
The sorting is stable.

Parameters

containerId	Container to sort the children of
propName	Property Type name
propType	Property Type datatype
ascending	True by default, set to False for descending sort order
maxDepth	Hierarchy depth (meaning that sub-containers will be sorted, too). A value of 1 would only sort direct children. The default value of 0 will sort all levels.

Returns: 1 OK
-1 Given ID could not be resolved or object is not a container
-2 Invalid Property Type

Since: 2.9.1, 25 Jan 2022

◆ startProjectTransaction

int startProjectTransaction ( string domain = "geometry" )

function

Start transaction on project of given domain. Use this if you want to create many objects at once.

See also: endProjectTransaction()

Returns: number of currently open project transactions

Since: 2.2.1, 02 aug 2018, sl

◆ startTransaction

bool startTransaction ( )

function

Start database transaction.

Since: 1.0.18, 20 aug 2012, jh

◆ swapOrientationOfTriangles

int swapOrientationOfTriangles ( array< object > idList )

function

Swap orientation of triangles.

Parameters

idList List of mesh object IDs.

Returns: Number of objects affected

Since: 2.8.7, 28 Mar 2022

◆ synchronizationFinished

void synchronizationFinished ( bool success )

signal

Emitted when API call synchronizeDocumentContainer() finishes.

See also: synchronizeDocumentContainer()

Since: 2.9.1, 31 Jan 2022

◆ synchronizeDocumentContainer

int synchronizeDocumentContainer	(	string	containerId,
		bool	waitForCompletion = `false`
	)

function

Synchronizes a document container with the assigned local directory or webservice. A URL or RemoteURL must be set for the container which should be synchronized.
By default, the operation will run asynchronously.
The signal synchronizationFinished will be emitted on completion, with one bool parameter indicating success or failure.
The optional parameter 'waitForCompletion' can be used to block further script execution until the synchronization has finished. Note that if you call the function from a WebForms context, you will still need to add the await keyword for this to work.

Parameters

containerId	: ID of container to synchronize
waitForCompletion	: if true, blocks script execution until completed (default is false)

Returns: 1 : OK
0 : undefined
-1 : Element with ID 'containerId' could not be found.
-2 : Element with ID 'containerId' is not a container.
-3 : Container with ID 'containerId' is not properly set up for synching (local or remote URL missing or invalid).
-4 : Container could not be synchronized. Note that this code can only ever be returned when using the 'waitForCompletion' mode, because otherwise, the function will not wait for the actual sync result.

See also: synchronizationFinished();

Example (non-blocking):

desiteAPI.synchronizationFinished.connect(function onSyncFinished(success)
{
    console.log('synchronizeDocumentContainer() has finished ' + (success ? 'successfully' : 'with errors'));
    desiteAPI.synchronizationFinished.disconnect(onSyncFinished);
});
var retCode = desiteAPI.synchronizeDocumentContainer('af563d25-345a-4c11-8947-5017681f623d');
console.log(retCode);

Example (blocking):

var retCode = desiteAPI.synchronizeDocumentContainer('af563d25-345a-4c11-8947-5017681f623d', true);

console.log(retCode);

(Note that you can still connect to the synchronizationFinished signal as in the first example, but it usually won't be very useful.)

Since: 1.5.0, 06 Apr 2016; 2.9.1, 31 Jan 2022 : no longer blocking, emits signal on completion; 3.0.7, 17 Oct 2022 : re-introduced optional parameter for blocking script execution

◆ transformObject

int transformObject	(	string	objId,
		string	transformation
	)

function

Rotate, scale, translate object.

Parameters

objId	ID of object which should be transformed
transformation	scale, translate, rotate encoded as XML

Transformation:

<t>
<scale sx="1.0" sy="1.0" sz="1.0" />
<translate dx="10.0" dy="20.0" dz="30.0" />
<rotate x="2.0" y="1.0" z="2.0" m="0.5 0.5 0.0   0.5 0.0 0.5   0.0 0.0 1.0" />
</t>

Returns: 1 Ok
-1 Could not find object
-2 Not a geometric object

Since: 27 Dec 2013

◆ unlockAllObjects

void unlockAllObjects ( )

function

Unlocks all objects.

Since: 1.3.6, 25 apr 2014, jh

◆ unlockObjects

void unlockObjects ( string idList )

function

Unlocks given objects.

Parameters

idList List of IDs of objects to lock (separated by ';')

Since: 1.3.6, 25 apr 2014, jh

◆ updateBoundingBox3DView

void updateBoundingBox3DView ( )

function

Update overall bounding box of all objects in 3D view.

Since: 1.3.5, 15 apr 2014, jh

◆ updateMaterial

void updateMaterial	(	string	matId,
		string	xmlMat
	)

function

Update material properties such as diffuse, transparency, ...

Parameters

matId	ID of material
matXml	New material properties as XML

See also: createMaterial()

Since: 1.4

◆ updateOOBB

int updateOOBB	(	var	objectIds,
		double	eps = `0.001`
	)

function

Update optimized, orientated bounding box (OOBB) of all given geometric objects. It will always be re-calculated.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ updateOOBBxy

int updateOOBBxy	(	var	objectIds,
		double	eps = `0.001`
	)

function

Update optimized, orientated bounding box in xy-plane (OOBBxy) of all given geometric objects. It will always be re-calculated.

Parameters

objectIds	IDs of objects to be affected (array or string, using ';' as separator)
eps	Threshold for optimization (default: 0.001)

Returns: Number of affected objects

Since: 1.5.0, 13 Jan 2015; 2.1.5, 19 Jan 2019 : extended to handle composites; 2.9.3, 17 Mar 2022 : Input ID list can be either an array or a string of concatenated IDs

◆ updateRuleBasedLinks

int updateRuleBasedLinks	(	string	domainName,
		bool	visibleOnly = `false`
	)

function

Update rule based object links for a given domain.

Parameters

domainName	Name of domain
visibleOnly	If true, only objects links of visible domain items will be updated (default: false)

Returns: 1 ok
-1 error

Since: 2.6.1, 25 aug 2020, sl

◆ updateSmartSets

int updateSmartSets ( array< string > smartSetIDs = array< string >() )

function

Update the Smart Sets with given IDs. If ID list is empty (default), all available Smart Sets will be updated.

Returns: number of updated sets (can be used to check if ID lookups were successful)

Since: 2.7.3, 2021-02-02, ah

◆ validateIfcCompatibiliy

int validateIfcCompatibiliy ( string bsModelID )

function

Checks if a building structure model is valid to be used by geometry export (must fulfill structural conditions).

Parameters

bsModelID ID of building structure model

Returns: 1 - Ok
-1 - Could not find model
-2 - Empty model
-3 - Only model root and groups of IFC types are allowed to be of type 'bsContainer'
-4 - Invalid type (not suited for parent element)
-5 - Maximum three nested elements of same type (bsSite/bsBuilding/bsBuildingStorey/bsSpace) are allowed

Since: 3.0.3, 04 Aug 2022

◆ writeFile

bool writeFile	(	string	filePath,
		string	content,
		string	encoding = `string()`
	)

function

Write a string as a whole to a file.

Parameters

filePath	Name and path of the file to be written. If no path is given, the current project's path will be used.
content	Data to be written to the file
encoding	File encoding, such as "ISO 8859-1", "UTF-8", or "UTF-16". To write binary data, use "base64" and encode the string accordingly.

Returns: true if file was written successfully, else false

Since: 1.3.0, 30 Oct 2013; 2.4.2, 01 Mar 2019 : changed behavior when no path is given (using project directory instead of application directory); 2.9.0, 06 Dec 2021 : added binary writing mode of base64 encoded data

◆ writePropertyValueDB

int writePropertyValueDB	(	string	objIdList,
		string	propName,
		string	propDataType,
		string	propDomain,
		var	value,
		bool	createType = `true`
	)

function

Write property value to database.

Other than setPropertyValueDB(), this method does not check if the objects given by objIdList exist in the project.

Returns: Code:
1 - Ok
0 - Undefined
-1 - Error: DB error
-2 - Error: list is too large (>5000 elements)
-3 - Error: Property Type locked
-4 - Error: Property Type not found
-5 - Error: Data type unknown or invalid
-6 - Error: execution blocked

Since: 2.0.16, 16 sep 2017, jh

◆ writeToFile

bool writeToFile ( string content )

function

Write text to an open file.

Parameters

content Content to be written

Returns: true - success,
false - file is not open

See also: openFile()

Since: 1.3.0, 30 Oct 2013

Functions

Signals

Function Documentation

◆ activateColorSchemaByName

◆ activatePropertyTypeBookmark

◆ addCalendarExceptions

◆ addCheckRule

◆ addObjectListToTooltip

◆ addPropertyScript

◆ addPropertyTypeBookmark

◆ addRangeToRegion

◆ addRegionToAlignment

◆ addToSelectionSetGeometry

◆ appendToFile

◆ calcDistance

◆ calcOOBB

◆ calcOOBBxy

◆ calcPropertyValuesOverTime

◆ calculateDistance

◆ calcWorkInMinutes

◆ checkIfFileExists

◆ checkIntersection

◆ checkOverlapOBB

◆ clearCalendarExceptions

◆ clearCheckResults

◆ clearCheckRules

◆ clearWireMode

◆ closeFile

◆ colorCodeObjects

◆ copyFile

◆ countLocked

◆ countWired

◆ createCalendar

◆ createColorSchema

◆ createColorSchemaFromCurrentMaterials

◆ createContactObject

◆ createDirectory

◆ createMaterial

◆ createModel

◆ createObject

DOMAIN ISSUES

◆ createObjectFromXml

DOMAIN GEOMETRY

DOMAIN ACTIVITIES

DOMAIN BUILDING STRUCTURE

DOMAIN DOCUMENTS

DOMAIN BoQ (Bill of Quantities)

DOMAIN RESOURCES

DOMAIN TYPES

DOMAIN PROCESS COMPONENTS

DOMAIN CLASH DETECTION

DOMAIN MODEL CHECK

DOMAIN ISSUES

◆ createPropertyType

◆ createSelectionSet

◆ createSelectionSets

◆ createTimeSchedule

◆ createWireModeSchema

◆ csvClose

◆ csvHasNextLine

◆ csvNextLine

◆ csvOpen

◆ currentGeoPosition

◆ cutObject

◆ dbAssertTable

◆ dbCheckIn

◆ dbCheckOut

◆ dbClearCache

◆ dbClearCacheAll

◆ dbClose

◆ dbDeleteProperty

◆ dbEndQueryExec

◆ dbGetFilepath

◆ dbGetImmediateUpdate

◆ dbIsLocalCopy

◆ dbOpen

◆ dbQueryExec

◆ dbQueryLastError

◆ dbQueryNext

◆ dbQueryRecordset