S3D.structure


The S3D.structure namespace is where the model is described. From here, you can make changes to the model.

info

S3D.UI.update may need to be called to reflect changes for any of the following functions.


S3D.structure.get#

Description: Get the current model object.

Operation Type: Synchronous

Params: options?

Sample:

getModel.js
let model = S3D.structure.get({ api_format: true });

SkyCiv recommend using the api_format:true option to work with the API model format. Without this option you will recieve the model in legacy format.

Now there is a reference to the model, you can make changes to any properties. To see the available properties, open a model in S3D and type the above command into the console. Then enter model. and you will see the available properties in the suggestions.

note

members are referred to as elements in this object.


S3D.structure.set#

Description: Set the active model.

Operation Type: Asynchronous

Params: S3D.structure.set(modelData, fileName?, isUndo?, callback?)

KeyTypeDescription
modelDataObjectThis can be obtained via S3D.structure.get().
fileNamestringThe new file name of the model.
isUndobooleanWhether the operation should be undoable.
callbackfunctionThis function will be executed once the model has been set.

Sample:

setModel.js
const clone = (obj) => JSON.parse(JSON.stringify(obj));
const currentModel = S3D.structure.get();
let newModel = clone(currentModel);
// Make changes to new model
// Set new model
S3D.structure.set(newModel);

The model data should be the same format as the object received when using S3D.structure.get(). The simplest way to do this is to clone this object, make changes to the clone, then pass the new model into the set method.


S3D.structure.clear#

Description: Clears the current model object.

Operation Type: Synchronous

Params: null

Sample:

clearModel.js
S3D.structure.clear();

S3D.structure.nodes#

The S3D.structure.nodes namespace provides ways to interact with model nodes.

S3D.stucture.nodes.add#

Description: Add a node to the model.

Operation Type: Synchronous

Params: S3D.structure.nodes.add(Object)

Object properties:

KeyTypeDescription
IDintegerOptional: The ID of the new node. Defaults to next available ID if omitted.
xfloatThe x coordinate of the node.
yfloatThe y coordinate of the node.
zfloatThe z coordinate of the node.

Sample:

addNode.js
S3D.structure.nodes.add({
ID: 12,
x: 1.5,
y: 3,
z: 0,
});

S3D.stucture.nodes.remove#

Description: Remove nodes from the model.

Operation Type: Synchronous

Params: S3D.structure.nodes.remove(Array)

Array values:

A list of node IDs to be removed.

Sample:

removeNode.js
S3D.structure.nodes.remove([12, 24]);

S3D.stucture.nodes.getVector#

Description: Gets the unit vector between two nodes.

Operation Type: Synchronous

Params: S3D.structure.nodes.getVector(startNode, endNode)

KeyTypeDescription
startNodeintegerThe node ID of the start node.
endNodeintegerThe node ID of the end node.

Sample:

getVector.js
S3D.structure.nodes.getVector(12, 24);

S3D.structure.members#

The S3D.structure.members namespace provides ways to interact with model members.

S3D.stucture.members.add#

Description: Add a member to the model.

Operation Type: Synchronous

Params: S3D.structure.members.add(Object)

Object properties:

KeyTypeDescription
IDintegerOptional: The ID of the new member. Defaults to next available ID if omitted.
nodeAintegerNode A of the member.
nodeBintegerNode B of the member.
section_idintegerOptional: The section ID to apply to the member.
rotationfloatOptional: The rotation of the member in degrees.
typestringOptional: The type of member. Accepts: normal, normal_continuous, rigid, tension, compression, cable, joist
fixityAstringOptional: The fixity code for end A.
fixityBstringOptional: The fixity code for end B.
offsetsAstringOptional: The offset applied to the member (x,y,z).
offsetsBstringOptional: The offset applied to the member (x,y,z).

Sample:

addMember.js
S3D.structure.members.add({
ID: 3,
nodeA: 1,
nodeB: 5,
section_id: 1,
rotation: 90,
type: 'normal_continuous',
fixityA: 'FFFFFF',
fixityB: 'FFFFFF',
offsetsA: '0,0,0',
offsetsB: '0,0,0',
});

S3D.stucture.members.remove#

Description: Remove members from the model.

Operation Type: Synchronous

Params: S3D.structure.members.remove(Array)

Array values:

A list of member IDs to be removed.

Sample:

removeMember.js
S3D.structure.members.remove([12, 24]);

S3D.stucture.members.getLength#

Description: Gets the length of a member.

Operation Type: Synchronous

Params: S3D.structure.members.getLength(memberId)

KeyTypeDescription
memberIdintegerThe ID of the member whose length to calculate.

Sample:

getLength.js
S3D.structure.members.getLength(12);

S3D.stucture.members.intersect#

Description: Split a member in various ways.

Operation Type: Synchronous

Params: S3D.stucture.members.intersect(Object)

Object Properties:

KeyTypeAcceptsDescription
typstringintersectingNodes, splitStr, intersectingMembers, equalPartsHow to split the member.
memberNointegerA normal number.Member ID to split.
splitStrstringA percentage or distance expressed as a string."50%" for midway along the member or a float for a distance from nodeA.
split_nodes_onlybooleantrue, falseOnly split on nodes.
incintegerA normal number.Number of increments to split the member into.

Sample:

S3D.structure.members.intersect({
// splits members by intersecting nodes
typ: 'intersectingNodes',
memberNo: 14,
});
S3D.structure.members.intersect({
// splits members by % or distance
typ: 'splitStr',
memberNo: 14,
splitStr: '50%', //or 1.34 for 1.34m from nodeA
split_nodes_only: false,
});
S3D.structure.members.intersect({
// locates any intersecting members and splits them at their intersection
typ: 'intersectingMembers',
memberNo: 14,
split_nodes_only: false,
});
S3D.structure.members.intersect({
typ: 'equalParts',
memberNo: 14,
inc: 4, // how many parts to split
split_nodes_only: true,
});

S3D.stucture.members.getIntersectingNodes#

Description: Get all the nodes connected to, or intersecting each member.

Operation Type: Synchronous

Params: S3D.stucture.members.getIntersectingNodes(Object)

Object Properties:

KeyTypeAcceptsDescription
member_idinteger(Optional)Include a specific member ID

Sample:

S3D.structure.members.getIntersectingNodes({
member_id: 14,
});
S3D.structure.members.getIntersectingNodes(); //returns all members and their intersecting nodes

S3D.structure.plates#

The S3D.structure.plates namespace provides methods to interact with model plates.

S3D.stucture.plate.add#

Description: Add a plate to the model.

Operation Type: Synchronous

Params: S3D.stucture.plate.add(Object)

Object properties:

KeyTypeDescription
IDintegerOptional: The ID of the new plate. Defaults to next available ID if omitted.
nodesarray , stringThe nodes that make up the plate.
thicknessfloatThe plate thickness.
material_idintegerThe material id to use with the plate.
offsetfloatOptional: The offset of the plate.
rotZfloatOptional: The rotation of the plate.
statestringOptional: stess or strain.
isMeshedbooleanIf the plate is meshed.

Sample:

addPlate.js
S3D.structure.plates.add({
nodes: [62, 60, 59, 61],
thickness: 12,
material_id: 1,
rotZ: 0,
offset: 0,
state: 'stress',
isMeshed: true,
});

S3D.structure.supports#

S3D.structure.supports.add#

Description: Add a restraint to the model.

Operation Type: Synchronous

Params: S3D.stucture.supports(Object)

Object Properties:

KeyTypeDescription
node_idintegerThe node ID to add the restraint.
fixitystringA restraint code.

Sample:

addSupport.js
S3D.structure.supports.add({
node_id: 1,
fixity: 'FFFRRR',
});

S3D.structure.loads#

The S3D.structure.loads namespace provides methods to add and remove loads to the structure.

S3D.structure.loads.point_loads#

Description: Add point loads to a node or member.

Operation Type: Synchronous

Params: S3D.stucture.loads.point_loads(Object)

Object Properties:

KeyTypeAcceptsDescription
typestringn, mHow to split the member.
nodeintegerA normal number.Node ID to apply the force.
memberintegerA normal number.Member ID to apply the force.
positionfloatA normal number.Percentage along the member. E.g. 50 for 50%.
x_magfloatAny number.Force magnitude in the X direction.
y_magfloatAny number.Force magnitude in the Y direction.
z_magfloatAny number.Force magnitude in the Z direction.
load_groupstringAny string.The name of the load group to assign the load to.

Sample:

addPointLoad.js
// Add a point load to a node
S3D.structure.loads.point_loads.add({
type: 'n',
node: 2,
x_mag: 0,
y_mag: 0.3,
z_mag: 2,
load_group: 'PL1',
});
// Add a point load to a member
S3D.structure.loads.point_loads.add({
type: 'm',
member: 1,
position: 40, // Percentage along member.
x_mag: 3.4,
y_mag: 0,
z_mag: 0,
load_group: 'PL2',
});

S3D.structure.loads.distributed_loads#

Description: Add distributed loads to a member.

Operation Type: Synchronous

Params: S3D.stucture.loads.distributed_loads(Object)

Object Properties:

KeyTypeAcceptsDescription
memberintegerA normal number.Member ID to apply the force.
x_mag_AfloatAny number.Start force magnitude in the X direction.
y_mag_AfloatAny number.Start force magnitude in the Y direction.
z_mag_AfloatAny number.Start force magnitude in the Z direction.
x_mag_BfloatAny number.End force magnitude in the X direction.
y_mag_BfloatAny number.End force magnitude in the Y direction.
z_mag_BfloatAny number.End force magnitude in the Z direction.
position_AfloatA normal number.Percentage along the member to start the load. E.g. 10 for 10%.
position_BfloatA normal number.Percentage along the member to finish the load. E.g. 90 for 90%.
load_groupstringAny string.The name of the load group to assign the load to.
axesglobalglobal, localWhether the load properties are relative to the global or local axis.

Sample:

addDistributedLoad.js
S3D.structure.loads.distributed_loads.add({
member: 4,
x_mag_A: 2,
y_mag_A: 0,
z_mag_A: 0,
x_mag_B: 5,
y_mag_B: 0,
z_mag_B: 0,
position_A: 0,
position_B: 100,
load_group: 'DistLoad1',
axes: 'global',
});

S3D.structure.loads.area_loads#

Description: Add area loads to the model.

Operation Type: Synchronous

Params: S3D.stucture.loads.area_loads(Object)

Object Properties:

KeyTypeAcceptsDescription
typestringone_way, two_way, column_wind_load, open_structureHow the area load should be applied.
nodesstring-Comma seperated node IDs to define the area load.
membersinteger-
magfloat-The magnitude of the load, in the units of pressure.
directionstringX, Y, ZThe direction of the load in the global axes.
elevationsfloat-Relevant only if "type": "column_wind_load".
The elevations between which the corresponding pressure magnitudes (see next row in this table) should be applied.
This property should have 1 more value than the corresponding pressure magnitudes property.
magsstring-Relevant only if "type": "column_wind_load".
The magnitudes of pressures which should be applied between the corresponding elevations (see above row in this table).
This property should have 1 less value than the corresponding elevations property.
column_directionstring-Relevant only if "type": "one_way" or "type": "column_wind_load".
The span direction of the applied area load.
The values must be the IDs of 2 nodes which are in the nodes property.
loaded_members_axisstringall, majorRelevant only if "type": "open_structure".
Whether to apply the open structure load to all members attaching to the nodes (indicated by all), or to only those members which lie along the global XYZ axes (indicated by major).
LGstring-The load group to which this area load belongs.

Sample:

addDistributedLoad.js
S3D.structure.loads.area_loads.add({
type: 'two_way',
nodes: '1,2,3,4',
members: 0,
mag: -2.5,
direction: 'Y',
elevations: 0,
mags: '0',
column_direction: '',
loaded_members_axis: 'all',
LG: 'Area Load 1',
});

S3D.structure.loads.sw#

S3D.structure.loads.sw.set#

Description: Add self-weight cases to the model.

Operation Type: Synchronous

Access: set

Params: S3D.structure.loads.sw.set(Object)

Object Properties:

KeyTypeDescription
Loadcase IDObjectThe property represents the loadcase index and should be greater than 0. The value is an object of key-values x,y,z. Each direction should have a value of type float which represents a gravity multiplier.

Sample:

This sample adds a gravity case of -1×g in the negative Z direction.

setGravity.js
S3D.structure.loads.sw.set({
1: {
x: 0,
y: 0,
z: -1,
},
});

S3D.structure.loads.lc#

S3D.structure.loads.lc.add#

Description: Create load combinations.

Operation Type: Synchronous

Access: set

Params: S3D.structure.loads.sw.set(Object)

Object Properties:

KeyTypeDescription
namestringThe name of the load combination.
Load Group NameFactorProvide the load group name as the property. The value should be the multiplier for the load group as a float.

Sample:

This sample adds a gravity case of -1×g in the negative Z direction.

addLoadcase.js
S3D.structure.loads.lc.add({
name: `G_floor + 1.5Q_floor`,
SW1: 1,
FloorLiveLoad: 1.5,
});

S3D.stucture.COG#

Description: Get the center of gravity for a group of structural elements.

Operation Type: Synchronous

Access: get

Params: S3D.structure.COG(nodes, elements, plates, sections, materials)

KeyTypeDescription
nodesObjectThe nodes object from the structural model.
elementsObjectThe elements object from the structural model.
platesObjectThe plates object from the structural model.
sectionsObjectThe sections object from the structural model.
materialsObjectThe materials object from the structural model.

Sample:

getCog.js
const structure = S3D.structure.get();
const nodes = structure.nodes;
const elements = structure.elements;
const plates = structure.plates;
const sections = structure.sections;
const materials = structure.materials;
S3D.structure.COG(nodes, elements, plates, sections, materials);
info

To exclude certain elements, for example plates, pass an empty object {}.

S3D.structure.COG(nodes, elements, {}, sections, materials);

S3D.structure.repair#

The S3D.structure.repair function provides access to the S3D repair tool.

Description: Repair the model.

Operation Type: Synchronous

Params: S3D.structure.repair(Object)

Object properties:

KeyTypeAllowableDescription
tasks[string]unused_nodes, large_structure, merge_nodes, zero_members, continuous_to_normal_members, intersect_members, default_section, force_plate_meshAn array of strings indicating which tasks to complete.
force_repairbooleantrue, falseIf true, repair will run without prompting the user.

Sample:

repairModel.js
const checks = [
'unused_nodes',
'large_structure',
'merge_nodes',
'zero_members',
'continuous_to_normal_members',
'intersect_members',
'default_section',
'force_plate_mesh',
];
S3D.structure.repair({
tasks: checks,
force_repair: true,
});

S3D.structure.share#

The S3D.structure.share function allows sharing of your model.

Description: Share the current model.

Operation Type: Synchronous

Params: S3D.structure.repair(callback)

Sample:

share.js
S3D.structure.share(function (res) {
console.log(res);
});
/* Output
{
project_id: 'hgcfpRRr...',
structural_viewer_link: 'https://platform.skyciv.com/structural-viewer?project_id=hgcfpRRr...',
project_viewer_link: 'https://platform.skyciv.com/model-viewer?project_id=hgcfpRRr...',
};
*/