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%. | |
offset_Ax | float | Any number. | The local x distance that the member is offset from its centroid at node A. If "type" property = "cable" or "rigid", 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" or "rigid", 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" or "rigid", 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" or "rigid", 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" or "rigid", 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" or "rigid", 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 |
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. |
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.
| Key | Type | Description |
|---|---|---|
type | string | The type of support which is either node or line |
node | integer | The ID of the node at which the support is located when type=node. |
nodes | string | Provide exactly two comma-seprated node IDs for the start and end points of a line support when type=line. For example, "10,16". |
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. |
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] | An array of integers, or (for general_one_way only) a comma separated string 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.. |
mag | float | Any number. | The magnitude of the load, in the units of pressure. Not used for "type": "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, the magnitude of the load — a single value for a uniform load, or n comma separated values to define a stepped/tapered load (paired with n + 1 values in intervals, see below). |
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. | Relevant only if "type": "general_one_way".Orthogonal in-plane distances from the area load's base to each step interval, for defining a stepped/tapered load. Leave blank for a uniform load. To define a stepped load, provide n comma separated magnitudes in mags (see above) and n + 1 comma separated step intervals here. |
excluded_member_ids | string | A comma separated string of integers. | Relevant only if "type": "general_one_way".The IDs of members to exclude from carrying this area load. Leave blank to exclude none. |
exclude_internal_members | string | off, angled, all | Relevant only if "type": "general_one_way".Whether internal members that aren't aligned with the span ( column_direction) should be automatically excluded from carrying this area load: off excludes none, angled excludes non-aligned (angled) internal members, all excludes all internal members. |
cantilever_extensions | string | A comma separated string of 2 values. | Relevant only if "type": "general_one_way".Offsets the left and right edges of the area load polygon in the direction of span, to pick up cantilevered members beyond the defined nodes. Enter the left and right offsets as comma separated values. Leave empty for no extension. |
LG | string | Any string. | The load group to which this area load belongs. |
Preferred area load type
general_one_way is the most robust one-way area load option — it supports non-rectangular spans, stepped/tapered magnitudes, and finer control over which members carry the load (via excluded_member_ids, exclude_internal_members, and cantilever_extensions). Prefer it over the plain one_way type where possible.
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.
| 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. |
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:
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.
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#
gridlines_and_elevations#
Optional. Defines the gridlines and story elevations shown in the SkyCiv Structural 3D platform's Gridlines & Elevations tool. This is purely organisational/visual — it does not affect the analysis — but it also drives certain platform features that operate per-level, such as isolating a single floor. It is not required to build or solve a model.
Unlike most other s3d_model properties, gridlines_and_elevations is an array (not an integer-keyed dictionary) of elevation (story) objects:
| Key | Type | Accepts | Description |
|---|---|---|---|
name | string or integer | Any string or number | The label for this elevation/story, e.g. "Base", 2, 3. |
elevation | float | Any number | The height of this level, in the units defined by the length property of the units object, measured along axis. |
axis | string | x, y, z | The vertical axis this elevation is measured along. Should match the model's settings.vertical_axis. |
is_draw | boolean | true, false | Whether this elevation/level is shown in the Gridlines & Elevations tool. |
columns | array | Array of column marker objects (see below) | The columns that intersect this level. |
beams, plates, points | array | - | Reserved for beam, plate, and point markers at this level. Not yet documented — leave as an empty array ([]). |
gridlines | array | Array of gridline objects (see below) | The gridlines drawn at this level. |
columns object#
Each entry marks a column at this level:
| Key | Type | Description |
|---|---|---|
section_id | integer | The ID of the section applied to this column. |
x | float | The column's x coordinate on this level. |
z | float | The column's z coordinate on this level. |
s3d_id | integer | The ID of the corresponding column in the model's members/nodes objects. |
gridlines object#
Each entry defines one gridline drawn at this level:
| Key | Type | Accepts | Description |
|---|---|---|---|
grid_id | string | Any string | The gridline's label, e.g. "1", "A". This is the value printed next to the gridline. |
start_x, start_z | float | Any number | The coordinates of the gridline's start point. |
end_x, end_z | float | Any number | The coordinates of the gridline's end point. |
vector_x, vector_z | float | Any number | The direction vector of the gridline. |
grid_label | string | start, end | Whether the grid_id label is printed at the start or end point of the gridline. |
startpt, endpt | [float, float] | - | The [x, z] coordinates of the drawn gridline's extents, including the small extension drawn past start_x/start_z and end_x/end_z to make room for the label. |
Sample code for the gridlines_and_elevations object#
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