S3D.grouping

---

This library provides methods to retrieve particular model elements based on certain criteria.

All grouping code snippets within use the model pictured below.

---

Nodes

byExtremes

Description: Get all nodes at the specified extreme of the model.

Operation Type: Synchronous

Params: S3D.grouping.nodes.byExtremes(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
direction	string	+x, -x, +y, -y, +z, -z.	Direction of the extreme to get.
unfiltered_ids	[integer]	An array of Node IDs.	If omitted, all nodes in the structure will be checked.
tol	float	Any normal number.	If the tolerance is 1, and the model length units are in ft, then any nodes within 1ft of the extreme are returned. Defaults to 1e-6.

Sample:

byNodeExtremes.js

const model = S3D.structure.get();

const xExtremeNodes = S3D.grouping.nodes.byExtremes({

structure: model,

direction: '+x',

tol: 0.01,

});

const zxExtremeNodes = S3D.grouping.nodes.byExtremes({

structure: model,

direction: '+z',

unfiltered_ids: xExtremeNodes,

});

// xExtremeNodes: [3, 4, 7, 8]

// zxExtremeNodes: [3, 4]

byMemberProp

Description: Get all nodes that are attached to members that have the specified attribute.

Operation Type: Synchronous

Params: S3D.grouping.nodes.byMemberProp(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
prop	string	A member property.	The member property to check.
value	Any	Any value.	The value that the member property should be.
unfiltered_ids	[integer]	An array of member IDs.	Only return members if their ID is included in this array.

Sample:

byMemberProp.js

const structure = S3D.structure.get();

S3D.grouping.nodes.byMemberProp({

structure,

prop: 'type',

value: 'cable',

});

// [9, 2, 3, 5, 7]

byMember

Description: Get all nodes that are attached to specified members.

Operation Type: Synchronous

Params: S3D.grouping.nodes.byMember(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
member_ids	[integer]	An array of member IDs.	Get the node IDs of these members.
unfiltered_ids	[integer]	An array of node IDs.	Only return node IDs if their ID is included in this array.

Sample:

const structure = S3D.structure.get();

S3D.grouping.nodes.byMember({

structure,

member_ids: [3, 9],

});

// [3, 4, 7]

---

Members

byNodes

Description: Get all members that are attached to any of the given nodes.

Operation Type: Synchronous

Params: S3D.grouping.members.byNodes(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
node_ids	[integer]	An array of node IDs.	If the member uses one of these nodes, it will be included.
unfiltered_ids	[integer]	An array of member IDs.	Only return members if their ID is included in this array.

Sample:

const model = S3D.structure.get();

// Get all members attached to node 4.

S3D.grouping.members.byNodes({

structure: model,

node_ids: [4],

unfiltered_ids: null,

});

// [3, 8, 12]

// Get all members attached to either nodes 4 or 8.

S3D.grouping.members.byNodes({

structure: model,

node_ids: [4, 8],

unfiltered_ids: null,

});

// [3, 8, 12, 7, 11]

// Only get member 12 if it is attached to nodes 4 or 8.

S3D.grouping.members.byNodes({

structure: model,

node_ids: [4, 8],

unfiltered_ids: [12],

});

// [12]

bySecName

Description: Get all members that have the given section name.

Operation Type: Synchronous

Params: S3D.grouping.members.bySecName(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
section	string	The section name.	All members using this section name will be returned.
unfiltered_ids	[integer]	An array of member IDs.	Only return members if their ID is included in this array.

Sample:

const model = S3D.structure.get();

// Get all members with the section name "HSS3-1/2x1-1/2x1/8".

S3D.grouping.members.bySecName({

structure: model,

section: 'HSS3-1/2x1-1/2x1/8',

});

// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

// Get all members with the section name "0 x 0".

S3D.grouping.members.bySecName({

structure: model,

section: '0 x 0',

});

// [13, 14, 15, 16]

// Get members 5, 6 and 14 if the use the section name "HSS3-1/2x1-1/2x1/8".

S3D.grouping.members.bySecName({

structure: model,

section: 'HSS3-1/2x1-1/2x1/8',

unfiltered_ids: [5, 6, 14],

});

// [5, 6]

byVector

Description: Get all members that conform to a specified vector.

Operation Type: Synchronous

Params: S3D.grouping.members.byVector(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
vector	[float]	An X,Y and Z value to define a vector.	All members using this section name will be returned.
unfiltered_ids	[integer]	Only return members if their ID is included in this array.
tol	float	A float representing degrees.	If the angle between the vector and any member is below or equal to this value, it will be returned. Defaults to 1e-6

Sample:

const model = S3D.structure.get();

// Get all members that extend in the X direction.

S3D.grouping.members.byVector({

structure: model,

unfiltered_ids: null,

vector: [1, 0, 0],

});

// [2, 6, 11, 12]

// To get the inclined member 13.

// Node 2 coords are: [0, 0.9, 0].

// Node 9 coords are: [1.15, 3, -0.95].

S3D.grouping.members.byVector({

structure: model,

unfiltered_ids: null,

vector: [1.15, 2.1, -0.95],

});

// [13]

byExtremes

Description: Get all members at the specified extreme of the model.

Operation Type: Synchronous

Params: S3D.grouping.members.byExtremes(Object)

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
direction	string	+x, -x, +y, -y, +z, -z.	Direction of the extreme to get.
unfiltered_ids	[integer]	An array of Node IDs.	Only return members in this array. If omitted, all members in the structure will be checked.
both_nodes_on_extreme	boolean	true, false	If both of the member's nodes should be on the extreme. Defaults to false.
tol	float	Any normal number.	If the tolerance is 1, and the model length units are in ft, then any members within 1ft of the extreme are returned. Defaults to 1e-6.

Sample:

const structure = S3D.structure.get();

// Any members that touch the extreme tolerance

S3D.grouping.members.byExtremes({

structure,

direction: '-x',

});

// [1, 2, 4, 5, 6, 10, 11, 12, 13, 15]

// Only members that have both ends within the extreme tolerance

S3D.grouping.members.byExtremes({

structure,

direction: '-x',

both_nodes_on_extreme: true,

});

// [1, 4, 5, 10]

// Member 12 is 2.3ft so a tolerance of 2ft will get members 13 and 15 too.

S3D.grouping.members.byExtremes({

structure,

direction: '-x',

both_nodes_on_extreme: true,

tol: 2,

});

// [1, 4, 5, 10, 13, 15]

---

General

byAttr

Description: Get all elements that have the specified attribute.

Operation Type: Synchronous

Params: S3D.grouping.general.byAttr(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
key	string	Any key inside the iterable objects.	The key to check of each object in the type array.
value	Any	Any value.	The value to match to the key defined above.

Sample:

const model = S3D.structure.get();

// Get all members that have a "type" attribute equal to cable.

S3D.grouping.general.byAttr({

structure: model,

unfiltered_ids: null,

type: 'elements',

key: 'type',

value: 'cable',

});

// [13, 14, 15, 16]

byBounds

Description: Get all elements inside a 2D plane. Polygon can be convex or concave. By default it is assumed convex unless specified otherwise. If convex then extra processing is required to triangulate the polygon.

Operation Type: Synchronous

Params: S3D.grouping.general.byBounds(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
node_ids	[integer]	Nodes IDs to define a 2D polygon.	The key to check of each object in the type array.
tol	float	Any normal number.	The tolerance to include members outside the polygon.
concave	boolean	true or false.	Whether the polygon is concave or convex. Defaults true.

Sample:

const model = S3D.structure.get();

// Get all members inside the 2D triangular polygon defined by nodes 1, 4 and 6.

S3D.grouping.general.byBounds({

structure: model,

unfiltered_ids: null,

type: 'elements',

node_ids: [1, 4, 6],

tol: null,

concave: true,

});

// [10, 12]

byCoord

Description: Get all elements that use a node that has a location that meets the specified criteria.

Operation Type: Synchronous

Params: S3D.grouping.general.byCoord(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
comparison	string	less than, equals to, greater than.	The type of comparison to use when checking a node.
plane	string	x, y or z.	The plane which to compare in.
value	float	Any float.	The coordinate to use in the comparison.

Sample:

const model = S3D.structure.get();

// Get all members that contain a node that has an x coordinate less than 1.

S3D.grouping.general.byCoord({

structure: model,

unfiltered_ids: null,

type: 'elements',

comparison: 'less than',

plane: 'x',

value: 1,

});

// [1, 2, 4, 5, 6, 10, 11, 12, 13, 15]

S3D.grouping.general.byCoord({

structure: model,

unfiltered_ids: null,

type: 'elements',

comparison: 'greater than',

plane: 'y',

value: 1,

});

// [13, 14, 15, 16]

byMaterial

Description: Get all members that have the given material name.

Operation Type: Synchronous

Params: S3D.grouping.general.byMaterial(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
material_name	string	The material name.	All elements using this material will be returned.

Sample:

const model = S3D.structure.get();

// Get all members that use the material named "cable material".

S3D.grouping.general.byMaterial({

structure: model,

unfiltered_ids: null,

type: 'elements',

material_name: 'cable material',

});

// [13, 14, 15, 16]

byPlane

Description: Get all elements that are in the specified plane.

Operation Type: Synchronous

Params: S3D.grouping.general.byPlane(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
node_ids	[integer]	Three node IDs that define a plane.	If an element lies in this plane it will be returned.

Sample:

const model = S3D.structure.get();

// Get all members that lie in the plane defined by nodes 1, 4, 6.

S3D.grouping.general.byPlane({

structure: model,

unfiltered_ids: null,

type: 'members',

node_ids: [1, 4, 6],

});

// [8, 10, 11, 12]

byPlaneDetailed

Description: An extension of the byPlane method which returns the element IDs and the perpendicular vector.

Operation Type: Synchronous

Params: S3D.grouping.general.byPlaneDetailed(Object)

Object properties:

Key	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
unfiltered_ids	[integer]	An array of element IDs.	Only return elements if their ID is included in this array.
type	string	nodes, members, materials, supports, etc.	The child array of the structure object to search.
node_ids	[integer]	Three node IDs that define a plane.	If an element lies in this plane it will be returned.

Sample:

const model = S3D.structure.get();

// Get all members that lie in the plane defined

// by nodes 1, 4, 6 and the perpendicular vector.

S3D.grouping.general.byPlaneDetailed({

structure: model,

unfiltered_ids: null,

type: 'members',

node_ids: [1, 4, 6],

});

/*

{

"ids": [8, 10, 11, 12],

"perp_vec": [0, 1, 0]

}

*/

Auto Grouping

members

Description: Members can be automatically grouped by similar attributes. The method takes two parameters - the first parameter is the structure object and the second is a settings object.

Operation Type: Synchronous

Params: S3D.grouping.autoGrouping.members(Object)

Parameters	Type	Accepts	Description
structure	Object	The structure object.	This can be obtained via S3D.structure.get().
settings	Object	An object of key value pairs. See example below.	Attributes to group by.

Sample input:

S3D.grouping.autoGrouping.members(model, {

material: false,

direction: false,

length: true,

section: false,

auto_update: true,

group_single_member: false,

});

Sample output:

{

criterias: [

{length: "0.90" },

null,

{ length: "2.30" },

{ length: "1.90" },

{ length: "2.58" }],

groups: [

{ name: "", IDs: [1, 3, 5, 7], type: "Members" },

null,

{ name: "", IDs: [2, 6, 11, 12], type: "Members" },

{ name: "", IDs: [4, 8, 9, 10], type: "Members" },

{ name: "", IDs: [13, 14, 15, 16], type: "Members" },

],

};