The s3d_model object


note

For modelling functions, see model.

Throughout the rest of the documentation, the SkyCiv Structural 3D model may be referred to as the s3d_model object. The s3d_model object is a JSON object that describes the structural model. This data contains all the necessary information to model and analyze the structure. We also have a S3D Model Schema in JSON format to help you map the input.

A convenient way to examine what an existing model looks like as JSON, is to open the file in SkyCiv Structural 3D and click:

File โ†’ Export โ†’ SkyCiv File (JSON for API)

This will download the JSON object of the current model, and may help as a guide to building the s3d_model object. Similarly, a JSON file can be tested directly through the UI by clicking:

File โ†’ Import โ†’ SkyCiv File (JSON for API)

tip

By exporting from the S3D platform, the sections object may look complicated. If you would like to keep the s3d_model more compact, it can be substituted to use the load_section property as seen in sections. You can get all available sections by inspecting the Section Builder Platform or via the S3D.SB.getLibraryTree function.

Try s3d_model

s3d_model#

The s3d_model property is comprised of the following properties:



settings#

KeyTypeAcceptsDescriptionDefault
unitsstring or objectimperial, metric, {...}Provide imperial or metric for default units. See Units to set specific units.Varies per design standard.
precisionstringfixed, exponentialNumber format style.fixed
precision_valuesintegerBetween 1 and 15Number of precision.
evaluation_pointsintegerBetween 3 and 50number of evaluation points for each member. Higher evaluation points will (slightly) increase the accuracy but will increase the time taken to solve.
vertical_axisstringY, ZThe axis which defines the vertical direction of the model.Y
solver_timeoutintegerAny number. in secondsHow long until the solver timeouts and returns "Solve Failed" if the model is not solving for an unknown reason.
accurate_buckling_shapebooleantrue, falseIf enabled when a buckling analysis is performed then the accuracy of the displayed buckled shape will be improved however it will take longer to solve. The buckling factors and values should be very similar to when this option is not enabled.
buckling_johnsonbooleantrue, falseUse the parabolic or J.B. Johnson formula which is a more conservative approach for buckling of intermediate-length columns. The Johnson formula will be applied for critical stresses above half the yield strength.
non_linear_tolerancestringE.g. 1 = 1%Non-Linear Analysis will continue to solve until this tolerance (relative error percentage) is met. A smaller number takes longer for convergence.
non_linear_theorystringsmall, finitesmall
auto_stabilize_modelbooleantrue, falseEnable this if your model has stability issues, especially if the non-linear analysis will not converge. The solver will attempt to automatically stabilize nodes that are not restrained. It's is recommended to leave this disabled unless you are having issues with stability.
member_offsets_axisstringglobal, localSpecifies if member offsets should be relative to the local or global axis system.local
dynamic_modesintegerAny positive integerThe maximum number of modes that the dynamic frequency analysis will return.5
dynamic_frequency_area_reduction_factorfloatAny positive numberThis factor reduces the area of these members to reduce their axial stiffness since they'll usually be used for bracing.1

units#

KeyTypeAcceptsDescription
lengthstringft in mm mLength for defining elements.
section_lengthstringin, mmLength for defining section properties.
material_strengthstringksi, psi, mpa
densitystringlb/ft3, kg/m3
forcestringkip, lb, kn, n, kg
momentstringkip-ft, lb-ft, lb-in, kn-m, n-m, kg-m
pressurestringksi, ksf, psi, psf, kpa, mpa, pa
massstringkip, lb, kg
translationstringmm, in
stressstringksi, psi, mpa, kpa
important

Unit systems can not be mixed between Imperial/Metric.

Sample code for the settings object#

simple-settings.json
{
"settings": {
"units": "imperial", // Will load default imperial units
"vertical_axis": "Z" // Only change one setting
}
}

Default units#

Using a value of imperial or metric for the units property will set the units to the following.

default-imperial-units.json
{
"settings": {
"units": {
"length": "ft",
"section_length": "in",
"material_strength": "ksi",
"density": "lb/ft3",
"force": "kip",
"moment": "kip-ft",
"pressure": "ksf",
"mass": "kip",
"translation": "in",
"stress": "ksi"
}
}
}


nodes#

Each node is defined by an object. The node key is the ID of that node in the structure.

The x, y, and z properties represent the coordinates in the global axes, respectively.

KeyTypeDescription
xfloatThe x coordinate of the node
yfloatThe y coordinate of the node
zfloatThe z coordinate of the node
note

The coordinates must be entered in the units defined by the length property of the units object.

Sample code for the nodes object#

The following JSON snippet describes 2 nodes, with IDs 1 & 2.

Node 1 lies at the origin, Node 2 lies a distance of 1 (in the relevant units) from the origin, along the x-axis.

nodes-sample.json
{
"nodes": {
"1": {
"x": 0,
"y": 0,
"z": 0
},
"2": {
"x": 1,
"y": 0,
"z": 0
}
}
}


members#

Similar to nodes, each member is defined by an object, and the object key is the ID of that member.

Members are defined by two nodes, the section, rotation angle, and fixity of the member at each node. Other optional properties may be specified.

KeyTypeAcceptsDescriptionDefault
typestring
(optional)
normal, normal_continuous, cableIf cable is specified:
  • rotation_angle defaults to 0
  • fixity_A and fixity_B default to FFFRRR
  • All offset properties default to 0.
normal
cable_lengthfloat
(optional)
Any non-negative numberRelevant only if type = cable, and even in this case, this is optional.
A cable length can be specified to account for sagging or pre-tension.
Do not set this property if you do not need to account for sagging or pre-tension.
node_AintegerAny non-negative numberThe start node, identified by the node ID
node_BintegerAny non-negative numberThe end node, identified by the node ID
section_idintegerAny non-negative numberThe ID of the section to be applied to the member.
Must be positive.
sections are defined in their own object.
rotation_anglefloat optionalNumber between -180 and 180Rotation of the member about its own axis, in degrees. This is measured from S3D's default local axes position based on node_A and node_B. If local_axis_y or local_axis_z is provided then it will be measured from these local axes rather than S3D's default local axes.
This value is ignored for type = cable.
fixity_AstringHow the member is connected about node A, represented by a restraint code.
If "type" property = "cable", this value is ignored.
fixity_BstringHow the member is connected about node B, represented by a restraint code.
If "type" property = "cable", this value is ignored.
stiffness_A_RystringNumber > 0 or a percentage between 0% and 100%.Spring Stiffness for rotation about the member's local y-axis at node A. Enter the actual stiffness or a percentage like 80%.
stiffness_A_RzstringNumber > 0 or a percentage between 0% and 100%.Spring Stiffness for rotation about the member's local z-axis at node A. Enter the actual stiffness or a percentage like 80%.
stiffness_B_RystringNumber > 0 or a percentage between 0% and 100%.Spring Stiffness for rotation about the member's local y-axis at node B. Enter the actual stiffness or a percentage like 80%.
stiffness_B_RzstringNumber > 0 or a percentage between 0% and 100%.Spring Stiffness for rotation about the member's local z-axis at node B. Enter the actual stiffness or a percentage like 80%.
offset_AxfloatAny number.The local x distance that the member is offset from its centroid at node A.
If "type" property = "cable", this value is ignored.
0
offset_AyfloatAny number.The local y distance that the member is offset from its centroid at node A.
If "type" property = "cable", this value is ignored.
0
offset_AzfloatAny number.The local z distance that the member is offset from its centroid at node A.
If "type" property = "cable", this value is ignored.
0
offset_BxfloatAny number.The local x distance that the member is offset from its centroid at node B.
If "type" property = "cable", this value is ignored.
0
offset_ByfloatAny number.The local y distance that the member is offset from its centroid at node B.
If "type" property = "cable", this value is ignored.
0
offset_BzfloatAny number.The local z distance that the member is offset from its centroid at node B.
If "type" property = "cable", this value is ignored.
0
local_axis_y[float] optional-Specify a global axis vector [X, Y, Z] for the direction of the local y-axis of the member (typically the minor axis). If this is provided, there is no need to provide local_axis_z. If this vector is not orthogonal to the local x-axis then it will be used along with the local x-axis to calculate the local z-axis. If rotation_angle property is non-zero then it will be added to this. This value is ignored for type = cable.
local_axis_z[float] optional-Specify a global axis vector [X, Y, Z] for the direction of the local z-axis of the member (typically the major axis). If this is provided, there is no need to provide local_axis_y. If this vector is not orthogonal to the local x-axis then it will be used along with the local x-axis to calculate the local y-axis. If rotation_angle property is non-zero then it will be added to this. This value is ignored for type = cable.
note

The offsets must be entered in the units defined by the section_length property of the units object.

Sample code for the members object#

The following JSON snippet describes 2 members.

The first member spans from node 1 to node 4, is not rotated about its own axis, is fully fixed, and is offset in the local x-direction by the same amount at both ends. It uses the first section in the list of sections.

The second member is a cable, spanning from node 2 to 5, and uses the second section in the list of sections.

members-sample.json
{
"members": {
"1": {
"node_A": 1,
"node_B": 4,
"section_id": 1,
"rotation_angle": 0,
"fixity_A": "FFFFFF",
"fixity_B": "FFFFFF",
"offset_Ax": "101.6",
"offset_Ay": "0",
"offset_Az": "0",
"offset_Bx": "101.6",
"offset_By": "0",
"offset_Bz": "0"
},
"2": {
"type": "cable",
"node_A": 2,
"node_B": 5,
"section_id": 2
}
}
}


plates#

Plates are 2D structural elements. Each plate is defined by an object which is contained within the plates object. Each plate inside the plates object should be identified by a unique positive integer.

KeyTypeAcceptsDescriptionDefault
nodes[integer]An array of normal integers.The nodes which make up the plate. A minimum of 3 nodes are required to specify a plate.
thicknessfloatA normal numberThe thickness of the plate. The units of thickness are defined by the section_length property of the units object
material_idintegerA normal numberThe material of the plate. Identified by the material ID defined in the materials object.
rotZfloatRotation of the plate about its local Z (normal) axis in degrees.0.0
typestringautoThis will consider shear deformation when the plate thickness is sufficient.auto
offsetfloatOffset of the plate along its local z-axis
diaphragmstringno, rigidIf the plate is a diaphragm.no
membrane_thicknessfloatโ‰ฅ0The membrane thickness to be used. Takes the value of thickness if null.thickness
shear_thicknessfloatโ‰ฅ0The shear thickness to be used. Takes the value of thickness if null.thickness
bending_thicknessfloatโ‰ฅ0The bending thickness to be used. Takes the value of thickness if null.thickness
statestringstress, strainDenotes whether the plate is in a state of plane stress or plane strain.stress
holes[integer]An array of node IDsUsed to define holes in the plate.null
isMeshedbooleantrue, falseIndicates whether the plate is already meshed. If the plate is meshed, then the elements making up the mesh must be specified in the meshed_plates object, and have their parent_plate property set to the ID of this plate.false
note

Each plate defined is also known as a parent_plate as it can mesh into smaller plate elements.

Sample code for the plates object#

plates-sample.json
{
"plates": {
"1": {
"nodes": [1, 2, 4, 3],
"thickness": 50,
"material_id": 1,
"rotZ": 0,
"type": "auto",
"offset": 65.6,
"diaphragm": "no",
"membrane_thickness": 48,
"shear_thickness": 45,
"bending_thickness": 45,
"state": "stress",
"isMeshed": true
},
"2": {
"nodes": [3, 4, 6, 6],
"thickness": 50,
"material_id": 1,
"rotZ": 0,
"type": "auto",
"offset": 65.6,
"state": "stress",
"isMeshed": true
}
}
}


meshed_plates#

Meshed Plates are the 2D elements (triangular or quadrilateral) that make up a plate. Every meshed plate has a parent_plate property defining where it originated. Individual plates are defined by an object in the meshed_plates object. The object key is the plate ID, and must be a unique positive integer value.

KeyTypeDescriptionDefault
node_AintegerThe first node of the meshed plate.
node_BintegerThe second node of the meshed plate.
node_CintegerThe third node of the meshed plate.
node_DintegerThe fourth node of the meshed plate.
Set this to null (None for a Python dictionary) if the meshed plate is triangular.
parent_plateintegerThe ID of the plate which this meshed plate originated from.
Must refer to a plate in the plates object.
rotZfloatRotation of this plate about the plate's local z-axis, in degrees.0.0

Sample code for the meshed_plates object#

The following JSON snippet shows a triangular plate that originates from plate 1 as defined by the parent_plate property:

meshed_plates-sample.json
{
"meshed_plates": {
"1": {
"node_A": 39,
"node_B": 51,
"node_C": 65,
"node_D": null,
"parent_plate": 1,
"rotZ": 166.43391070308
}
}
}


sections#

Individual sections are stored in the sections object. Each section is defined by an object. The object key is the ID of the section, and should be a unique positive integer.

Sections can be specified in the following ways:

  1. By providing the load_section property which contains the path to the section as seen in the SkyCiv Section Builder.
  2. By providing the load_custom property which contains the name of a custom shape defined in SkyCiv Section Builder.
  3. Using the output from the SkyCiv Section Builder, which includes geometric coordinates of the cross-section shape. Sections specified using this format support design, stress calculation, and can be rendered in S3D.
  4. As custom input: The geometric coordinates of the cross-section shape are not considered, and only the essential section properties (Iz, Iy, J etc.) must be specified. Sections specified using this format do not support design, stress calculation, or rendering in S3D, making them appropriate for analysis, but not design.
note

The section builder format contains all the properties of the custom input format plus the version & aux properties.

Using the load_section property.

KeyTypeDescription
load_section[string]Provided as an array of 4 strings (see example below). It is the path of the section in the section library, obtained by inspection from within SkyCiv Section Builder or by attaining the library tree via S3D.SB.getLibraryTree
material_idintegerThe ID of the material that is assigned to the shape of the section. materials are defined in their own object.

Sample code for the sections object using the load_section property

sections-sample.json
{
"sections": {
"1": {
"load_section": ["American", "AISC", "W shapes", "W14x22"],
"material_id": 1
}
}
}


materials#

Individual materials are stored in the materials object. Each material is defined by an object. The object key is the ID of the material, and should be a unique positive integer.

KeyTypeAcceptsDescription
namestringAny stringThe name of the material
densityfloatA normal numberThe density of the material.
elasticity_modulusfloatA normal numberThe Modulus of Elasticity (or Young's Modulus) of the material.
poissons_ratiofloatA normal numberThe Poisson's Ratio for the material.
yield_strengthfloatA normal numberThe Yield strength of the material.
ultimate_strengthfloatA normal numberThe Ultimate strength the material.
classstringsteel, aluminium, masonry, concrete, wood, otherThe type of material.

Sample code for the materials object#

The following JSON snippet adds several materials, to the model using the metric system.

materials-sample.json
{
"materials": {
"1": {
"name": "Structural Steel",
"density": 7850,
"elasticity_modulus": 200000,
"poissons_ratio": 0.27,
"yield_strength": 260,
"ultimate_strength": 410,
"class": "steel"
},
"2": {
"name": "Aluminium",
"density": 2700,
"elasticity_modulus": 69000,
"poissons_ratio": 0.32,
"yield_strength": 100,
"ultimate_strength": 150,
"class": "aluminium"
},
"3": {
"name": "Carbon Fibre Reinforced Plastic",
"density": 3500,
"elasticity_modulus": 150000,
"poissons_ratio": 0.2,
"yield_strength": null,
"ultimate_strength": 2705,
"class": "other"
},
"4": {
"name": "Concrete",
"density": 2500,
"elasticity_modulus": 17000,
"poissons_ratio": 0.2,
"yield_strength": null,
"ultimate_strength": 3.5,
"class": "concrete"
},
"5": {
"name": "Concrete High Strength",
"density": 2500,
"elasticity_modulus": 30000,
"poissons_ratio": 0.2,
"yield_strength": null,
"ultimate_strength": 5,
"class": "concrete"
},
"6": {
"name": "Oakwood",
"density": 900,
"elasticity_modulus": 11000,
"poissons_ratio": 0.3,
"yield_strength": 4.5,
"ultimate_strength": 5,
"class": "wood"
},
"7": {
"name": "Glass",
"density": 2500,
"elasticity_modulus": 70000,
"poissons_ratio": 0.24,
"yield_strength": null,
"ultimate_strength": 33,
"class": "other"
}
}
}


supports#

Individual supports are stored in the supports object. Each support is defined by an object. The object key is the ID of the support, and should be a unique positive integer.

KeyTypeDescription
nodeintegerThe ID of the node at which the support is located.
restraint_codestringA 6 character restraint code.
txfloatSpring stiffness for translation in the x-axis. Applies only if the restraint code character for translation in x = S.
tyfloatSpring stiffness for translation in the y-axis. Applies only if the restraint code character for translation in y = S.
tzfloatSpring stiffness for translation in the z-axis. Applies only if the restraint code character for translation in z= S.
rxfloatSpring stiffness for rotation about the x-axis. Applies only if the restraint code character for rotation about x = S.
ryfloatSpring stiffness for rotation about the y-axis. Applies only if the restraint code character for rotation about y = S.
rzfloatSpring stiffness for rotation about the z-axis. Applies only if the restraint code character for rotation about z = S.

Sample code for the supports object#

The following JSON snippet creates two supports: the first is fully fixed, the second is released in all rotational degrees of freedom, and has a spring in the translational y-direction.

supports-sample.json
{
"supports": {
"1": {
// Add a fully fixed support
"node": 1,
"restraint_code": "FFFFFF",
"tx": 0,
"ty": 0,
"tz": 0,
"rx": 0,
"ry": 0,
"rz": 0
},
"2": {
// Add a support with a spring for translation in y, and released rotationally
"node": 2,
"restraint_code": "FSFRRR",
"tx": 0,
"ty": 0.1,
"tz": 0,
"rx": 0,
"ry": 0,
"rz": 0
}
}
}


settlements#

Settlement loads may be applied using the settlements object. Each settlement is defined by an object with properties within the settlements object. Individual settlements should be identified by a unique positive integer.

KeyTypeDescription
nodeintegerThe node ID of the node to which the settlement is applied.
txfloatSettlement displacement in the global x-axis.
tyfloatSettlement displacement in the global y-axis.
tzfloatSettlement displacement in the global z-axis.
rxfloatSettlement rotation about the global x-axis.
ryfloatSettlement rotation about the global y-axis.
rzfloatSettlement rotation about the global z-axis.

Sample code for the settlements object#

The following JSON snippet shows a settlement load applied to node 1, in the global translational x & y-directions, and about the global y-axis:

settlements-sample.json
{
"settlements": {
"1": {
"node": 1,
"tx": 5,
"ty": -0.1,
"tz": 0,
"rx": 0,
"ry": -0.174533,
"rz": 0
}
}
}


point_loads#

Individual point loads are stored in the point_loads object. Each point load is defined by an object. The object key is the ID of the point load and should be a unique positive integer. Point loads may be applied to nodes, or at a position along a member, determined by the type property.

KeyTypeAcceptsDescription
typestringn, mThe type of object to which the load is applied. node, member
nodeintegerA normal numberInclude the property node only when applying the point load to a node. The value should be the node ID.
memberintegerA normal numberInclude the property member only when applying the point load to a member. The value should be the member ID.
positionfloat0-100Include the property position only when applying the point load to a member. The value is the position of the point load along the member, from the start node of the member. It is defined as a percentage and therefore has an acceptable value of 0 to 100.
x_magfloatAny number.The magnitude of the point load along the x-axis.
y_magfloatAny number.The magnitude of the point load along the y-axis.
z_magfloatAny number.The magnitude of the point load along the z-axis.
load_groupstringA string.The load group to which the point load will be grouped.

Sample code for the point_loads object#

The following JSON snippet will add two point loads to the S3D model, a nodal point load, and a member point load midway along the member:

point_loads-sample.json
{
"point_loads": {
"1": {
"type": "n",
"node": 2,
"x_mag": 0,
"y_mag": -1,
"z_mag": 0,
"load_group": "DL"
},
"2": {
"type": "m",
"member": 1,
"position": 50,
"x_mag": 0,
"y_mag": -2,
"z_mag": 0,
"load_group": "LL"
}
}
}


moments#

Individual moments (moment loads) are stored in the moments object. Each moment is defined by an object. The object key is the ID of the moment and should be a unique positive integer. Moments may be applied to nodes, or at a position along a member, determined by the property type.

KeyTypeAcceptsDescription
typestringn, mThe type of object to which the load is applied. node, member
nodeintegerA normal numberInclude the property node only when applying the moment to a node. The value should be the node ID.
memberintegerA normal numberInclude the property member only when applying the moment to a member. The value should be the member ID.
positionfloat0-100Include the property position only when applying the moment to a member. The value is the position of the moment along the member, from the start node of the member. It is defined as a percentage and therefore has an acceptable value of 0 to 100.
x_magfloatAny number.The magnitude of the moment about the x-axis. Positive = counter-clockwise, negative = clockwise.
y_magfloatAny number.The magnitude of the moment about the y-axis. Positive = counter-clockwise, negative = clockwise.
z_magfloatAny number.The magnitude of the moment about the z-axis. Positive = counter-clockwise, negative = clockwise.
load_groupstringA string.The load group to which the moment will be grouped.

Sample code for the moments object#

The following JSON snippet will add two moments to the S3D model, a nodal moment, and a point moment midway along a member:

moments-sample.json
{
"moments": {
"1": {
"type": "n",
"node": 2,
"x_mag": 0,
"y_mag": -1,
"z_mag": 0,
"load_group": "DL"
},
"2": {
"type": "m",
"member": 1,
"position": 50,
"x_mag": 0,
"y_mag": -2,
"z_mag": 0,
"load_group": "LL"
}
}
}


distributed_loads#

Individual distributed loads are stored in the distributed_loads object. Each distributed load is defined by an object. The object key is the ID of the distributed load, and should be a unique positive integer.

KeyTypeAcceptsDescription
memberintegerA normal numberThe member to which the distributed load will be applied. Identified by the member ID.
x_mag_AfloatAny number.Magnitude of load in the x-direction at the starting position A.
y_mag_AfloatAny number.Magnitude of load in the y-direction at the starting position A.
z_mag_AfloatAny number.Magnitude of load in the z-direction at the starting position A.
x_mag_BfloatAny number.Magnitude of load in the x-direction at the finish position B.
y_mag_BfloatAny number.Magnitude of load in the y-direction at the finish position B.
z_mag_BfloatAny number.Magnitude of load in the z-direction at the finish position B.
position_AfloatA normal number.Position along member where the distributed load starts. Expressed as a percentage.
position_BfloatA normal number.Position along member where the distributed load ends. Expressed as a percentage.
load_groupstringA string.The load group to which the load belongs.
axesstringglobal, global_projected, localThe axes in which the distributed load will be applied.

Sample code for the distributed_loads object#

The following JSON snippet shows a trapezoidal load in the global y-axis, applied to the middle 80% of member 9:

distributed_loads-sample.json
{
"distributed_loads": {
"1": {
"member": 9,
"x_mag_A": 0,
"y_mag_A": -5,
"z_mag_A": 0,
"x_mag_B": 0,
"y_mag_B": -30,
"z_mag_B": 0,
"position_A": 10,
"position_B": 90,
"load_group": "DL",
"axes": "global"
}
}
}


pressures#

Pressures are uniform loads applied to plates. Each pressure is an object contained within the pressures object, and should be identified by a unique positive integer.

KeyTypeAcceptsDescription
plate_idintegerA normal numberThe plate to which the pressure is applied. Identified by the plate ID.
axesstringglobal, global_projected, localThe axes in which the pressure load will be applied.
x_magfloatAny number.The magnitude of the pressure in the x-direction of the specified axes, in the units of the pressure property of the units object.
y_magfloatAny number.The magnitude of the pressure in the y-direction of the specified axes, in the units of the pressure property of the units object.
z_magfloatAny number.The magnitude of the pressure in the z-direction of the specified axes, in the units of the pressure property of the units object.
load_groupstringA string.The group to which this load belongs.

Sample code for the pressures object#

The following JSON snippet shows a pressure in the global y-axis, applied to plate 1:

pressures-sample.json
{
"pressures": {
"1": {
"plate_id": 1,
"axes": "global",
"x_mag": 0,
"y_mag": -20,
"z_mag": 0,
"load_group": "LL"
}
}
}


area_loads#

Area Loads are uniform loads applied to an area, that are distributed to the members surrounding that area. Each Area Load is an object contained with the area_loads object, and should be identified by a unique positive integer.

KeyTypeAcceptsDescription
typestringone_way, two_way, column_wind_load, open_structure, non_rectangularHow the area load should distribute the load.
nodes[integer]An array of integers.The IDs of the nodes which define the area for loading. Specify 3 or 4 values, in sequential order (clockwise or counterclockwise direction).
members[integer]An array of integers.The IDs of the members which create a closed space for non_rectangular type only..
magfloatAny number.The magnitude of the load, in the units of pressure.
directionstringX, X_projected, Y, Y_projected, Z, Z_projectedThe direction of the load in the global or local axes.
elevationsstringA comma separated string of values.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.
magsstringA comma separated string of values.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_directionstringA comma separated string of 2 integers.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).
LGstringAny string.The load group to which this area load belongs.

Sample code for the area_loads object#

The following JSON snippet shows each type of Area Load, applied to the same nodes, 1, 2, 3 & 4:

area_loads-sample.json
{
"area_loads": {
"1": {
"type": "one_way",
"nodes": [1, 2, 3, 4],
"members": null,
"mag": 10,
"direction": "X",
"elevations": null,
"mags": null,
// Loads will span parallel to the direction from node 1 to node 2
"column_direction": "1,2",
"loaded_members_axis": null,
"LG": "LG"
},
"2": {
"type": "two_way",
"nodes": [1, 2, 3, 4],
"members": null,
"mag": 10,
"direction": "X",
"elevations": null,
"mags": null,
"column_direction": null,
"loaded_members_axis": null,
"LG": "LG"
},
"3": {
"type": "column_wind_load",
"nodes": [1, 2, 3, 4],
"members": null,
"mag": null,
"direction": null,
// Pressure 1 (5 kPa) will apply from 0 to 1.5 m, Pressure 2 (10 kPa) will apply from 1.5 to 3 m
"elevations": "0,1.5,3",
"mags": "5,10",
// Loads will span parallel to the direction from node 1 to node 2
"column_direction": "1,2",
"loaded_members_axis": null,
"LG": "LG"
},
"4": {
"type": "open_structure",
"nodes": [1, 2, 3, 4],
"members": null,
"mag": 10,
"direction": "Y",
"elevations": null,
"mags": null,
"column_direction": null,
"loaded_members_axis": "all",
"LG": "LG"
},
"5": {
"type": "non_rectangular",
"members": "3,7,8,9,16,17,18,19,20", //closed space of members
"mag": -1,
"direction": "Y",
"LG": "LG"
},
}
}


self_weight#

The self-weight for the whole model in S3D can be toggled on or off using the self_weight object.

It is also possible to apply a gravity multiplier in the global x, y or z axes.

KeyTypeAcceptsDescription
enabledbooleantrue, falseIf the self-weight is applied to the model or not.
xfloatAny number.Acceleration due to gravity in the x-axis, defined as a multiplier of the gravitational constant g.
yfloatAny number.Acceleration due to gravity in the y-axis, defined as a multiplier of the gravitational constant g.
zfloatAny number.Acceleration due to gravity in the z-axis, defined as a multiplier of the gravitational constant g.

Sample code for the self_weight object#

The following JSON snippet enables the self-weight, and indicates that gravity should act in the negative y-axis, with g = 1 ร— g:

self_weight-sample.json
"self_weight": {
"enabled": true,
"x": 0,
"y": -1,
"z": 0
}


load_combinations#

Each object in the load_combinations array represents an individual combination. For a single combination, a property for each load group is included. This property comprises the load group name and the load factor for that load group. The load factor is the multiplier applied to all forces and moments within the load group.

KeyTypeDescription
namestringLoad Combination Name
criteriastringOptional criteria that are used in design modules. Options are strength, serviceability or other
SWfloatLoad factor for the Self Weight (SW) load group.
LG1floatLoad factor for (e.g.) the LG1 load group.
LG2floatLoad factor for (e.g.) the LG2 load group.

Sample code for the load_combinations object#

The following JSON snippet shows the creation of two load combinations. The first load combination contains 3 load groups, all with a factor of 1. The second load combination contains 2 load groups, the self-weight has a load factor of 1, and LG1 has a load factor of 1.5.

load_combinations-sample.json
"load_combinations": {
"1": {
"name": "ULS: 1. 1.4D",
"criteria": "strength",
"Dead (Panel load)": 1.4,
"Snow": 0,
"SW1": 1.4,
"Wind downforce": 0,
"Wind uplift": 0
},
"2": {
"name": "ULS: 2. 1.2D + 1.6L + 0.5(S or Lr or R)",
"criteria": "strength",
"Dead (Panel load)": 1.2,
"Snow": 0.5,
"SW1": 1.2,
"Wind downforce": 0,
"Wind uplift": 0
},

--

groups#

Specify similar elements (members, plates, supports) in groups to neatly organise your structure, using the groups object:

KeyTypeAcceptsDescription
namestringAny StringGive your group a name.
idsarrayArray of element IDsArray of integers (element IDs) to include in this group
typestringelements, nodes, supports, plates, groupsWhat is the group comprised of?

Sample code for the group object#

group-sample.json
"groups": {
"1": {
"name": "Some Group of Members",
"ids": [
1,
2,
3,
4,
5,
6,
7,
9
],
"type": "elements"
},
"2": {
"name": "Some Group of Plates",
"ids": [
5,
8,
9
],
"type": "plates"
}
}



Restraint code#

The restraint code is a string made of 6 characters that describes how the member is connected to a node. The first three characters represent translational degrees of freedom in the local X, Y, and Z axes. The last 3 characters represent rotational degrees of freedom about the local X, Y, and Z axes.

F = Fixed, R = Released and S = Spring.

Example: "fixity_A": "FFFFFR" denotes a connection that has fixed translation, fixed rotation about the local X and Y axes, and rotationally released about the z-axis.



How can I test my Structural JSON file?#

There are a few simple and quick ways to test the file you have built:

  1. Import - JSON from the SkyCiv Structural 3D Interface
  2. Via the API - run S3D.file.save and visit the URL in the response. After that, you can simply re-run the API then refresh web browser to update your model


Other Sample files:#

Simple Beam (Imperial): skyciv-sample-1

AISC 3D Frame (exported from S3D): skyciv-sample-2

2,000 Member Structure: skyciv-sample-3

450 Member Structure with 32 Load Combos: skyciv-sample-4


Try s3d_model