CmUtils::Objects::NodeGroup

The NodeGroup class defines structures and methods for creating and manipulating groups of nodes. The NodeGroup structure has 4 fields:

NAME
Name of the NodeGroup
FOCUS
Value of the focus for NodeGroups based on prolate-spheroidal coordinates
FIELDSETS
A set of FieldSets which describe the Nodes in this NodeGroup
NODES
The set of nodes belonging to this NodeGroup

VERSION

0.6 (7 September 2001)

CHANGES

0.6 GBS: Added distance method to compute distance between two nodes.

METHODS

new()

Returns a new NodeGroup.

name([string/number])

Optional argument is name for NodeGroup. Returns the name of the NodeGroup.

property(name,[value])

Sets a problem-specific/dependent property (named NAME) of the NodeGroup. Optional argument is the value of the property. Returns the value.

getPropertyNames([Name(s)])

Returns the sorted names of all (or NAMED) Properties defined for a NodeGroup.

addFieldSet(FieldSet)

Adds a FieldSet to the list of FieldSets of this NodeGroup. Returns the index of the last FieldSet.

getFieldSets()

Returns the list of defined FieldSets.

getFieldSet(number)

Returns a specific FieldSet by number. FieldSets do not have names :-(

getAllFieldNames([FieldSet(s)])

Returns the sorted names of all Fields in DEFINED or, by default, ALL FieldSets of a NodeGroup.

addNode(Node)

Adds a Node to the list of Nodes in the NodeGroup. Node will NOT be added (replaced) if it already exists. Returns the total number of defined Nodes in the NodeGroup.

addNodes(Node(s))

Adds one or more Nodes to the list of Nodes in the NodeGroup. Nodes will NOT be added (replaced) if they already exist. Returns the total number of defined Nodes in the NodeGroup.

updateNode(Node)

Updates the Node in the NodeGroup. Node will NOT be changed unless it already exists. Returns the total number of defined Nodes in the NodeGroup.

deleteNode(NodeName)

Deletes Node named NodeName in the NodeGroup. Returns the total number of defined Nodes in the NodeGroup.

deleteNodes(NodeName(s))

Deletes one or more Nodes named NodeName(s) in the NodeGroup. Returns the total number of defined Nodes in the NodeGroup.

isNode(NodeName)

Returns True if the Node named NodeName is in the NodeGroup, otherwise returns False.

getNodeNames([NodeName(s)])

If NodeName(s) are specified, returns a list of names of all Nodes with these names that exist in the NodeGroup, in the order they are specified. If no argument is given, returns a list of names of ALL Nodes, sorted in numerical/alphabetical order.

getNodes([NodeName(s)])

If NodeName(s) are specified, returns a list of all Nodes with these names that exist in the NodeGroup, in the order they are specified. If no argument is given, returns a list of ALL Nodes, sorted in numerical/alphabetical order.

getNodesByFieldSet([NodeName(s)])

If NodeName(s) are specified, returns a list of all Nodes with these names that exist in the NodeGroup. If no argument is given, returns a list of ALL Nodes. Returned Nodes are sorted by FieldSet, then by name (numerically/alphabetically).

getNode(NodeName)

Returns the Node named NodeName from the NodeGroup.

numberOfNodes()

Returns the number of Nodes defined in the NodeGroup.

maximumNodeNumber()

Returns the number of Nodes defined in the NodeGroup.

listFields([FH])

List the Field information of this NodeGroup to the filehandle FH (default to STDOUT). Set the "verbose" flag ($s->verbose(1)) to see extended information.

listNodes([FH])

List the Node information of this NodeGroup to the filehandle FH (default to STDOUT). Set the "verbose" flag ($s->verbose(1)) to see extended information.

mergeGroup(Group[,Options])

Merges another Group into this NodeGroup. By default, nodes are added as long as they do not already exist. The Options hashref can alter this by either forcing an overwrite of existing nodes (key "overwrite"), or assigning a new number to the new nodes (key "newnumber").

  $options{newnumber} = 1;
  $group->mergeGroup($another_group,$options);

Transformation METHODS

The following routines define useful transformations of existing NodeGroups. By default each routine processes the whole NodeGroup, but a list of NodeNames may be specified to restrict processing to just a portion of it. NodeNames can be specified as either an array or a list, and are always the last argument(s) to the method call.

Where operations apply to coordinate values, they are restricted to fields matching /coordinate/i with components matching /[xyz]/i.

reduce(Factor[,NodeName(s)])

Deletes nodes so that only 1/Factor of the original number remain. For example:

  $group->reduce(2);

keeps only every other node. Useful for subsampling a dataset.

renumber([Offset[,Increment[,NodeNames]]])

Renumbers the NodeGroup starting from Offset (default 1) by an Increment (default 1).

Note: Nodes may be lost if a portion of the group is renumbered to the same as other existing nodes.

offset_number([Offset[,NodeNames]])

Renumbers the NodeGroup by adding Offset to each node number.

Note: Nodes may be lost if a portion of the group is renumbered to the same as other existing nodes.

translate(Translation[,NodeName(s)])

Translates nodal x/y/z coordinates by Translation. The translation may be specified by either: * a hashref, with keys of one or more of x,y,z * an arrayref, with values in order of x,y,z * a scalar, where the value applies equally to each direction

  $group->translate({x => 3, z => -7});
  $group->translate([4,5,6]);

setorigin(Origin[,NodeName(s)])

Translates nodal x/y/z coordinates so that Origin is the origin. The origin may be specified by either: * a hashref, with keys of one or more of x,y,z * an arrayref, with values in order of x,y,z

  $group->setorigin([-10,10,5]);

scale(Scale[,NodeName(s)])

Scales nodal x/y/z coordinates by the given Scale. The values to scale by may be specified by either: * a hashref, with keys of one or more of x,y,z * an arrayref, with values in order of x,y,z * a scalar, where the value applies equally to each direction

  $group->scale({x => 5});
  $group->scale(2);

multmatrix4(matrix[,NodeName(s)])

Perform a general transformation on nodal coordinates by multiplying by a standard 16 element transformation Matrix. The matrix must be specified as an arrayref with 16 elements (or a 4x4 array of arrays). The matrix is given row-first.

  $mat = [ 
    [ 1, 0, 0, 5],
    [ 0, 0,-1,10],
    [ 0, 1, 0, 0],
    [ 0, 0, 0, 1] ];
  $group->multmatrix4($mat);

rotateradians(Angles[,NodeName(s)]) rotatedegrees(Angles[,NodeName(s)])

Rotates nodal x/y/z coordinates by the given Angles. The values to rotate by may be specified by either: * a hashref, with keys of one or more of x,y,z * an arrayref, with values in order of x,y,z * a scalar, where the rotation is assumed to be in the x-direction Angles are given in radians or degrees depending on the function called

  $group->rotateradians({z => $pi/2});
  $group->rotatedegrees([45,-30,10]);

Both these routines called the internal routine _rotate which converts the angles to a 4x4 transformation matrix and calls the multmatrix4 routine. CmUtils::RotationTransform is used to do the conversion.

centroid([NodeName(s)])

Computes the centroid of the xyz coordinate components of the NodeGroup.

  @centroid = $group->centroid();

distance(node1, node2)

Computes the distance between two nodes ina nodegroup (assuming xyz coordinates). e.g. nodes 1 and 5:

  $distance = $group->distance(1, 5);