CIP C++ documentation for class "pfcSolid"

Class pfcSolid

# include <pfcSolid.h> class pfcSolid : public virtual pfcFamilyMember, : public virtual pfcModel { xaideclare(pfcSolid) ... };

Description

This class defines a solid.

Direct Known Subclasses:: pfcAssembly, pfcPart, wfcWSolid

Method Summary


`void`	`ActivateSimpRep (pfcSimpRep_ptr SimpRep)`
	Activates the specified simplified representation.

`pfcUnit_ptr`	`CreateCustomUnit (xrstring Name, pfcUnitConversionFactor_ptr ConversionFactor, pfcUnit_ptr ReferenceUnit)`
	Creates a custom unit based on name, conversion factor and reference unit.

`pfcFeature_ptr`	`CreateFeature (pfcFeatureCreateInstructions_ptr Instructions)`
	Not implemented in the current release. Creates a feature, based on the instructions provided.

`pfcFeature_ptr`	`CreateImportFeat (pfcIntfDataSource_ptr IntfData, optional pfcCoordSystem_ptr CoordSys, optional pfcImportFeatAttr_ptr FeatAttr)`
	Creates a new import feature in the solid (part). Assembly case is not supported.

`pfcFeatureGroup_ptr`	`CreateLocalGroup (pfcFeatures_ptr Members, xrstring Name)`
	Creates a local group out of the specified set of features.

`pfcModelItem_ptr`	`CreateNote (xstringsequence_ptr Lines, optional pfcModelItem_ptr Owner)`


`pfcSimpRep_ptr`	`CreateSimpRep (pfcCreateNewSimpRepInstructions_ptr Instructions)`
	Creates a simplified representation based on the supplied instructions.

`pfcFeatureGroup_ptr`	`CreateUDFGroup (pfcUDFGroupCreateInstructions_ptr Instructions)`
	Creates a FeatureGroup, based on the instructions provided.

`pfcUnitSystem_ptr`	`CreateUnitSystem (xrstring Name, pfcUnitSystemType Type, pfcUnits_ptr Units)`
	Creates a new unit system in the model.

`void`	`DeleteSimpRep (pfcSimpRep_ptr SimpRep)`
	Deletes the specified simplified representation from its owner model.

`pfcOutline3D_ptr`	`EvalOutline (optional pfcTransform3D_ptr Trf, optional pfcModelItemTypes_ptr ExcludeTypes)`
	This method is enabled for Creo Direct. Computes the outline of a solid.

`void`	`ExecuteFeatureOps (pfcFeatureOperations_ptr Ops, optional pfcRegenInstructions_ptr Instrs)`
	Performs the specified feature operations.

`void`	`ExportShrinkwrap (pfcShrinkwrapExportInstructions_ptr Instructions)`
	Exports a solid model to shrinkwrap format.

`optional xreal`	`GetAbsoluteAccuracy ()`
`void`	`SetAbsoluteAccuracy (optional xreal value)`
	This method is enabled for Creo Direct. The absolute accuracy of the solid or `null`, if relative accuracy is used

`pfcSimpRep_ptr`	`GetActiveSimpRep ()`
	Returns the current active simplified representation.

`optional pfcXSection_ptr`	`GetCrossSection (xrstring Name)`
	Returns a cross-section object, given its name.

`optional pfcFeature_ptr`	`GetFeatureById (xint Id)`
	Retrieves the specified feature, given its identifier.

`optional pfcFeature_ptr`	`GetFeatureByName (xrstring Name)`
	Locates the feature object, given its name.

`pfcOutline3D_ptr`	`GetGeomOutline ()`
	This method is enabled for Creo Direct. The outline of the solid with respect to the base coordinate system orientation

`pfcSimpRep_ptr`	`GetGeomRep ()`
	Returns the object representing the solid model's Geometry Rep.

`pfcSimpRep_ptr`	`GetGraphicsRep ()`
	Returns the object representing the solid model's Grpahics Rep.

`xbool`	`GetIsSkeleton ()`
	`true` if the model is a skeleton model, `false` otherwise.

`pfcMassProperty_ptr`	`GetMassProperty (optional xrstring CoordSysName)`
	This method is enabled for Creo Direct. Gets the mass properties for the solid.

`pfcSimpRep_ptr`	`GetMasterRep ()`
	Returns the object representing the solid model's Master Rep.

`pfcUnitSystem_ptr`	`GetPrincipalUnits ()`
	This method is enabled for Creo Direct. Gets the system of units assigned to the solid model.

`optional xreal`	`GetRelativeAccuracy ()`
`void`	`SetRelativeAccuracy (optional xreal value)`
	This method is enabled for Creo Direct. The relative accuracy of the solid or `null`, if absolute accuracy is used

`pfcSimpRep_ptr`	`GetSimpRep (xrstring SimpRepName)`
	Returns the handle to the specified simplified representation.

`optional pfcUnit_ptr`	`GetUnit (xrstring Name, optional xbool ByExpression)`
	Get the handle to a particular unit based on name or expression.

`xbool`	`HasRetrievalErrors ()`
	Identifies if a previous call to retrieve the model resulted in errors.

`optional pfcXSections_ptr`	`ListCrossSections ()`
	Lists the cross-sections in the solid model.

`optional pfcFeatures_ptr`	`ListFailedFeatures ()`
	Retrieves the list of failed features in the part or assembly.

`optional pfcFeatures_ptr`	`ListFeaturesByType (optional xbool VisibleOnly, optional pfcFeatureType Type)`
	Lists the features according to type.

`pfcFeatureGroups_ptr`	`ListGroups ()`
	Collect groups (including UDFs) in the solid.

`pfcUnits_ptr`	`ListUnits (optional pfcUnitType Type)`
	Lists the units available in the model.

`pfcUnitSystems_ptr`	`ListUnitSystems ()`
	Lists the unit systems available in the model.

`void`	`Regenerate (optional pfcRegenInstructions_ptr Instrs)`
	Regenerates the solid.

`pfcSimpRep_ptr`	`SelectSimpRep ()`
	Enables the user to select a simplified representation.

	This method is enabled for Creo Direct.

`void`	`SetPrincipalUnits (pfcUnitSystem_ptr Units, pfcUnitConversionOptions_ptr Options)`
	Sets the system of units for the solid.

	This method is enabled for Creo Direct.

Methods Inherited from Class pfcFamilyMember:: GetParent, GetImmediateGenericInfo, GetTopGenericInfo, ListColumns, ListRows, GetCell, SetCell, GetCellIsDefault, AddRow, GetRow, RemoveRow, AddColumn, RemoveColumn, GetColumn, CreateColumn, CreateParamColumn, CreateDimensionColumn, CreateFeatureColumn, CreateComponentColumn, CreateCompModelColumn, CreateGroupColumn, CreateMergePartColumn, CreateTolPlusColumn, CreateTolMinusColumn, CreateTolPlusMinusColumn

Methods Inherited from Class pfcParent:: GetChild

Methods Inherited from Class pfcModelItemOwner:: GetItemByName, GetItemById, ListItems

Methods Inherited from Class pfcViewOwner:: RetrieveView, GetView, SaveView, GetCurrentViewTransform, SetCurrentViewTransform, CurrentViewRotate, ListViews, GetCurrentView

Methods Inherited from Class pfcChild:: GetDBParent, GetOId

Methods Inherited from Class pfcActionSource:: AddActionListener, RemoveActionListener

Methods Inherited from Class pfcRelationOwner:: DeleteRelations, GetRelations, SetRelations, RegenerateRelations, EvaluateExpression

Methods Inherited from Class pfcParameterOwner:: GetParam, CreateParam, ListParams, SelectParam, CreateParamWithUnits, SelectParameters

Methods Inherited from Class pfcModel:: GetDescr, GetRelationId, GetIsModified, GetVersionStamp, GetRevision, GetVersion, GetBranch, GetReleaseLevel, GetCommonName, SetCommonName, IsCommonNameModifiable, GetFullName, GetInstanceName, GetGenericName, GetType, GetFileName, Backup, Copy, CopyAndRetrieve, Rename, Save, Erase, EraseWithDependencies, Delete, Display, ListDependencies, ListDeclaredModels, CreateLayer, Export, Import, AccessExternalData, TerminateExternalData, CheckIsSaveAllowed, CheckIsModifiable, GetOrigin, GetPostRegenerationRelations, SetPostRegenerationRelations, RegeneratePostRegenerationRelations, DeletePostRegenerationRelations, CleanupDependencies, IsNativeModel, ExportIntf3D

Method Detail

pfcOutline3D_ptr GetGeomOutline ()

This method is enabled for Creo Direct.

The outline of the solid with respect to the base coordinate system orientation

Manual References:: Solid: Solid Operations, Solid: Solid Operations

`optional xreal`	`GetRelativeAccuracy`	`()`
`void`	`SetRelativeAccuracy`	`(optional xreal value)`

This method is enabled for Creo Direct.

The relative accuracy of the solid or null, if absolute accuracy is used

Manual References:: Solid: Solid Information, Solid: Solid Information

`optional xreal`	`GetAbsoluteAccuracy`	`()`
`void`	`SetAbsoluteAccuracy`	`(optional xreal value)`

This method is enabled for Creo Direct.

The absolute accuracy of the solid or null, if relative accuracy is used

Manual References:: Solid: Solid Information, Solid: Solid Information

void Regenerate (optional pfcRegenInstructions_ptr Instrs)

Regenerates the solid.

Regeneration in No-Resolve mode (default mode in Creo Elements/Pro) is not supported. This method will throw pfcXToolkitBadContext, if Creo Parametric is running in No-Resolve mode. To continue with the Pro/ENGINEER Wildfire 4.0 behavior in Resolve mode, set the configuration option 'regen_failure_handling' to 'resolve_mode'. The regeneration instructions. This parameter can be null, in which case the Creo Parametric's Fix Model interface is not displayed after a failure.

Exceptions thrown (but not limited to):

pfcXToolkitUnattachedFeats - Unattached features were detected, but there was no regeneration failure

pfcXToolkitRegenerateAgain - The model is too complex to regenerate the first time

pfcXToolkitBadContext - Invalid regen flags and/or combination of regeneration flags if mixed with pfcRegenInstructions::SetForceRegen as true.

Manual References:: Solid: Regenerating a Solid, Solid: Regenerating a Solid

Parameters:

Instrs

Returns:

void ExecuteFeatureOps (pfcFeatureOperations_ptr Ops, optional pfcRegenInstructions_ptr Instrs)

Performs the specified feature operations.

This method is not supported in No-Resolve mode (default regeneration mode in Creo Elements/Pro). It will throw pfcXToolkitBadContext, if Creo Parametric is running in No-Resolve mode. To continue with the Pro/ENGINEER Wildfire 4.0 behavior in Resolve mode, set the configuration option 'regen_failure_handling' to 'resolve_mode'. The feature operations (suppress, delete, resume, and so on) The regeneration instructions. This parameter can be null, in which case the Creo Parametric's Fix Model interface is not displayed after a failure.

Exceptions thrown (but not limited to):

pfcXToolkitNotValid - One or more input features is not permitted to be suppressed.

pfcXToolkitSuppressedParents - Suppressed parents were found.

<reference 4 to unknown entity pfcExceptions::pfcXToolkitInvalidPtr> - Feature operation is invalid

Manual References:: Features: Feature Operations, Features: Feature Operations, Assemblies and Components: Assembly Components

Parameters:

Ops
Instrs

Returns:

pfcOutline3D_ptr EvalOutline (optional pfcTransform3D_ptr Trf, optional pfcModelItemTypes_ptr ExcludeTypes)

This method is enabled for Creo Direct.

Computes the outline of a solid.

Manual References:: Solid: Solid Operations, Solid: Solid Operations

Parameters:

Trf: The orientation matrix (with respect to the base coordinatesystem) to which the outline is to be computed
ExcludeTypes: An array of model-item types to exclude from the outline computation. The types that can be excluded are ITEM_COORD_SYS, ITEM_AXIS, and ITEM_POINT.

Returns:: An Outline3D object which contains two points that define the boundaries of the solid in the specified orientation

pfcFeatureGroup_ptr CreateLocalGroup (pfcFeatures_ptr Members, xrstring Name)

Creates a local group out of the specified set of features.

The supplied features must represent a contiguous set of features in the part or assembly.

Manual References:: Features: Feature Groups and Patterns, Features: Feature Groups and Patterns

Parameters:

Members: The features to be grouped
Name: The name to be assigned to the created local group

Returns:: The local group that was created

pfcModelItem_ptr CreateNote (xstringsequence_ptr Lines, optional pfcModelItem_ptr Owner)

Parameters:

Lines
Owner

Returns:

optional pfcFeatures_ptr ListFailedFeatures ()

Retrieves the list of failed features in the part or assembly.

Manual References:: Features: Access to Features, Features: Access to Features

Returns:: The list of failed features, or null if no failed features has been found

optional pfcFeatures_ptr ListFeaturesByType (optional xbool VisibleOnly, optional pfcFeatureType Type)

Lists the features according to type.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - No failed feature was found.

Manual References:: Features: Access to Features, Features: Access to Features

Parameters:

VisibleOnly: If this is true, the function lists public features only. If this is false, the function lists both public and internal features. Internal features are 'invisible' features and used internally for construction purposes. (If the argument is null, true will be used.)
Type: The feature type or null, if all the solid features are to be listed

Returns:: The list of features or null, if no features of the specified type has been found

optional pfcXSections_ptr ListCrossSections ()

Lists the cross-sections in the solid model.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - Model doesn't have cross-sections.

Manual References:: Cross Sections: Listing Cross Sections, Cross Sections: Listing Cross Sections

Returns:: Sequence of cross-section objects.

optional pfcXSection_ptr GetCrossSection (xrstring Name)

Returns a cross-section object, given its name.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - Model doesn't have cross-sections.

Manual References:: Cross Sections: Listing Cross Sections, Cross Sections: Listing Cross Sections

Parameters:

Name: The name of the cross-section.

Returns:: The cross-section object, or null, if the cross-section with that name does not exist.

xbool GetIsSkeleton ()

true if the model is a skeleton model, false otherwise.

Exceptions thrown (but not limited to):

pfcXToolkitNotValid - Required license not found.

Manual References:: Solid: Solid Operations, Solid: Solid Operations, Assemblies and Components: Skeleton Models

xbool HasRetrievalErrors ()

Identifies if a previous call to retrieve the model resulted in errors.

Models may be retrieved even if some component models are missing. The missing components will be suppressed, and geometry referencing these models will be frozen. The retrieval methods will not give an indication that this error occurred. Call this method after retrieval to see if any such errors occurred. pfcSession::BaseSession::RetrieveModel

pfcSession::BaseSession::RetrieveModelWithOpts

pfcSession::BaseSession::OpenFile

pfcSession::BaseSession::RetrieveAssemSimpRep

true if errors occurred during retrieval, false if there was no error.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - Errors were not found for this model.

Manual References:: Models: Retrieving Models

Returns:

optional pfcFeature_ptr GetFeatureByName (xrstring Name)

Locates the feature object, given its name.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The item was not found.

Parameters:

Name: The name of the feature to locate.

Returns:: The feature object, or null, if the feature was not found.

optional pfcFeature_ptr GetFeatureById (xint Id)

Retrieves the specified feature, given its identifier.

Exceptions thrown (but not limited to):

pfcXToolkitNotExist - Item with such id and type does not exist.

Manual References:: Features: Access to Features, Features: Access to Features

Parameters:

Id: The feature identifier

Returns:: The requested feature or null, if the solid does not contain a featurewith the specified identifier.

pfcFeature_ptr CreateImportFeat (pfcIntfDataSource_ptr IntfData, optional pfcCoordSystem_ptr CoordSys, optional pfcImportFeatAttr_ptr FeatAttr)

Creates a new import feature in the solid (part). Assembly case is not supported.

Exceptions thrown (but not limited to):

pfcXToolkitUnsupported - Creo Parametric does not support import of the indicated file.

pfcXToolkitNotExist - No profile found.

pfcXToolkitInvalidFile - profile is not readable.

Manual References:: Interface: Solid Operations, Interface: Solid Operations

Parameters:

IntfData: The source of data (that is, the file) from which to create the import feature.
CoordSys: A reference coordinate system. If NULL, the method uses the default coordinate system.
FeatAttr: The attributes for creation of the new import feature. If NULL, the method uses the default attributes.

Returns:: The handle to the new import feature.

void ActivateSimpRep (pfcSimpRep_ptr SimpRep)

Activates the specified simplified representation.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The specified simplified representation was not found in the model.

Manual References:: Simplified Representations: Simplified Representation Utilities, Simplified Representations: Simplified Representation Utilities

Parameters:

SimpRep: The simplified representation to activate.

Returns:

pfcSimpRep_ptr GetActiveSimpRep ()

Returns the current active simplified representation.

Manual References:: Simplified Representations: Simplified Representation Utilities

Returns:: The current active simplified representation

pfcSimpRep_ptr CreateSimpRep (pfcCreateNewSimpRepInstructions_ptr Instructions)

Creates a simplified representation based on the supplied instructions.

Manual References:: Simplified Representations: Creating and Deleting Simplified Representations, Simplified Representations: Creating and Deleting Simplified Representations

Parameters:

Instructions: The Instructions (data) for the simplified representation.

Returns:: The handle to the new simplified representation.

pfcSimpRep_ptr SelectSimpRep ()

Enables the user to select a simplified representation.

Exceptions thrown (but not limited to):

pfcXToolkitUserAbort - The user aborted simplified representation selection.

Manual References:: Simplified Representations: Simplified Representation Utilities, Simplified Representations: Simplified Representation Utilities

Returns:: The selected simplified representation.

pfcSimpRep_ptr GetSimpRep (xrstring SimpRepName)

Returns the handle to the specified simplified representation.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The function did not find the simplified representation in the solid.

Manual References:: Simplified Representations: Simplified Representation Utilities, Simplified Representations: Simplified Representation Utilities

Parameters:

SimpRepName: The name of the simplified representation in the solid.

Returns:

pfcSimpRep_ptr GetMasterRep ()

Returns the object representing the solid model's Master Rep.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The function did not find the simplified representation in the solid.

See Also:: pfcSolid::GetSimpRep(xrstring), pfcSolid::GetGraphicsRep(), pfcSolid::GetGeomRep(), pfcSimpRep::GetSimpRepType()

Returns:: An object representing the Master Rep.

pfcSimpRep_ptr GetGraphicsRep ()

Returns the object representing the solid model's Grpahics Rep.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The function did not find the simplified representation in the solid.

See Also:: pfcSolid::GetSimpRep(xrstring), pfcSolid::GetGeomRep(), pfcSolid::GetMasterRep(), pfcSimpRep::GetSimpRepType()

Returns:: An object representing the Graphics Rep.

pfcSimpRep_ptr GetGeomRep ()

Returns the object representing the solid model's Geometry Rep.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The function did not find the simplified representation in the solid.

See Also:: pfcSolid::GetSimpRep(xrstring), pfcSolid::GetGraphicsRep(), pfcSolid::GetMasterRep(), pfcSimpRep::GetSimpRepType()

Returns:: An object representing the Geometry Rep.

void DeleteSimpRep (pfcSimpRep_ptr SimpRep)

Deletes the specified simplified representation from its owner model.

Manual References:: Simplified Representations: Creating and Deleting Simplified Representations

Parameters:

SimpRep: The simplified representation to delete.

Returns:

pfcMassProperty_ptr GetMassProperty (optional xrstring CoordSysName)

This method is enabled for Creo Direct.

Gets the mass properties for the solid.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The specified coordinate system was not found.

Manual References:: Solid: Mass Properties

Parameters:

CoordSysName: The coordinate system name used to compute the mass property.If null, uses the default coordinate system.

Returns:

pfcFeatureGroups_ptr ListGroups ()

Collect groups (including UDFs) in the solid.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - No groups exist in the solid

Manual References:: Solid: Solid Operations, Solid: Solid Operations

Returns:: The list of groups.

pfcFeature_ptr CreateFeature (pfcFeatureCreateInstructions_ptr Instructions)

Not implemented in the current release. Creates a feature, based on the instructions provided.

Object Toolkit users can use WCreateFeature

Parameters:

Instructions: Descriptions of the type of feature to create.

Returns:: pfcFeature object

pfcFeatureGroup_ptr CreateUDFGroup (pfcUDFGroupCreateInstructions_ptr Instructions)

Creates a FeatureGroup, based on the instructions provided.

Exceptions thrown (but not limited to):

pfcXToolkitUnsupported - The input model is Multi-CAD model.

Manual References:: Features: Read Access to Groups and User Defined Features, Features: Creating Features from UDFs, Features: Creating a Custom UDF, Features: Creating a Custom UDF, Solid: Getting a Solid Object

Parameters:

Instructions: Data objects containing parameters for the type of feature group to create.

Returns:: The created UDF group.

void ExportShrinkwrap (pfcShrinkwrapExportInstructions_ptr Instructions)

Exports a solid model to shrinkwrap format.

Exceptions thrown (but not limited to):

pfcXToolkitBadContext - Invalid combination of input arguments.

pfcXToolkitLineTooLong - Name length of the output file is more than 31 chars.

Manual References:: Interface: Shrinkwrap Export

Parameters:

Instructions: Instructions describing the type and contents of the shrinkwrap model.

Returns:

pfcUnitSystem_ptr GetPrincipalUnits ()

This method is enabled for Creo Direct.

Gets the system of units assigned to the solid model.

Manual References:: Solid: Accessing Systems of Units, Solid: Accessing Systems of Units

Returns:: The unit system.

void SetPrincipalUnits (pfcUnitSystem_ptr Units, pfcUnitConversionOptions_ptr Options)

Sets the system of units for the solid.

This will regenerate the model.

Manual References:: Solid: Conversion to a New Unit System, Solid: Conversion to a New Unit System

Parameters:

Units: The new unit system.
Options: Information about the data conversion should take place.

Returns:

pfcUnits_ptr ListUnits (optional pfcUnitType Type)

Lists the units available in the model.

Manual References:: Solid: Accessing Individual Units, Solid: Accessing Individual Units

Parameters:

Type: The type of units to list. If this is null, this will list all unit types.

Returns:: The list of units found.

pfcUnitSystems_ptr ListUnitSystems ()

Lists the unit systems available in the model.

Manual References:: Solid: Accessing Systems of Units, Solid: Accessing Systems of Units

Returns:: The list of unit systems.

optional pfcUnit_ptr GetUnit (xrstring Name, optional xbool ByExpression)

Get the handle to a particular unit based on name or expression.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The indicated unit name does not exist in the model.

Manual References:: Solid: Accessing Individual Units, Solid: Accessing Individual Units

Parameters:

Name: The name, or expression, for the unit.
ByExpression: Specifies whether name is to be treated as an expression (value true) or not (value false).

Returns:: The initialized pfcUnit

pfcUnit_ptr CreateCustomUnit (xrstring Name, pfcUnitConversionFactor_ptr ConversionFactor, pfcUnit_ptr ReferenceUnit)

Creates a custom unit based on name, conversion factor and reference unit.

Exceptions thrown (but not limited to):

pfcXToolkitNotFound - The reference unit was not found in the model.

Manual References:: Solid: Creating a New Unit, Solid: Creating a New Unit

Parameters:

Name: The name of the unit
ConversionFactor: Information relating the new unit to its reference unit.
ReferenceUnit: The unit upon which the new unit is based.

Returns:: The created pfcUnit

pfcUnitSystem_ptr CreateUnitSystem (xrstring Name, pfcUnitSystemType Type, pfcUnits_ptr Units)

Creates a new unit system in the model.

Units should include at most one occurrence of each basic unit type. If a unit of a basic type is missing then a corresponding one is taken from the standard system 'Creo Parametric Default'. The created pfcUnitSystem The name of the new unit system. The type of unit system to create (Mass/Length/Time) or (Force/Length/Time). Sequence of units that makes up the new unit system.

Exceptions thrown (but not limited to):

pfcXToolkitAmbiguous - The units argument contains multiple units for a type.

Manual References:: Solid: Creating a New System of Units

Parameters:

Name
Type
Units

Returns: