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?)

Key	Type	Description
`modelData`	`Object`	This can be obtained via `S3D.structure.get()`.
`fileName`	`string`	The new file name of the model.
`isUndo`	`boolean`	Whether the operation should be undoable.
`callback`	`function`	This 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:

Key	Type	Description
`ID`	`integer`	Optional: The ID of the new node. Defaults to next available ID if omitted.
`x`	`float`	The x coordinate of the node.
`y`	`float`	The y coordinate of the node.
`z`	`float`	The 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)

Key	Type	Description
`startNode`	`integer`	The node ID of the start node.
`endNode`	`integer`	The 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:

Key	Type	Description
`ID`	`integer`	Optional: The ID of the new member. Defaults to next available ID if omitted.
`nodeA`	`integer`	Node A of the member.
`nodeB`	`integer`	Node B of the member.
`section_id`	`integer`	Optional: The section ID to apply to the member.
`rotation`	`float`	Optional: The rotation of the member in degrees.
`type`	`string`	Optional: The type of member. Accepts: `normal`, `normal_continuous`, `rigid`, `tension`, `compression`, `cable`, `joist`
`fixityA`	`string`	Optional: The fixity code for end A.
`fixityB`	`string`	Optional: The fixity code for end B.
`offsetsA`	`string`	Optional: The offset applied to the member (x,y,z).
`offsetsB`	`string`	Optional: 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)

Key	Type	Description
`memberId`	`integer`	The 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:

Key	Type	Accepts	Description
`typ`	`string`	`intersectingNodes`, `splitStr`, `intersectingMembers`, `equalParts`	How to split the member.
`memberNo`	`integer`	A normal number.	Member ID to split.
`splitStr`	`string`	A percentage or distance expressed as a string.	`"50%"` for midway along the member or a float for a distance from nodeA.
`split_nodes_only`	`boolean`	`true`, `false`	Only split on nodes.
`inc`	`integer`	A 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:

Key	Type	Accepts	Description
`member_id`	`integer`	(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:

Key	Type	Description
`ID`	`integer`	Optional: The ID of the new plate. Defaults to next available ID if omitted.
`nodes`	`array` , `string`	The nodes that make up the plate.
`thickness`	`float`	The plate thickness.
`material_id`	`integer`	The material id to use with the plate.
`offset`	`float`	Optional: The offset of the plate.
`rotZ`	`float`	Optional: The rotation of the plate.
`state`	`string`	Optional: `stess` or `strain`.
`isMeshed`	`boolean`	If 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:

Key	Type	Description
`node_id`	`integer`	The node ID to add the restraint.
`fixity`	`string`	A 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:

Key	Type	Accepts	Description
`type`	`string`	`n`, `m`	How to split the member.
`node`	`integer`	A normal number.	Node ID to apply the force.
`member`	`integer`	A normal number.	Member ID to apply the force.
`position`	`float`	A normal number.	Percentage along the member. E.g. `50` for 50%.
`x_mag`	`float`	Any number.	Force magnitude in the X direction.
`y_mag`	`float`	Any number.	Force magnitude in the Y direction.
`z_mag`	`float`	Any number.	Force magnitude in the Z direction.
`load_group`	`string`	Any 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:

Key	Type	Accepts	Description
`member`	`integer`	A normal number.	Member ID to apply the force.
`x_mag_A`	`float`	Any number.	Start force magnitude in the X direction.
`y_mag_A`	`float`	Any number.	Start force magnitude in the Y direction.
`z_mag_A`	`float`	Any number.	Start force magnitude in the Z direction.
`x_mag_B`	`float`	Any number.	End force magnitude in the X direction.
`y_mag_B`	`float`	Any number.	End force magnitude in the Y direction.
`z_mag_B`	`float`	Any number.	End force magnitude in the Z direction.
`position_A`	`float`	A normal number.	Percentage along the member to start the load. E.g. `10` for 10%.
`position_B`	`float`	A normal number.	Percentage along the member to finish the load. E.g. `90` for 90%.
`load_group`	`string`	Any string.	The name of the load group to assign the load to.
`axes`	`global`	`global`, `local`	Whether 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:

Key	Type	Accepts	Description
`type`	`string`	`one_way`, `two_way`, `column_wind_load`, `open_structure`	How the area load should be applied.
`nodes`	`string`	-	Comma seperated node IDs to define the area load.
`members`	`integer`	-
`mag`	`float`	-	The magnitude of the load, in the units of pressure.
`direction`	`string`	`X`, `Y`, `Z`	The direction of the load in the global axes.
`elevations`	`float`	-	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.
`mags`	`string`	-	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_direction`	`string`	-	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_axis`	`string`	`all`, `major`	Relevant 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).
`LG`	`string`	-	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:

Key	Type	Description
Loadcase ID	`Object`	The 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:

Key	Type	Description
`name`	`string`	The name of the load combination.
Load Group Name	`Factor`	Provide 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)

Key	Type	Description
`nodes`	`Object`	The nodes object from the structural model.
`elements`	`Object`	The elements object from the structural model.
`plates`	`Object`	The plates object from the structural model.
`sections`	`Object`	The sections object from the structural model.
`materials`	`Object`	The 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:

Key	Type	Allowable	Description
`tasks`	`[string]`	`unused_nodes`, `large_structure`, `merge_nodes`, `zero_members`, `continuous_to_normal_members`, `intersect_members`, `default_section`, `force_plate_mesh`	An array of strings indicating which tasks to complete.
`force_repair`	`boolean`	`true`, `false`	If 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...',
};
*/

info

S3D.structure.get#

note

S3D.structure.set#

S3D.structure.clear#

S3D.structure.nodes#

S3D.stucture.nodes.add#

S3D.stucture.nodes.remove#

S3D.stucture.nodes.getVector#

S3D.structure.members#

S3D.stucture.members.add#

S3D.stucture.members.remove#

S3D.stucture.members.getLength#

S3D.stucture.members.intersect#

S3D.stucture.members.getIntersectingNodes#

S3D.structure.plates#

S3D.stucture.plate.add#

S3D.structure.supports#

S3D.structure.supports.add#

S3D.structure.loads#

S3D.structure.loads.point_loads#

S3D.structure.loads.distributed_loads#

S3D.structure.loads.area_loads#

S3D.structure.loads.sw#

S3D.structure.loads.sw.set#

S3D.structure.loads.lc#

S3D.structure.loads.lc.add#

S3D.stucture.COG#

info

S3D.structure.repair#

S3D.structure.share#

`S3D.structure.get`#

`S3D.structure.set`#

`S3D.structure.clear`#

`S3D.structure.nodes`#

`S3D.stucture.nodes.add`#

`S3D.stucture.nodes.remove`#

`S3D.stucture.nodes.getVector`#

`S3D.structure.members`#

`S3D.stucture.members.add`#

`S3D.stucture.members.remove`#

`S3D.stucture.members.getLength`#

`S3D.stucture.members.intersect`#

`S3D.stucture.members.getIntersectingNodes`#

`S3D.structure.plates`#

`S3D.stucture.plate.add`#

`S3D.structure.supports`#

`S3D.structure.supports.add`#

`S3D.structure.loads`#

`S3D.structure.loads.point_loads`#

`S3D.structure.loads.distributed_loads`#

`S3D.structure.loads.area_loads`#

`S3D.structure.loads.sw`#

`S3D.structure.loads.sw.set`#

`S3D.structure.loads.lc`#

`S3D.structure.loads.lc.add`#

`S3D.stucture.COG`#

`S3D.structure.repair`#

`S3D.structure.share`#