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.
s3d_models3d_model#
The s3d_model property is comprised of the following properties:
settingsnodesmembersplatesmeshed_platessectionsmaterialssupportssettlementspoint_loadsmomentsdistributed_loadspressuresarea_loadsself_weightload_combinationsload_casesgridlines_and_elevations
settings#
| Key | Type | Accepts | Description | Default |
|---|---|---|---|---|
units | string or object | imperial, metric, {...} | Provide imperial or metric for default units. See Units to set specific units. | Varies per design standard. |
precision | string | fixed, exponential | Number format style. | fixed |
precision_values | integer | Between 1 and 15 | Number of precision. | |
evaluation_points | integer | Between 3 and 50 | number of evaluation points for each member. Higher evaluation points will (slightly) increase the accuracy but will increase the time taken to solve. | |
vertical_axis | string | Y, Z | The axis which defines the vertical direction of the model. | Y |
solver_timeout | integer | Any number. in seconds | How long until the solver timeouts and returns "Solve Failed" if the model is not solving for an unknown reason. | |
accurate_buckling_shape | boolean | true, false | If 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_johnson | boolean | true, false | Use 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_tolerance | string | E.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_theory | string | small, finite | small | |
auto_stabilize_model | boolean | true, false | Enable 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_axis | string | global, local | Specifies if member offsets should be relative to the local or global axis system. | local |
dynamic_modes | integer | Any positive integer | The maximum number of modes that the dynamic frequency analysis will return. | 5 |
dynamic_frequency_area_reduction_factor | float | Any positive number | This factor reduces the area of these members to reduce their axial stiffness since they'll usually be used for bracing. | 1 |
units#
| Key | Type | Accepts | Description |
|---|---|---|---|
length | string | ft in mm m | Length for defining elements. |
section_length | string | in, mm | Length for defining section properties. |
material_strength | string | ksi, psi, mpa | |
density | string | lb/ft3, kg/m3 | |
force | string | kip, lb, kn, n, kg | |
moment | string | kip-ft, lb-ft, lb-in, kn-m, n-m, kg-m | |
pressure | string | ksi, ksf, psi, psf, kpa, mpa, pa | |
mass | string | kip, lb, kg | |
translation | string | mm, in | |
stress | string | ksi, psi, mpa, kpa |
important
Unit systems can not be mixed between Imperial/Metric.
Sample code for the settings object#
- Option 1 - Partially specify
- Option 2 - Entirely specified
Default units#
Using a value of imperial or metric for the units property will set the units to the following.
- Imperial
- Metric
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.
| Key | Type | Description |
|---|---|---|
x | float | The x coordinate of the node |
y | float | The y coordinate of the node |
z | float | The 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.
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.
| Key | Type | Accepts | Description | Default |
|---|---|---|---|---|
type | string(optional) | normal, normal_continuous, cable, tension, compression, rigid |
| normal |
cable_length | float(optional) | Any non-negative number | Relevant 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_A | integer | Any non-negative number | The start node, identified by the node ID | |
node_B | integer | Any non-negative number | The end node, identified by the node ID | |
section_id | integer | Any non-negative number, or null for type = rigid | The ID of the section to be applied to the member. Must be positive. sections are defined in their own object. | |
rotation_angle | float optional | Number between -180 and 180 | Rotation 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 or rigid. | |
fixity_A | string | How the member is connected about node A, represented by a restraint code. If "type" property = "cable", this value is ignored. | ||
fixity_B | string | How the member is connected about node B, represented by a restraint code. If "type" property = "cable", this value is ignored. | ||
stiffness_A_Ry | string | Number > 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_Rz | string | Number > 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_Ry | string | Number > 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_Rz | string | Number > 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%. | |
disable_non_linear_effects | string(optional) | yes, no | If yes, disables non-linear effects (e.g. P-Delta) for this member even if enabled globally. | no |
offset_Ax | float | Any 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_Ay | float | Any 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_Az | float | Any 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_Bx | float | Any 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_By | float | Any 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_Bz | float | Any 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. | |
mirror | string(optional) | no, y, z, y_and_z | Mirrors the member's section about its local y-axis, z-axis, or both, without needing a separately mirrored section in the section library. | no |
disable_non_linear_effects | string(optional) | yes, no | When yes, this member is excluded from the model's non-linear/P-delta effects, even when a non-linear analysis is otherwise active. | no |
note
The offsets must be entered in the units defined by the section_length property of the units object.
tip
Unless you need true catenary cable behavior (significant sag under self-weight), a pinned tension member is simpler and avoids triggering a non-linear analysis, unlike cable.
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.
The third member is a pinned, tension-only bracing member spanning from node 6 to 7.
The fourth member is a rigid link between nodes 8 and 9, transferring axial and shear forces but no moments.
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.
| Key | Type | Accepts | Description | Default |
|---|---|---|---|---|
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. | |
thickness | float | A normal number | The thickness of the plate. The units of thickness are defined by the section_length property of the units object | |
material_id | integer | A normal number | The material of the plate. Identified by the material ID defined in the materials object. | |
rotZ | float | Rotation of the plate about its local Z (normal) axis in degrees. | 0.0 | |
type | string | auto | This will consider shear deformation when the plate thickness is sufficient. | auto |
offset | float | Offset of the plate along its local z-axis | ||
diaphragm | string | no, rigid | If the plate is a diaphragm. | no |
diaphragm_internal_nodes | [integer] or null | An array of node IDs | Internal node IDs included in a rigid diaphragm for this plate; null if not applicable. | null |
diaphragm_fixity | string or null | Fixity/restraint applied to the diaphragm; null if not applicable. | null | |
drilling_stiffness_factor | float | Factor applied to the plate's drilling (rotational) stiffness about its normal axis. | ||
membrane_thickness | float | ≥0 | The membrane thickness to be used. Takes the value of thickness if null. | thickness |
shear_thickness | float | ≥0 | The shear thickness to be used. Takes the value of thickness if null. | thickness |
bending_thickness | float | ≥0 | The bending thickness to be used. Takes the value of thickness if null. | thickness |
state | string | stress, strain | Denotes whether the plate is in a state of plane stress or plane strain. | stress |
holes | [integer] | An array of node IDs | Used to define holes in the plate. | null |
isMeshed | boolean | true, false | Indicates 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#
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.
| Key | Type | Description | Default |
|---|---|---|---|
node_A | integer | The first node of the meshed plate. | |
node_B | integer | The second node of the meshed plate. | |
node_C | integer | The third node of the meshed plate. | |
node_D | integer | The fourth node of the meshed plate. Set this to null (None for a Python dictionary) if the meshed plate is triangular. | |
parent_plate | integer | The ID of the plate which this meshed plate originated from. Must refer to a plate in the plates object. | |
rotZ | float | Rotation 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:
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:
load_section: Load a library section from the "Database Shapes" of SkyCiv Section Builder.load_custom: Load a custom section from the "My Sections" of SkyCiv Section Builder. These are your custom sections that you've saved to the cloud storage of the section builder.- Full SB JSON Format: Manually define the full format that the SkyCiv Section Builder constructs internally. You can view this full object when exporting an model JSON from S3D. It is difficult to construct this full object manually so it's not typically recommended.
- Minimal JSON Format: This is the simplest format you can provide as it only defines the essential section properties (A, Iy, Iz, J). Since no shape or dimensions are provided, this type of section cannot be used for 3D renderering, stress results or design calculations. It's only appropriate for an S3D analysis.
- Template Shape: Create a "Template Shape" by specifying a shape and dimensions. These match the "Shape Templates" seen in SkyCiv Section Builder.
- Non-Prismatic: This type of section is used for defining a non-prismatic member which is a member that has a varying cross section.
- load_section
- load_custom
- Full SB JSON Format
- Minimal JSON Format
- Template Shape
- Non-Prismatic
Load a library section from the "Database Shapes" of SkyCiv Section Builder.
| Key | Type | Description |
|---|---|---|
load_section | [string] | Provided as an array of 4 strings (see example below). It is the path of the section in the "Database Shapes", obtained by inspection from within SkyCiv Section Builder or by attaining the library tree via S3D.SB.getLibraryTree |
material_id | integer | The 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
Load a custom section from the "My Sections" of SkyCiv Section Builder. These are your custom sections that you've saved to the cloud storage of the section builder.
| Key | Type | Description |
|---|---|---|
load_custom | string or [string] | The name of a shape defined in "My Sections" of SkyCiv Section Builder. Use an array to specify the folders of your storage. |
material_id | integer(optional) | The ID of the material that will be assigned to all shapes in the section. This is optional and if it's not provided then the materials that were saved with the section will be used. materials are defined in their own object. |
Sample code for the sections object using the load_custom property
Manually define the full format that the SkyCiv Section Builder constructs internally. You can view this full object when exporting an model JSON from S3D. It is difficult to construct this full object manually so it's not typically recommended.
| Key | Type | Description |
|---|---|---|
version | float | The version of SkyCiv Section Builder that was used to construct this object. |
name | string | The name of your section. If nothing is entered, the name will default to the (rounded) height x width dimensions. |
area | float | Cross-sectional area. |
Iy | float | Area moment of inertia about the section y-axis. |
Iz | float | Area moment of inertia about the section z-axis. |
material_id | integer | The ID of the material that is assigned to the section. materials are defined in their own object. |
shear_area_z | float(optional) | Shear Area in the section z-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. This should not be confused with the property of the same name within the aux object. |
shear_area_y | float(optional) | Shear Area in the section y-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. This should not be confused with the property of the same name within the aux object. |
aux | object | The aux property is an object containing various section property values.It contains the geometric coordinates of the cross-section, among other properties, that are calculated via the Section Builder Platform. For brevity, these individual properties are not detailed here. To understand how to create a section via the Section Builder Platform and implement it into the API, please contact us at [email protected] |
Sample code for the sections object using the Section Builder format
This is the simplest format you can provide as it only defines the essential section properties (A, Iy, Iz, J). Since no shape or dimensions are provided, this type of section cannot be used for 3D renderering, stress results or design calculations. It's only appropriate for an S3D analysis.
| Key | Type | Description |
|---|---|---|
name | string | The name of your section. If nothing is entered, the name will default to the (rounded) height x width dimensions. |
material_id | integer | The ID of the material that is assigned to the section. materials are defined in their own object. |
shear_area_z | float(optional) | Shear Area in the section z-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. |
shear_area_y | float(optional) | Shear Area in the section y-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. |
area | float | Cross-sectional area. |
Iy | float | Area moment of inertia about the section y-axis. |
Iz | float | Area moment of inertia about the section z-axis. |
J | float | Torsion constant. |
Sample code for the sections object using the Custom Input option
The following JSON snippet shows both methods of specifying the section data:
Create a "Template Shape" by specifying a shape and dimensions. These match the "Shape Templates" seen in SkyCiv Section Builder.
| Key | Type | Description |
|---|---|---|
info | object | The shape information which contains the shape type and dimensions. See the possible values below. |
material_id | integer | The ID of the material that is assigned to the section. materials are defined in their own object. |
Sample code for the sections object using template shapes.
When you define a section for a non-prismatic member, the regular section defintion (as per the other methods above) will define the STARTING shape of the member (i.e. at Node A).
You can provide a non_prismatic object to define the ENDING shape of the member (i.e. at Node B). The API and Section Builder will then vary the shape from the STARTING shape to the ENDING shape. This can be used to define a tapered or haunched member.
The following shapes are supported for non-prismatic sections:
rectanglehollow rectangleibeamtbeamlipped channel box
| Key | Type | Accepts | Description |
|---|---|---|---|
enabled | boolean | true, false | Whether the non-prismatic definition is enabled for this section. |
type | string | taper | Currently only tapers can be defined through the API. Haunches are only supported through the UI as they require two shapes to be defined in the section. |
depth_taper | object | See below | Defines how the depth of the section varies along the member. width_taper, depth_taper, or both can be provided. |
depth_taper.bottom | boolean | true, false | Whether the bottom edge of the section tapers. |
depth_taper.top | boolean | true, false | Whether the top edge of the section tapers. |
depth_taper.start | float | A positive number | The starting depth. Optional — if omitted, it is automatically taken from the starting shape. |
depth_taper.end | float | A positive number | The ending depth. |
width_taper | object | See below | Defines how the width of the section varies along the member. width_taper, depth_taper, or both can be provided. |
width_taper.left | boolean | true, false | Whether the left edge of the section tapers. |
width_taper.right | boolean | true, false | Whether the right edge of the section tapers. |
width_taper.start | float | A positive number | The starting width. Optional — if omitted, it is automatically taken from the starting shape. |
width_taper.end | float | A positive number | The ending width. |
consider_offsets | boolean | true, false | Choose whether offsets should be added to the prismatic member segments to ensure that the centerlines of each segment are aligned. Usually it is simpler to avoid offsets as they can introduce undesirable actions/forces. Defaults to false. |
member_sizes | string | average, maximum, minimum | Maximum will be the most conservative. Defaults to average. |
segments | integer | An integer from 2 to 10 inclusive | The number of segments the member is divided into to approximate the varying shape. Defaults to 4. |
Sample code for the non_prismatic object#
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
name | string | Any string | The name of the material |
density | float | A normal number | The density of the material. |
elasticity_modulus | float | A normal number | The Modulus of Elasticity (or Young's Modulus) of the material. |
poissons_ratio | float | A normal number | The Poisson's Ratio for the material. |
yield_strength | float | A normal number | The Yield strength of the material. |
ultimate_strength | float | A normal number | The Ultimate strength the material. |
class | string | steel, aluminium, masonry, concrete, wood, other | The type of material. |
thermal_expansion_coefficient | float | A normal number | The coefficient of thermal expansion of the material. |
shear_modulus | float | A number > 0 | The shear modulus of the material. |
elasticity_modulus_x | float | A number > 0 | Orthotropic modulus of elasticity in the material's local x direction. |
elasticity_modulus_y | float | A number > 0 | Orthotropic modulus of elasticity in the material's local y direction. |
shear_modulus_xy | float | A number > 0 | Orthotropic shear modulus in the xy plane. |
shear_modulus_xz | float | A number > 0 | Orthotropic shear modulus in the xz plane. |
shear_modulus_yz | float | A number > 0 | Orthotropic shear modulus in the yz plane. |
poissons_ratio_xy | float | A normal number | Orthotropic Poisson's ratio in the xy plane. |
Sample code for the materials object#
The following JSON snippet adds several materials, to the model using the metric system.
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.
By default, a support is applied to a single node. Alternatively, setting type to line applies the same restraint along a straight line running through multiple nodes, instead of requiring one entry per node.
| Key | Type | Description |
|---|---|---|
type | string | node (default) applies the support to a single node. line applies the support along a line connecting multiple nodes. |
node | integer | The ID of the node at which the support is located. Required when type is node (or omitted). |
nodes | string | Comma-separated list of node IDs the line support runs through, e.g. "4,5,7,6". Required when type is line. |
restraint_code | string | A 6 character restraint code. |
tx | float | Spring stiffness for translation in the x-axis. Applies only if the restraint code character for translation in x = S. |
ty | float | Spring stiffness for translation in the y-axis. Applies only if the restraint code character for translation in y = S. |
tz | float | Spring stiffness for translation in the z-axis. Applies only if the restraint code character for translation in z= S. |
rx | float | Spring stiffness for rotation about the x-axis. Applies only if the restraint code character for rotation about x = S. |
ry | float | Spring stiffness for rotation about the y-axis. Applies only if the restraint code character for rotation about y = S. |
rz | float | Spring stiffness for rotation about the z-axis. Applies only if the restraint code character for rotation about z = S. |
non_linear_spring_stiffness | object (optional) | Defines a non-linear (variable) stiffness for one or more spring directions (tx/ty/tz/rx/ry/rz), instead of a single constant value. |
non_linear_spring_stiffness: an object keyed by direction (tx, ty, tz, rx, ry, rz). Each direction entry has:
| Key | Type | Description |
|---|---|---|
stiffness_dependency | string | The quantity the stiffness varies with, e.g. "reaction_fx", "reaction_mx", "displacement_rx". |
relationship | object | Defines the stiffness curve. Has symmetric (boolean — if true, the curve is mirrored for negative values of the dependency) and values (an array of [dependency_value, stiffness_value] pairs describing a piecewise curve). |
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.
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.
| Key | Type | Description |
|---|---|---|
node | integer | The node ID of the node to which the settlement is applied. |
tx | float | Settlement displacement in the global x-axis. |
ty | float | Settlement displacement in the global y-axis. |
tz | float | Settlement displacement in the global z-axis. |
rx | float | Settlement rotation about the global x-axis. |
ry | float | Settlement rotation about the global y-axis. |
rz | float | Settlement 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:
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
type | string | n, m | The type of object to which the load is applied. node, member |
node | integer | A normal number | Include the property node only when applying the point load to a node. The value should be the node ID. |
member | integer | A normal number | Include the property member only when applying the point load to a member. The value should be the member ID. |
position | float | 0-100 | Include 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_mag | float | Any number. | The magnitude of the point load along the x-axis. |
y_mag | float | Any number. | The magnitude of the point load along the y-axis. |
z_mag | float | Any number. | The magnitude of the point load along the z-axis. |
load_group | string | A 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:
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
type | string | n, m | The type of object to which the load is applied. node, member |
node | integer | A normal number | Include the property node only when applying the moment to a node. The value should be the node ID. |
member | integer | A normal number | Include the property member only when applying the moment to a member. The value should be the member ID. |
position | float | 0-100 | Include 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_mag | float | Any number. | The magnitude of the moment about the x-axis. Positive = counter-clockwise, negative = clockwise. |
y_mag | float | Any number. | The magnitude of the moment about the y-axis. Positive = counter-clockwise, negative = clockwise. |
z_mag | float | Any number. | The magnitude of the moment about the z-axis. Positive = counter-clockwise, negative = clockwise. |
load_group | string | A 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:
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
member | integer | A normal number | The member to which the distributed load will be applied. Identified by the member ID. |
x_mag_A | float | Any number. | Magnitude of load in the x-direction at the starting position A. |
y_mag_A | float | Any number. | Magnitude of load in the y-direction at the starting position A. |
z_mag_A | float | Any number. | Magnitude of load in the z-direction at the starting position A. |
x_mag_B | float | Any number. | Magnitude of load in the x-direction at the finish position B. |
y_mag_B | float | Any number. | Magnitude of load in the y-direction at the finish position B. |
z_mag_B | float | Any number. | Magnitude of load in the z-direction at the finish position B. |
position_A | float | A normal number. | Position along member where the distributed load starts. Expressed as a percentage. |
position_B | float | A normal number. | Position along member where the distributed load ends. Expressed as a percentage. |
load_group | string | A string. | The load group to which the load belongs. |
axes | string | global, global_projected, local | The 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:
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
plate_id | integer | A normal number | The plate to which the pressure is applied. Identified by the plate ID. |
axes | string | global, global_projected, local | The axes in which the pressure load will be applied. |
x_mag | float | Any 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_mag | float | Any 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_mag | float | Any 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_group | string | A 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:
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.
| Key | Type | Accepts | Description |
|---|---|---|---|
type | string | one_way, two_way, general_one_way, column_wind_load, open_structure, non_rectangular | How the area load should distribute the load. |
nodes | [integer] or string | An array of integers, or (for general_one_way) a comma-separated string. | 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.. |
mag | float | Any number. | The magnitude of the load, in the units of pressure. Not used for general_one_way — use mags instead. |
direction | string | X, X_projected, Y, Y_projected, Z, Z_projected | The direction of the load in the global or local axes. |
elevations | string | A 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. |
mags | string | A comma separated string of values. | Relevant only if "type": "column_wind_load" or "type": "general_one_way".For 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.For general_one_way, a single value for a uniform load, or n values paired with n + 1 values in intervals for a stepped/tapered load. |
column_direction | string | A comma separated string of 2 integers. | Relevant only if "type": "one_way", "type": "column_wind_load", or "type": "general_one_way".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" or "type": "general_one_way".Whether to apply the 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). |
intervals | string | A comma separated string of values. | general_one_way only. Comma-separated step-interval distances, n + 1 values matching n values in mags. Blank means a uniform load. |
excluded_member_ids | string | A comma separated string of member IDs. | general_one_way only. Member IDs to exclude from carrying the load. |
exclude_internal_members | string | off, angled, all | general_one_way only. Auto-excludes internal members not aligned to the span. |
cantilever_extensions | string | A comma separated string, e.g. "left,right". | general_one_way only. Offsets extending the load polygon along the span to pick up cantilevered members. |
distributed_moments | [object] | An array. | Distributed moments applied as part of this area load. |
elevation_direction | string | Relevant only for "type": "two_way". The direction used to interpret elevations for this area load. | |
plate_material_id | integer | Relevant only for "type": "two_way". Material ID assigned to plates auto-generated from this area load. | |
plate_thickness | float | Relevant only for "type": "two_way". Thickness assigned to plates auto-generated from this area load. | |
plate_torsion | string | yes, no | Relevant only for "type": "two_way". Whether torsion is considered for plates auto-generated from this area load. |
plate_rotation | float | Relevant only for "type": "two_way". Rotation (about local Z) assigned to plates auto-generated from this area load. | |
number_of_segments | integer | Relevant only for "type": "two_way". Number of segments used to discretize plates auto-generated from this area load. | |
LG | string | Any string. | The load group to which this area load belongs. |
Prefer
general_one_wayover plainone_way— it supports non-rectangular spans, stepped/tapered magnitudes, and finer control over which members carry the load.
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:
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. self_weight supports either of the two shapes below for a single self-weight case. For multiple self-weight cases, key self_weight by integer id instead — each instance requires x, y, and z, with an LG/load_group that must equal "SW" followed by that same id (e.g. self_weight["10"] must use "LG": "SW10").
Legacy format — x/y/z gravity multipliers:
| Key | Type | Accepts | Description |
|---|---|---|---|
enabled | boolean | true, false | If the self-weight is applied to the model or not. |
x | float | Any number. | Acceleration due to gravity in the x-axis, defined as a multiplier of the gravitational constant g. |
y | float | Any number. | Acceleration due to gravity in the y-axis, defined as a multiplier of the gravitational constant g. |
z | float | Any number. | Acceleration due to gravity in the z-axis, defined as a multiplier of the gravitational constant g. |
LG / load_group | string | e.g. "SW1" | The Load Group to which the self weight belongs. |
Simplified format — a single direction/factor pair:
| Key | Type | Accepts | Description |
|---|---|---|---|
direction | string | X, Y, Z | The axis along which self weight gravity acts. |
factor | float | Any number. | Gravity multiplier applied in the given direction (e.g. -1 for standard downward gravity). |
LG / load_group | string | "SW" optionally followed by an integer, e.g. "SW" or "SW2" | The Load Group to which the self weight belongs. |
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:
The following JSON snippet uses the simplified direction/factor format for the same effect:
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.
| Key | Type | Description |
|---|---|---|
name | string | Load Combination Name |
criteria | string | Optional criteria that are used in design modules. Options are strength, serviceability or other |
SW | float | Load factor for the Self Weight (SW) load group. |
LG1 | float | Load factor for (e.g.) the LG1 load group. |
LG2 | float | Load 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_cases#
Maps load groups to standard load type categories for a named design code. Used to auto-generate code-based load combinations. The top-level key is the design code identifier; each nested key is a load group name from your model, and the value is the code-defined load type.
tip
Multiple load groups can map to the same load type (e.g. several wind direction groups all mapped to "W"). Multiple design codes can coexist in the same load_cases object.
note
The older short-code design code identifiers ("AISC", "ASCE", "AS", "EN", "NBCC") remain valid as top-level keys alongside the newer full code+version identifiers shown above (e.g. "AS-1170.0-2002", "ASCE-7-2022-LRFD", "EN-1990-2002").
groups#
Specify similar elements (members, plates, supports) in groups to neatly organise your structure, using the groups object:
| Key | Type | Accepts | Description |
|---|---|---|---|
name | string | Any String | Give your group a name. |
ids | array | Array of element IDs | Array of integers (element IDs) to include in this group |
type | string | elements, nodes, supports, plates, groups | What is the group comprised of? |
Sample code for the group object#
member_prestress_loads#
Applies a prestress force to a member. Each object is identified by a unique positive integer.
| Key | Type | Accepts | Description |
|---|---|---|---|
load_group | string | Any string | The load group to which this prestress load belongs. |
member_id | integer | Any positive integer | The ID of the member the prestress load is applied to. |
prestress_magnitude | float | Any number | The magnitude of the prestress force applied to the member. |
Sample code for the member_prestress_loads object#
thermal_loads#
Applies a temperature change to a member or plate. Each object is identified by a unique positive integer.
| Key | Type | Accepts | Description |
|---|---|---|---|
element_type | string | member, plate | The type of element this thermal load is applied to. |
element_id | integer | Any positive integer | The ID of the member or plate this thermal load is applied to. |
thermal_load | float | Any number | The temperature change applied by this thermal load. |
load_group | string | Any string | The load group to which this load belongs. |
Sample code for the thermal_loads object#
nodal_masses#
Applies additional translational and rotational mass to a node, e.g. for use in dynamic frequency or response spectrum analysis. Each object is identified by a unique positive integer.
| Key | Type | Accepts | Description |
|---|---|---|---|
node_id | integer | Any positive integer | The ID of the node the mass is applied to. |
tx_mass | float | A non-negative number | Translational mass in the global x-axis. |
ty_mass | float | A non-negative number | Translational mass in the global y-axis. |
tz_mass | float | A non-negative number | Translational mass in the global z-axis. |
rx_mass | float | A non-negative number | Rotational mass about the global x-axis. |
ry_mass | float | A non-negative number | Rotational mass about the global y-axis. |
rz_mass | float | A non-negative number | Rotational mass about the global z-axis. |
source | string | e.g. "User Defined" | Indicates how the nodal mass was generated. |
spectral_loads#
Defines response spectrum loads used in dynamic response spectrum analysis. Each object is identified by a unique positive integer.
| Key | Type | Accepts | Description |
|---|---|---|---|
input_method | integer | 1, 2 | 1 if the load was generated via user input, 2 if by design code. |
design_code | string or null | EN8, ASCE, "", null | The selected design code if the load was generated via design code. |
design_data | object | Design-code-specific inputs used to generate the spectrum (e.g. rs_type, rs_peak, rs_damp). | |
xy_data | [object] | Array of {x, y} pairs | Values for the response spectrum XY plot: Period T (x), Spectral Value (y). |
load_dir | string | X, Z, XZ, Y | Direction of the load. |
load_angle | float | 0 to 360 | Angle of the load if XZ was chosen for direction. |
load_factor | float | Any number | Factor multiplier for the load. |
load_combo_method | string | CQC, ABS, SRSS, Linear | Method used to calculate the impact of load combinations. |
load_damping_ratio | float | Any number | Damping ratio for this load. |
save_sign | string | yes, no | Whether to preserve the sign of results when combining modal responses. |
LG | string | Any string | The load group this load belongs to. |
moving_loads#
Defines vehicle/moving loads for bridge/traffic-line style analysis, comprising traffic lines, vehicle loads, and generated load cases.
| Key | Type | Description |
|---|---|---|
traffic_lines | object | Traffic lines (identified by a unique positive integer) defining the paths along which vehicle loads travel across members. |
vehicle_loads | object | Vehicle load definitions (axle spacings, weights, etc.) applied to traffic lines. |
cases | object | Generated moving load cases combining vehicle loads with traffic lines. |
suppress#
Tracks which model elements are suppressed (hidden from analysis) per named suppression set, plus the currently active set. Array should include element IDs you wish to suppress.
| Key | Type | Description |
|---|---|---|
current_case | string | The name of the currently active suppression set. |
"<set name>" | object | A named suppression set (e.g. "All On", "User Defined"). Each property (members, plates, supports, moments, distributed_loads, point_loads, area_loads, pressures, load_combinations) is an array of suppressed IDs for that element collection. |
load_combination_settings#
Settings that control the automatic generation of code-based load combinations from load_cases.
| Key | Type | Description |
|---|---|---|
country | string | The country associated with the selected design code. |
code | string | The design code (and version) used to auto-generate load combinations, e.g. "AS-1170.0-2002". |
criteria | string | Which combination criteria to generate, e.g. "All". |
filters | object | UI filter selections used when generating load combinations. |
load_case_order | array | The display/generation order of load group names. |
patterns | object | Load pattern and ratio settings (e.g. simultaneous vs alternate, main/alternate ratios) used when generating combinations. |
load_case_mappings | object | Maps short load group codes to their full descriptive load case names. |
load_case_sub_groups | array | Sub-group assignments ({"name", "sub_group"}) for load group names, used to control which load groups are combined together. |
See
load_combinationsandload_casesfor how this setting fits into the overall load-combination generation workflow.
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:
- Import - JSON from the SkyCiv Structural 3D Interface
- Via the API - run
S3D.file.saveand 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