S3D.model

The S3D.model namespace provides functions which take action on the s3d_model object.

note

To create a model object, see s3d_model.

`S3D.model.set`#

Setting a model is the first step to running any analysis, design or running any other functionality on a structural model.

Key	Type	Accepts	Description
`s3d_model`	`object`	A s3d_model object	An object containing information that represents a Structural 3D model.

Sample input for S3D.model.set

{
    "function": "S3D.model.set",
    "arguments": {
        "s3d_model": MODEL_OBJECT
    }
}

The response will confirm whether or not the model was successfully set.

Sample response for S3D.model.set

{
    "msg": "Model was successfully set.",
    "status": 0,
    "data": ""
}

Try S3D.model.set

`S3D.model.get`#

Once the model is set, you can request the model data at any time by calling the function S3D.model.get. This function takes no arguments, and will return the s3d_model object.

important

S3D.model.get will only work if S3D.model.set has been called earlier in the session.

Sample input for S3D.model.get

{
    "function": "S3D.model.get"
}

The response will return the s3d_model object.

Sample response for S3D.model.get

{
    "data": MODEL_OBJECT,
    "status": 0,
    "function": "S3D.model.get",
    "msg": ""
}

`S3D.model.repair`#

S3D.model.repair will run SkyCiv's repair model functionality. This will identify any issues with the model and repair them to ensure the analysis model is built correctly. To test the behaviour of these features, we recommend using the Repair Model function in the S3D UI.

important

S3D.model.set must be called earlier in the session.

Key	Type	Accepts	Description	Default
`checks`	`[string]`	`unused_nodes` `large_structure` `merge_nodes` `zero_members` `continuous_to_normal_members` `intersect_members` `default_section` `force_plate_mesh`	An array of strings defining the checks to be performed.	all

`checks`#

unused_nodes - scan model for nodes that are floating and disconnected.
large_structure - detect extremely slender members (used to detect unit issues).
merge_nodes - merge close nodes with a tolerance based on unit system.
zero_members - detect members that have the same start/end node.
continuous_to_normal_members - detect any members with intermediate nodes and splits them to ensure they are properly connected. This will also change the member type to 'normal'
intersect_members - detect and connect intersecting members.
default_section - find any members with no section data, add a default section.
force_plate_mesh - allow analysis to run without plates being meshed first.

Sample input for S3D.model.repair

{
    "function": "S3D.model.repair",
    "arguments": {
        "checks": [
            "unused_nodes",
            "large_structure",
            "merge_nodes",
            "zero_members",
            "continuous_to_normal_members",
            "intersect_members",
            "default_section",
            "force_plate_mesh"
        ]
    }
}

The response will confirm whether or not the model was successfully repaired.

Sample response for S3D.model.repair

{
    "data": REPAIRED_MODEL_OBJECT,
    "msg": "S3D model successfully repaired",
    "status": 0
}

`S3D.model.solve`#

Runs a structural analysis on your s3d_model.

Key	Type	Accepts	Description	Default
`analysis_type`	`string`	`linear`, `nonlinear`, `buckling`, `dynamic`, `response_spectrum`	The type of analysis to be performed.	`linear`
`repair_model`	`boolean`	`true`, `false`	If `S3D.model.repair` should be executed prior to solving.	`false`
`return_data`	`boolean`	`true`, `false`	To minimize data downloaded, solve data will be removed.	`true`
`format`	`string`	`json`, `csv`	Export results in particular file format.	`json`
`lc_filter`	`[string]`	`envelope`, `load_case`, `load_group`, `load_combo`, `envelope_abs_max`	Only return specific data in the response. You can also provide names you have applied to load combination. E.g. `LC1`.	All cases
`result_filter`	`[string]`	`reactions`, `member_displacements`, `member_forces`, `member_stresses`, `member_lengths`, `member_stations`, `member_discontinuities`, `member_minimums`, `member_maximums`, `member_peak_results`, `plate_displacements`, `plate_forces`, `plate_stresses`, `plate_minimums`, `plate_maximums`, `plate_peak_results`, `buckling`, `dynamic_frequency`	Only return specific data in the response.	All results
`ignore_area_load_validation`	`boolean`	`true` or `false`	Ignore area load variance checks and solve anyway	`true`
`allowable_area_load_variance`	`float`	e.g `3`	Ignore area load variance that are below this percentage. In percentage as a whole number	`true`

tip

Using the filter properties will drastically reduce the size of the response therefore saving on download data and time.

Sample input for S3D.model.solve

{
    "function": "S3D.model.solve",
    "arguments": {
        "analysis_type": "nonlinear",
        "repair_model": true,
        "lc_filter": ["envelope_abs_max", "LC1"],
        "result_filter": ["member_peak_results", "member_discontinuities"]
    }
}

Try S3D.model.solve

The analysis results will return an object of all the load combination results in the following format. If the solver fails to run, it will return with a status: 1 and an error message to assist in debugging the issue.

Sample response for S3D.model.solve

{
    "1": {
        "name": "LC1",
        "type": "user_defined",
        "reactions": {},
        "member_displacements": {},
        "member_forces": {},
        "member_stresses": {},
        "member_lengths": {},
        "member_stations": {},
        "member_discontinuities": {},
        "member_minimums": {},
        "member_maximums": {},
        "member_peak_results": {},
        "plate_displacements": {},
        "plate_forces": {},
        "plate_stresses": {},
        "plate_minimums": {},
        "plate_maximums": {},
        "plate_peak_results": {}
    },
    "2": {} // etc
}

`S3D.model.takeScreenshot`#

Take screenshots of the model.

important

S3D.model.set must be called earlier in the session.

Key	Type	Accepts	Description
`views`	`[string]`	`iso`, `front`, `side`, `top`, `thumbnail`, `custom`	Array of strings, defining the different perspectives to take a screenshot from.
`is_renderer`	`boolean`	`true`, `false`	Take screenshots of the structure in the 3D renderer.
`wireframe_settings`	`object`	An object as defined in `wireframe_settings`	An object defining additional settings. Only applicable to WIREFRAME display.
`renderer_settings`	`object`	An object which matches the S3D Renderer settings: `renderer_settings`	An object defining additional settings. Only applicable to RENDERER display.
`custom_view`	`object` optional	An object with x, y, z values	This object specifies the position of the camera in global 3D space `{ x: 100, y: 2, z: 3 }`. Only applies when `view=custom`.
`scale`	`float` optional	A number between 0 and 5 (default is 1)	Defines the scale slider for the graphics (loads and results). A higher number makes the scale larger. Only applicable to WIREFRAME display.
`zoom_factor`	`float` optional	A number between -50 and 50 (default is 0 which is no zoom)	Defines the factor to zoom the graphics. A positive number zooms in while a negative number zooms out. Only applicable to WIREFRAME display.

Input for `wireframe_settings`#

Key	Type	Accepts	Description
`show_nodes`	`boolean`	`true`, `false`	If nodes should be visible.
`show_loads`	`boolean`	`true`, `false`	If loads should be visible.
`show_plates`	`boolean`	`true`, `false`	If plates should be visible.
`projection`	`string`	`perspective`, `orthographic`	The projection of the model to the view-point.

Sample input for Wireframe

{
    "function": "S3D.model.takeScreenshot",
    "arguments": {
        "views": ["iso", "front", "side", "top"],
        "is_renderer": false,
        "scale": 1,
        "zoom_factor": 1,
        "wireframe_settings": {
            "show_nodes": true,
            "show_loads": false,
            "show_plates": true,
            "projection": "perspective"
        }
    }
}

Sample input for Renderer

{
    "function": "S3D.model.takeScreenshot",
    "arguments": {
        "is_renderer": true,
        "renderer_settings": {
            "visibility": {
                "nodes": true,
                "node_id_labels": false,
                "members": true,
                "member_id_labels": false,
                "plates": true,
                "plates_mesh": false,
                "supports": false,
                "floor_grid": false,
                "local_axis": false,
                "global_origin_axis": false,
                "global_axis": true,
                "logo": true,
                "label_font_size": "12px",
                "loads": false,
                "load_labels": false,
                "load_group": null
            },
            "grid": {
                "vertical_offset": 0
            },
            "lighting": {
                "shadows": false,
                "shadow_softening": 1,
                "sun_horizontal_position": 180
            },
            "projection_mode": "perspective",
            "display_mode": "solids_and_edges",
            "colors": 1,
            "transparency": {
                "members": 0.5,
                "plates": 0.3
            }
        },
        "views": [
            "iso",
            "front",
            "side",
            "top"
        ]
    }
}

Try S3D.model.takeScreenshot

note

The response will return an object of screenshots in base64 format.

Sample response for S3D.model.takeScreenshot

{
    "status": 0,
    "msg": "Screenshots successfully taken and returned in base64 format.",
    "data": {
        "iso": "data:image/png;base64,iVBORw0K...",
        "front": "data:image/png;base64,EACEpCABCQg....",
        "side": "data:image/png;base64,GABCQgAQlIQAI....",
        "top": "data:image/png;base64,CABCUhAAhKQgAQ...."
    }
}

The following is an example of the isometric screenshot from the above sample:

`S3D.model.mesh`#

Mesh the plates in the s3d_model object.

Key	Type	Accepts	Description	Default
`method`	`string`	`frontal_quads`, `frontal`, `adapt`, `packing_parallelograms`, `delaunay`	Specify what type of mesher to use.	`frontal`
`granularity`	`integer`	`1`-`5`	Integer between 1 and 5 for level of granularity of mesh (1 is coarse, 5 is fine).	`1`
`plate_ids`	`[integer]`	An array of plate ids.	Array of plates you wish to mesh.	All plates if property is not provided.

Sample input for S3D.model.mesh

{
    "function": "S3D.model.mesh",
    "arguments": {
        "method": "delaunay",
        "granularity": 3,
        "plate_ids": [1, 3]
    }
}

`S3D.model.script`#

Allows you to run custom JavaScript functions to access all S3D functionality such as intersecting or adding new nodes or members. Available functions can be found here.

Key	Type	Accepts	Description
`script`	`string`	A string of JavaScript	Define custom actions to run. Available functions can be found here.

Note: Users can write to a pre-made global variable API_RETURN_DATA and this will return back from the SkyCiv API. This allows you to return data you need from your operations.

Sample input for S3D.model.script

    const custom_script = `
        //splits members by intersecting nodes
        S3D.structure.members.intersect({ 
        "typ": "intersectingMembers",
        "memberNo": 343
        });

        //node already exists here, so will return existing node ID
        var new_node_id = S3D.structure.nodes.add({ 
        x: 32,
        y: 36,
        z: 104
        });

        var new_node_id2 = S3D.structure.nodes.add({ 
        x: 32,
        y: 0,
        z: 0
        });

        S3D.structure.supports.add({
        node_id:2, 
        fixity:"FFFFFR"
        });

        S3D.structure.members.add({
        nodeA: new_node_id,
        nodeB: new_node_id2,
        section_id: 1,
        type: "continuous", //normal, rigid, tension, compression, cable
        fixityA: "FFFFFF",
        fixityB: "FFFFFF",
        offsetsA: "0,0,0",
        offsetsB: "0,0,0",
        });

        S3D.UI.update({redraw:true});

        API_RETURN_DATA = {
            new_nodes_created: [new_node_id, new_node_id2],
            last_member_added: last_member_added,
            notes: "Nodes were added, supports were aded and then we joined them with a member!"
        };
    `;

    const functions = [
        {
            function: 'S3D.session.start',
            arguments: {
                keep_open: false,
            },
        },
        {
            function: 'S3D.model.set',
            arguments: {
                s3d_model: MODEL_OBJECT,
            },
        },
        {
            function: 'S3D.model.script',
            arguments: {
                script: custom_script,
            },
        }
    ];

The response will return the following message, as well as data you set to API_RETURN_DATA

Sample response for S3D.model.script

    {
        "status": 0,
        "msg": "Custom script ran successfully",
        "data": {
            "new_nodes_created": [
                121,
                2
            ],
            "last_member_added": 9,
            "notes": "Nodes were added, supports were aded and then we joined them with a member!"
        },
        "function": "S3D.model.script"
    }

`S3D.model.getLocalAxisVectors`#

Returns the local axis vectors for each member.

Sample input for S3D.model.getLocalAxisVectors

{
    "function": "S3D.model.getLocalAxisVectors",
    "arguments": {}
}

Sample response for S3D.model.getLocalAxisVectors

{
    "response": {
        "data": {
            "members": {
                "1": { "x": [0, 1, 0], "y": [-1, 0, 0], "z": [0, 0, 1] },
                "2": { "x": [1, 0, 0], "y": [0, 1, 0], "z": [0, 0, 1] },
                "3": { "x": [0, -1, 0], "y": [1, 0, 0], "z": [0, 0, 1] },
                "4": { "x": [0, 1, 0], "y": [-1, 0, 0], "z": [0, 0, 1] },
                "5": { "x": [1, 0, 0], "y": [0, 1, 0], "z": [0, 0, 1] },
                "6": { "x": [0, -1, 0], "y": [1, 0, 0], "z": [0, 0, 1] },
                "7": { "x": [0, 0, 1], "y": [0, 1, 0], "z": [-1, 0, 0] },
                "8": { "x": [0, 0, 1], "y": [0, 1, 0], "z": [-1, 0, 0] }
            },
            "meshed_plates": {},
            "plates": {}
        },
        "msg": "Successfully computed local axes vectors.",
        "status": 0,
        "function": "S3D.model.getLocalAxisVectors",
        "last_session_id": "S7MtXyVMtX0SPCGFkfOyj4eHqWEKwSy71dRwwN7WSCTSeAcS5pGIXgS4KqeIG1gF_0"
    }
}

note

S3D.model.set#

S3D.model.get#

important

S3D.model.repair#

important

checks#

S3D.model.solve#

tip

S3D.model.takeScreenshot#

important

Input for wireframe_settings#

note

S3D.model.mesh#

S3D.model.script#

S3D.model.getLocalAxisVectors#

`S3D.model.set`#

`S3D.model.get`#

`S3D.model.repair`#

`checks`#

`S3D.model.solve`#

`S3D.model.takeScreenshot`#

Input for `wireframe_settings`#

`S3D.model.mesh`#

`S3D.model.script`#

`S3D.model.getLocalAxisVectors`#