pw:: Framework

Framework type

Derives From

pw::Object

Summary

pw:: Framework	Framework type
Static Actions
getRoot	This action returns the root (global) framework system.
hasFrameworks	This action returns true if multiple frameworks are present.
get	This action returns the framework specified by the name-based path.
find	This action returns a path to an instance of the framework.
setActive	This action specifies the active framework.
getActive	This action returns the full path to the active framework as a list of pw::Framework objects.
getRootToTailTransform	This action returns a transformation matrix which will convert a point in the coordinate system of the framework specified by the root of the path to the coordinate system of the framework specified as the tail of the path.
getTailToRootTransform	This action returns a transformation matrix which will convert a point in the coordinate system of the framework specified by the tail of the path to the coordinate system of the framework specified as the root of the path.
convertPoint	This action transforms a point from one framework coordinate system to another framework coordinate system.
convertDirection	This action transforms a direction from one framework coordinate system to another framework coordinate system.
convertNormal	This action transforms a normal vector from one framework coordinate system to another framework coordinate system.
computeTransform	This action computes the transform from one framework coordinate system to another.
export	This action exports one or more frameworks.
isValidPath	This action tests to see if a framework path argument is valid.
Instance Attributes
Enabled	This attribute controls whether or not the framework is displayed when it is not the active framework.
InactiveTransparency	This attribute controls how transparent its entities are drawn when the framework is not the active framework.
Transform	This attribute is the transform of the framework system.
Instance Actions
delete	This action deletes this framework system, any framework systems attached to it as children, and any entities contained in the deleted framework systems.
Name	This attribute is the name of the framework system.
createChild	This action creates a new pw::Framework object and adds it as a child.
addChild	This action adds a child pw::Framework object to the framework.
removeChild	This action removes a child pw::Framework object from the framework.
reorderChild	This action reorders a child pw::Framework of the framework.
reparent	This action removes the framework from one parent, a pw::Framework object, to another parent, also a pw::Framework object.
insertParent	This action inserts a new pw::Framework object between this framework and the specified child.
getChildCount	This action returns the number of framework children for this framework.
getChild	This action returns a pw::Framework object.
hasChild	This action returns the true if the framework directly contains the specified child framework.
isolateChild	This action replaces the local instance of a multiply-instanced framework with a non-shared copy.
flattenChild	This action moves the entities in the child or at the tail of the specified path to this framework, transforming them from the child space to the parent space.
getInstanceCount	This action returns the number of times the framework is instanced (i.e., a child of another framework).
getPathCount	This action returns the number of times the framework and the specified child is referenced by a permanent framework path (such as grid entities referencing sources).
getAttachmentPointCount	This action returns the number of attachment points the framework contains.
getAttachmentPoint	This action returns various values associated with an attachment point of a framework.
addAttachmentPoint	This action adds an attachment point to a framework.
modifyAttachmentPoint	This action modifies an existing attachment point of a framework.
removeAttachmentPoint	This action removes the attachment point specified either by index or name.
clearAttachmentPoints	This action removes all the attachment points from a framework
attach	This action transforms the framework such that the parent attachment point and the child attachment point line up in the global transform space.
computeAttachTransform	This action computes the transform for the framework such that, if applied, would line up the parent attachment point and the child attachment point in the global transform space.

find

pw::Framework find < ?-root head? target | -next path >

This action returns a path to an instance of the framework.

Parameters

-next path	This parameter specifies a previous path to use as a starting point for the search. This action will find the next occurence of the framework after this path. The target framework is the tail of the specified path. The root of the search is given by the head of the specified path. An error is raised if the path is invalid.
-root head	If this option is missing, the search is performed relative to the root of the framework hierarchy (unless the -next option is specified). If an alternate root is specified, then the returned path will be relative to this root framework.
target	If a path is not specified with the -next option, this specifies the pw::Framework object to locate. The action will return the first occurrence of the given framework in the framework hierarchy.

Returns

This action returns a list pw::Framework objects representing a path from the root framework (the first entry in the list) to the target framework (the last entry in the list). An empty list is returned if the target could not be found.

convertPoint

pw::Framework convertPoint ?-from path? ?-to path? < point | coord >

This action transforms a point from one framework coordinate system to another framework coordinate system.

Parameters

-from path	This specifies the framework path from which the transformation will be computed. If not specified, or if the specified path is empty, the active framework is used.
-to path	This specifies the framework path into which the transform will be computed. If not specified, or if the specified path is empty, the active framework is used.
point	This parameter is a point.
coord	This parameter is a grid coord.

Note

A path argument must be a list of either pw::Framework objects or framework names. The path must start at the root framework, start at the active framework, or start at a child of the active framework. If both a ‘from’ and a ‘to’ path are specified, then it is also permissible for the two paths to share the same starting framework (regardless of whether it is the root or active framework).

Returns

This action returns an XYZ value vector representing the transformed point.

convertDirection

pw::Framework convertDirection ?-from path? ?-to path? direction

This action transforms a direction from one framework coordinate system to another framework coordinate system.

Parameters

-from path	This specifies the framework path from which the transformation will be computed. If not specified, or if the specified path is empty, the active framework is used.
-to path	This specifies the framework path into which the transform will be computed. If not specified, or if the specified path is empty, the active framework is used.
direction	This parameter is a vector representing the direction to be transformed.

Note

This differs from the pw::Framework.convertPoint routine in how the XYZ value is prepared for use with the 4x4 transform matrix. For a point value, the fourth value of the point vector is set to 1. This allows it to pick up the translation values in the transform. For a direction, the fourth value of the XYZ vector is set to 0. One way to think about this is to consider a direction as the difference between two points. The transformed direction should be the difference between the transformed points. If the transform is given by M, the direction as D and the points as P1 and P2, then

M * P2

M * P1 = M * (P2 - P1) = M * D

Given that P1 and P2 both have 1 as the fourth value, the fourth value for the direction should be 0.

Returns

This action returns an XYZ value vector representing the transformed direction.

convertNormal

pw::Framework convertNormal ?-from path? ?-to path? normal

This action transforms a normal vector from one framework coordinate system to another framework coordinate system.

Parameters

-from path	This specifies the framework path from which the transformation will be computed. If not specified, or if the specified path is empty, the active framework is used.
-to path	This specifies the framework path into which the transform will be computed. If not specified, or if the specified path is empty, the active framework is used.
normal	This parameter is a vector representing a normal vector.

Note

Normal vectors are transformed by the transposed inverse of the transformation matrix/

Returns

This action returns an XYZ value vector representing the transformed normal. The result will be normalized.

computeTransform

pw::Framework computeTransform ?-from path? ?-to path?

This action computes the transform from one framework coordinate system to another.

Parameters

-from path	This specifies the framework path from which the transformation will be computed. If not specified, or if the specified path is empty, the active framework is used.
-to path	This specifies the framework path into which the transform will be computed. If not specified, or if the specified path is empty, the active framework is used.

Note

Returns

This action returns a pwu::Transform value representing the transformation matrix.

export

pw::Framework export ?-compress level? filename framework_path_list

This action exports one or more frameworks.

Parameters

-compress	This specifies the compression level to use for the file. The value should be an integer number in the range [0,9]. The default value of 0 indicates no compression, while the maximum level of compression is specified by a value of 9.
filename	This specifies the name of file to be exported.
frameworks	This specifies the list of framework paths to be exported. Each entry in the list should either be a unique framework (only one instance) or the full path to the particular instance of the framework to be exported. All frameworks below the named frameworks will also be exported.

Notes

A path argument must be a list of either pw::Framework objects or framework names. The path must start at the root framework.

If more than one framework is specified and they are not in the same branch, they will be exported as direct children of an empty temporary root framework. For example, if the list of frameworks to export was “root a b c” and “root d e”, the frameworks “c” and “e” would be exported as “temp_root c” and “temp_root e”. Any transforms by “a”, “b”, or “d” will be ignored. In this way, they would be later imported under a single framework.

In the rare case where the frameworks to be placed under the “temp_root” have the same name, an additional framework will be inserted between the temporary root and each exported framework so the names can be preserved. For example, if the list of frameworks to export was “root a b c” and “root d e c”, the frameworks “c” and “c” (which may or may not be instances of the same framework) would be exported as “temp_root framework-1 c” and “temp_root framework-2 c”.

No overset data is included in the export.

Because the framework hierarchy may be different, the default view and saved views may not be the same when reading in the exported framework subset.

Returns

This action returns no value.

InactiveTransparency

$framework get/setInactiveTransparency ?-instance path? ?-all? value

This attribute controls how transparent its entities are drawn when the framework is not the active framework.

Parameters

-instance	This optional argument expects a path to an instance of this framework. The transparency is only for that particular instance. If this option is not specified, the transparency sets or retrieves the default for future instances of the framework.
-all	This optional flag specifies that the transparency should be applied to all instances of the framework as well as become the default for future instance. This option is only available when setting the transparency.

Type

This attribute is a float value between 0.0 (fully opaque) and 1.0 (fully transparent).

Default

The default for this attribute is 0.5.

reparent

$child reparent ?-path instance? source_parent destination_parent

This action removes the framework from one parent, a pw::Framework object, to another parent, also a pw::Framework object.

Parameters

-path	This optional argument specifies a specific instance of the child to be copied. This only matters if the framework being moved is instanced multiple times and has cut planes and/or a modified transparency setting. The path specified should be a full path from the root framework to the source parent framework. The transparency value and cut planes from that instance will be applied to the new instances created.
source_parent	This argument specifies the pw::Framework object that is currently a parent of the framework.
destination_parent	This argument provides the pw::Framework object that is to become the new parent of the framework.

Notes

If the child framework is instanced multiple times and is referenced by permanent framework paths (such as those used by voxel blocks to track enclosing entities or various grid entities to track sources), then reparenting will be prohibited. Updating the paths is ambiguous in such cases.

A framework in the active framework path cannot be reparented.

Framework transparency settings and cut planes are assigned per instance of a framework. Reparenting a framework destroys the old instance and creates a new instance. If the framework is multiply instanced and an instance path is specified, or if there is only one instance of the framework, then the transparency and cut planes will be copied over to the new instance (or instances if the destination is itself multiply-instanced). Otherwise, any transparency settings or cut planes will be lost.

Returns

This action returns an index of the reparented framework in the range [1, N], where N is the number of children in destination_parent.

flattenChild

$parent flattenChild < index | child | relative_path >

This action moves the entities in the child or at the tail of the specified path to this framework, transforming them from the child space to the parent space. After moving the entities, the source framework will be removed from its parent if it has no child frameworks. The path will continue to be culled up to the parent until a framework with entities or other framework children is encountered. This command will fail if any framework along the specified path is multiply instanced. Such frameworks must be isolated first (otherwise all instances would be affected).

Parameters

index	This parameter specifies the index of the child to flatten in the range [1, N], where N is the number of children the framework has.
child	This parameter specifies the child to be flattened.
relative_path	This parameter specifies a path based with the current framework and ending with the framework to be flattened. The path can start with this framework or with an immediate child of this framework.

Returns

This action returns nothing.

getAttachmentPoint

$framework getAttachmentPoint ?< -name | -location | -up | -forward>? < index | name >

This action returns various values associated with an attachment point of a framework.

Parameters

index	This parameter specifies which attachment point is being queried. The value should be an integer with the range [1, number of attachment points].
name	The parameter specifies the attachment point to query by name. The value should be a string.
-name	If this option is present, the name of the attachment point is returned. The return value will be a string.
-location	If this option is present, the location of the attachment point is returned. When two frameworks are transformed such that two of their attachment points are connected, the location points will be identical in the global transform space. The return value will be a vector.
-up	If this option is specified, the “up” direction of the attachment point is returned. When two frameworks are transformed such that two of their attachment points are connected, their up direction vectors will be opposite each other in the global transform space. The return value will be a vector.
-forward	If this option is specified, the “forward” direction of the attachment point is returned. When two frameworks are transformed such that two of their attachment points are connected, their forward direction vectors will be identical in the global transform space. The return value will be a vector.
none	If no options are specified, the result will be a list containing the name, the location vector, the up direction vector, and the forward direction vector.

Returns

This action returns varying values based on which optional parameter is specified. See the list of paremeters above.

addAttachmentPoint

$framework addAttachmentPoint ?-name name? location up forward

This action adds an attachment point to a framework.

Parameters

-name name	This optional argument specifies the name of the attachment point. The name will be modified if there is another attachment point with the same name or same root name. For example, if name is specified as “ap” and there is already an attachment point with the name “ap-1”, the new attachment point will be named “ap-2”. Similarly, if there had already been an attachment point with the name “ap”, the new attachment point will be named “ap-2”. Since other commands allow the attachment point to be referenced by name or index, the name cannot be an integer number.
location	This vector argument specifies the location of the attachment point. When used to connect to another attachment point, this point will be identical to the location of the other attachment point in the global transform space.
up	This vector argument provides the “up” direction of the attachment point. When two frameworks are transformed such that two of their attachment points are connected, their up direction vectors will be opposite each other in the global transform space.
forward	This vector argument specifies the “forward” direction of the attachment point. When two frameworks are transformed such that two of their attachment points are connected, their forward direction vectors will be identical in the global transform space.

Returns

This action returns an unsigned integer representing the index of the newly added attachment point. Note that the index can change over time if earlier attachment points are removed.

modifyAttachmentPoint

$framework modifyAttachmentPoint <name | index> ?-name new_name? ?-location location? ?-up up_direction? ?-forward forward_direction?

This action modifies an existing attachment point of a framework.

Parameters

index	This integer value identifies which attachment point will be modified. The valid range is [1, number of attachment points].
name	This string value identifies the attachment point by name.
-name new_name	This optional argument specifies that the name of the attachment point should be changed. The actual name will be modified if there is another attachment point with the same name or same root name. For example, if new_name is specified as “ap” and there is already an attachment point with the name “ap-1”, the attachment point will be named “ap-2”. Similarly, if there had already been an attachment point with the name “ap”, the attachment point will be named “ap-2”. Since other commands allow the attachment point to be referenced by name or index, the new_name cannot be an integer number.
-location location	If specified, the vector argument specifies changes the location of the attachment point.
-up up_direction	If specified, this vector argument provides the “up” direction of the attachment point. The forward direction may be modified to make it orthogonal to the up direction. If both the “up” and “forward” directions are specified and are not orthogonal, the “up” direction takes precedence.
-forward forward_direction	This optional flag speciies that the vector argument replaces the “forward” direction of the attachment point. The “forward” direction will be modified if needed to make it orthogonal to the “up” direction.

Returns

This action returns an unsigned integer representing the index of the newly added attachment point. Note that the index can change over time if earlier attachment points are removed.

attach

$parent attach parent_path parent_attachment_point child_path child_attachment_point

This action transforms the framework such that the parent attachment point and the child attachment point line up in the global transform space. The parent attachment point must be in a framework that is not a child of any instance of this framework. The child attachment point must be an attachment point on this framework or a framework that is an instance of this framework. After the transformation, the location points will be identical in the global transform space, the up directions will be opposite, and the forward directions will be identical.

Parameters

parent_path	This argument describes the path to the framework containing the parent attachment point as a list of frameworks. The framework path is a list of the framework names describing the path from the root to the framework containing the target attachment point. The framework path must be an absolute path and cannot include this framework.
parent_attachment_point	This argument identifies the parent attachment point on the framework given by the parent_path argument. The attachment point can be identified either by name or index.
child_path	This argument describes the path to the framework containing the child attachment point. The path is specified as a list of frameworks names. The path must be an absolute path containing this framework. This path must point to either this framework or a framework instance that is a child (directly or indirectly) of this framework.
child_attachment_point	This argument identifies the child attachment point on the framework given by the child_path argument. The attachment point can be identified either by name or index.

Returns

This action returns nothing.

computeAttachTransform

$parent computeAttachTransform parent_path parent_attachment_point child_path child_attachment_point

This action computes the transform for the framework such that, if applied, would line up the parent attachment point and the child attachment point in the global transform space. The parent attachment point must be in a framework that is not a child of any instance of this framework. The child attachment point must be an attachment point on this framework or a framework that is an instance of this framework. After the transformation, the location points will be identical in the global transform space, the up directions will be opposite, and the forward directions will be identical.

Parameters

parent_path	This argument describes the path to the framework containing the parent attachment point as a list of frameworks. The framework path is a list of the framework names describing the path from the root to the framework containing the target attachment point. The framework path must be an absolute path and cannot include this framework.
parent_attachment_point	This argument identifies the parent attachment point on the framework given by the parent_path argument. The attachment point can be identified either by name or index.
child_path	This argument describes the path to the framework containing the child attachment point. The path is specified as a list of frameworks names. The path must be an absolute path containing this framework. This path must point to either this framework or a framework instance that is a child (directly or indirectly) of this framework.
child_attachment_point	This argument identifies the child attachment point on the framework given by the child_path argument. The attachment point can be identified either by name or index.

Returns

This action returns the pwu::Transform that would align the two attachment points.

pw:: Framework

Derives From

Static Actions

getRoot

Parameters

Returns

hasFrameworks

Parameters

Returns

get

Parameters

Returns

find

Parameters

Returns

setActive

Parameters

Returns

getActive

Parameters

Returns

getRootToTailTransform

Parameters

Returns

getTailToRootTransform

Parameters

Returns

convertPoint

Parameters

Note

Returns

convertDirection

Parameters

Note

Returns

convertNormal

Parameters

Note

Returns

computeTransform

Parameters

Note

Returns

export

Parameters

Notes

Returns

isValidPath

Parameters

Returns

Instance Attributes

Enabled

Parameters

Type

Default

InactiveTransparency

Parameters

Type

Default

Transform

Type

Default

Instance Actions

delete

Parameters

Note

Returns

Name

Type

Note

Default

createChild

Parameters

Returns

addChild

Parameters

Returns

removeChild

Parameters

Returns