Frequently Asked Questions

Table of Contents

• Where can I find script samples to start with?
• How can I retrieve an element from the current document?
• How can I insert elements in my document?
• How can I import files?
• How can I export files?
• How can I handle errors in my code?
• How to create new objects?
• How to copy objects?

Where can I find script samples to start with?

Visit the Cyclone 3DR GitHub page

You can visit Cyclone 3DR Scripts to have access to a list of scripts samples.
For example, have a look at MyFirstScript, it will help you learn how to get started on scripting with Cyclone 3DR.

Basic sample: Inspection Cloud vs Mesh

Additionally, here is a small sample that creates a mesh from a selected point cloud (using SPoly.Direct3DMesh) and then performs an inspection analysis (using SPoly.Compare)

// Utility function to output an error and stop the script execution
function ErrorMessage(iMessage)
{
    throw new Error(iMessage);
}
 
// Main function
 
// Get the selected point cloud
var selCloudTbl = SCloud.FromSel();
if(selCloudTbl.length == 0)
{
    ErrorMessage("Please select a point cloud.");
}
 
var iCloud = selCloudTbl[0];
 
// Create a mesh from the selected point cloud
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)
{
    var 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("The mesh is created.\n");
}
else
{
    ErrorMessage("An error occurred. No mesh was created.");
}
 
// Perform inspection
var maxDist = 1; // max distance of the inspection
var iInspection = newMesh.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 mesh");
    newMesh.SetVisibility(false); // to hide the original mesh
    print("Inspection succeeded.\n");
}

How can I retrieve an element from the current document?

There are 4 ways to request elements from the current document:

• All: To retrieve all elements from a given type.
• FromSel: To retrieve the current selected elements.
• FromName: To query elements from their names.
• FromClick: To query an element clicked by the user.

These functions are static and accessible in SComp or any derived SComp class (such as SPoly.All for example). The usage will depend on the type of object you want to query.

All()

To find all elements of a given type.
The function will return a table with all elements of a defined type depending on a visibility criterion.

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.

var tblPlane = SPlane.FromSel(); // Will contains all selected planes. Can be empty if no plane has been selected.
if(tblPlane.length > 0)
    var firstPlane = tblPlane[0]; // Get the first 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 pause the script and wait until you click a point in the document.
If the clicked point corresponds to an element of the defined type, the element is returned, else an error is returned.
A specific case exists for SPoint function 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)
{
    print("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 insert elements in my document?

By default, imported objects are not inserted inside the current document.
Use SComp.AddToDoc() to insert an element in the current document.

How can I import files?

FromFile()

This static function is available for most classes. For example, SPoly.FromFile, SCloud.FromFile, etc.
The function will return elements loaded, it means that the elements are not inserted 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("The import of the object " + mesh.GetName() + " succeeded.");
 
    // Add the mesh in the document
    mesh.AddToDoc();
} 
else
{
    throw new Error("The import of the object failed.");
}

OpenDoc()

To open a .3dr file.
All the objects are directly inserted in the current document.

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.");
}

SSurveyingFormat.ImportProject()

This function will import dxf, LandXml and E57 files.
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 files?

Save()

This static function is available for most of classes. For example, SPoly.Save, SMultiline.Save and SCloud.Save
Elements are not added in the current document.

// Export a mesh 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("The export of the object " + mesh.GetName() + " succeeded.");
} 
else
{
    throw new Error("The export of the object " + mesh.GetName() + " failed.");
}

SSurveyingFormat.ExportProject()

This function will export all input elements in a DXF file.

How can I handle errors in my code?

Instead of using throw new Error, you can create your function, based on the example below, 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 to create new objects?

In script, you can create new object through the use of static methods nammed New.
Depending on the object, several constructors may exist with different input parameters.

// Create a new empty point
var myPoint = SPoint.New(); 
 
// Create a point with specific coordinates
var myPoint2 = SPoint.New(1, 2, 3); 

Once your class object has been created, you can call any available method from it, like for instance:

var myPoint = SPoint.New(0, 1, 2);
// Insert the point in the current document
myPoint.AddToDoc(); 

How to copy objects?

To copy a script object, you cannot use the = operator, indeed the = operator merely copies the object reference and does not create a copy.
To copy a SObject instance, you must use the New( objectToCopy ) constructor available for most classes.

For instance:

var myPoint = SPoint.New();
print(myPoint.GetX()); // output: 0
 
// Copying only a reference to myPoint
var samePoint = myPoint;
samePoint.SetX(32);
print(myPoint.GetX()); // output: 32. Error!
print(samePoint.GetX()); // output: 32
 
// Copying myPoint geometry
var pointCopy = SPoint.New( myPoint ); // Valid syntax
pointCopy.SetX(64);
print(myPoint.GetX()); // output: 32
print(pointCopy.GetX()); // output: 64