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" },
  ],
};

Nodes#

byExtremes#

byMemberProp#

byMember#

Members#

byNodes#

bySecName#

byVector#

byExtremes#

General#

byAttr#

byBounds#

byCoord#

byMaterial#

byPlane#

byPlaneDetailed#

Auto Grouping#

members#

`byExtremes`#

`byMemberProp`#

`byMember`#

`byNodes`#

`bySecName`#

`byVector`#

`byExtremes`#

`byAttr`#

`byBounds`#

`byCoord`#

`byMaterial`#

`byPlane`#

`byPlaneDetailed`#

`members`#