Frequent questions

Where can I find script samples to start with?

Please visit our Github at https://github.com/Cyclone3DR/Scripts to access to a list of scripts samples. Especially have a look on MyFirstScript, it will help you learn how to get started on scripting with Cyclone 3DR.

How can I access to an element in the current document?

To do it, you have 4 methods available in the script.
These functions can be used on each SComp.
All these methods are static, so they will be used with the objects type you want to find.

All()
To find all elements of a defined type.
The function will return a table with all elements of a defined type depending on a visibility criteria.

var allNotVisiblePolys = SPoly.All(0); // will contains all non visible SPolys in the document. var allVisibleClouds = SCloud.All(1); // will contains all visible SClouds in the document. var allPoints = SPoint.All(2); // will contains all SPoints, visible or not, in the document.
FromSel()
To find all selected elements of a defined type.
Selection can be used before running script or during script execution.
The function will return a table with all selected elements of a defined type. And more, selection can be done during SDialog execution.

//Select planes in the scene and start your script var tblPlane = SPlane.FromSel(); // will contains all selected planes. Can be empty if no plane has been selected. var firstPlane = tblPlane[0]; or var firstPlane = SPlane.FromSel()[0]; // If you are only interested by the first selected plane
FromName()
To find an element of a defined type by its name.
The function will return a table with all elements of a defined type with the given name.

var tblPoint = SPoint.FromName("Center"); // will return all the SPoints named "Center". var tblCloud = SCloud.FromName("Wall"); // will return all the SClouds named "Wall".
FromClick()
Unlike previous function, this command will stop the script.
The function will wait until you click a point in the document. If the clicked point correspond to an element of the defined type, the element is returned, else an error is returned.
An exception is done for the SPoint, which can return the clicked entity or a projection of the clicked point.
```
var result = SCloud.FromClick(); // Click to select a point cloud in the scene
if (result.ErrorCode != 0)
{
    throw new Error("An error occurred. No cloud has been selected."); // print an error message if no success
}
else
{ 
    print("Point Cloud " + result.Cloud.GetName() + " has been selected for meshing."); // print the name of the cloud
}
```

How can I import files?

FromFile()
This static function is available for SPoly, SMultiline and SCloud.
It is similar to File/Import Cloud(s), File/Import Mesh(es), File/Import Polyline(s).
The function will return element(s) loaded. The elements are not loaded in the current document.

var load = SPoly.FromFile( 'C:/Poly.stl' ); // will load file Poly.stl in the script but not in the current document.
if (load.ErrorCode == 0)
{
    var mesh = load.PolyTbl[0];
    print("\nThe import of the object " + mesh.GetName() + " succeeded.");
} 
else
{
    throw new Error("The import of the object failed.");
}

OpenDoc()
To open a .3dr file. Set all the objects in the current document.
By default, current document is not cleared, but you can define it.
After you open a .3dr file, you can access an element by using FromClick(), or FromName() function.

var res = OpenDoc( 'C:/MyFile.3dr' );
if (res.ErrorCode == 0)
{
    print("\nThe file has been correctly loaded.");
} 
else
{
    throw new Error("An error occurred during the loading.");
}

var clickResult = SPoly.FromClick();

if(clickResult.ErrorCode != 0)
    throw new error("An error occurred. No mesh has been selected.");

var mesh = clickResult.Poly; // Get a Poly loaded in your current document earlier

ImportProject()
Only available in the SurveyingFormat plugin.
This function will import dxf, LandXml and E57 files.
The function will return all the readable objects. Elements are not added in the current document.

var res = SSurveyingFormat.ImportProject( 'C:/ProjectFile.e57', 0 );
if(res.ErrorCode != 0)
    throw new Error("An error occurred during the import.");

// Add all your point clouds in your document
for(i = 0; i < res.CloudTbl.length; i++) 
    res.CloudTbl[i].AddToDoc();

How can I export an element?

Save()
To save an element in a file.
This static function is available for SPoly, SMultiline, SCloud and SPoint.
The function will return an error code to indicate if it was a success or not.

// Export to OBJ 
var mesh = SPoly.FromSel()[0];
var filePath = "C://" + mesh.GetName()+".obj"; 
var matrix = SMatrix.FromActiveCS();
var result = mesh.Save(filePath,false,matrix); 
if (result.ErrorCode == 0)
{
    print("\nThe export of the object " + mesh.GetName() + " succeeded.");
} 
else
{
    throw new Error("The export of the object " + mesh.GetName() + " failed.");
}

How can I handle errors in my code?

Instead of using throw new Error, you can create your function, inspired of the one after, to show a dialog with your error message.

function ErrorMessage(iMessage)
{
    var myDlg = SDialog.New("Error Message");
    myDlg.AddLine(iMessage, false, Array(), 1);
    myDlg.Execute();

    throw new Error(iMessage);
}

var result = SCloud.FromClick(); // Click to select a point cloud in the scene 
if (result.ErrorCode != 0) 
{
    ErrorMessage("An error occured. No cloud has been selected."); // print an error message if no success 
}
else
{
    print("Point Cloud " + result.Cloud.GetName() + " has been selected for meshing."); // print the name of the cloud
}

How can I call algorithm function?

These static functions are used exactly like the Save function.
Here we can see some examples with Direct3DMesh and Compare.

function ErrorMessage(iMessage)
{
    var myDlg = SDialog.New("Error Message");
    myDlg.AddLine(iMessage, false, Array(), 1);
    myDlg.Execute();

    throw new Error(iMessage);
}

// Direct3DMesh
// Definition of the 3D MESH basic parameters: used by the function
var iCloud = SCloud.FromSel()[0];
var newMesh = SPoly.New(); // creation of new object 
var deviationError = 0; // deviation error. 0 means that deviation error is not used
var miniAverageDist = 0.05; // average distance between points in current distance unit
var meshHoles = SPoly.ALL_CLOSED; // all the detected holes are closed in this case
var sizeHoles = miniAverageDist*3; // size of the holes in current distance unit

var iResult = SPoly.Direct3DMesh(iCloud,deviationError,miniAverageDist,meshHoles,sizeHoles); // basic 3D MESH function

if (iResult.ErrorCode ==0)
{
    newMesh = iResult.Poly;
    iCloud.SetVisibility(false); // input cloud is hidden
    newMesh.AddToDoc(); // necessary step to add the mesh from the script into the project (displayed by default)
    print("\nThe mesh is created.");
}
else
{
    ErrorMessage("An error occurred. No mesh was created.");
}

// Compare
var iMesh = SPoly.FromSel()[0];
var iCloud = SCloud.FromSel()[0];
var maxDist = 1; // max distance of the inspection
var iInspection = iMesh.Compare(iCloud,maxDist,1,true,0,90,true); // Mesh with inspection

if (iInspection.ErrorCode == 1)
{
    ErrorMessage("An error occurred during the inspection.");
}
else
{
    var inspectedMesh = iInspection.Poly;
    inspectedMesh.AddToDoc();
    inspectedMesh.SetName("Inspected "+ iMesh.GetName());
    iMesh.SetVisibility(false); // to hide the original mesh
    print("\nInspection succeeded.");
}

How can I add labels in my document?

Use AddToDoc() on your created labels to add them in your document.

var myPlane = SPlane.FromSel()[0];

// Create a label with the surface and normal direction of the plane
var planeSurface = myPlane.GetSurface(); // surface of the best plane
var planeNormal = myPlane.GetNormal(); // normal of the best plane
var planePoint = myPlane.GetCenter(); // center of the best plane

var iLabel = SLabel.New(4,1); // creation of a label
iLabel.SetColType([SLabel.Measure]); // column that contains measures
iLabel.SetLineType([SLabel.Surface, SLabel.NormalX,SLabel.NormalY,SLabel.NormalZ,]); // lines are surface and directions of the normal vector
iLabel.SetCol(0,[planeSurface,planeNormal.GetX(),planeNormal.GetY(),planeNormal.GetZ()]);
iLabel.AttachToPoint(planePoint); // label is attached to the center of the best plane
iLabel.AddToDoc();