Open CASCADE Technology  7.2.0
Public Member Functions | Protected Member Functions | Protected Attributes

SelectMgr_ViewerSelector Class Reference

A framework to define finding, sorting the sensitive primitives in a view. Services are also provided to define the return of the owners of those primitives selected. The primitives are sorted by criteria such as priority of the primitive or its depth in the view relative to that of other primitives. Note that in 3D, the inheriting framework StdSelect_ViewerSelector3d is only to be used if you do not want to use the services provided by AIS. Two tools are available to find and select objects found at a given position in the view. If you want to select the owners of all the objects detected at point x,y,z you use the Init - More - Next - Picked loop. If, on the other hand, you want to select only one object detected at that point, you use the Init - More - OnePicked loop. In this iteration, More is used to see if an object was picked and OnePicked, to get the object closest to the pick position. Viewer selectors are driven by SelectMgr_SelectionManager, and manipulate the SelectMgr_Selection objects given to them by the selection manager. More...

#include <SelectMgr_ViewerSelector.hxx>

Inheritance diagram for SelectMgr_ViewerSelector:
Inheritance graph
[legend]

Public Member Functions

void Clear ()
 Empties all the tables, removes all selections... More...
 
Standard_Real Sensitivity () const
 returns the Sensitivity of picking More...
 
void SortResult ()
 Sorts the detected entites by priority and distance. to be redefined if other criterion are used... More...
 
Handle< SelectMgr_EntityOwnerOnePicked () const
 Returns the picked element with the highest priority, and which is the closest to the last successful mouse position. More...
 
void SetPickClosest (const Standard_Boolean theToPreferClosest)
 Set preference of selecting one object for OnePicked() method: More...
 
Standard_Integer NbPicked () const
 Returns the number of detected owners. More...
 
Handle< SelectMgr_EntityOwnerPicked (const Standard_Integer theRank) const
 Returns the entity Owner for the object picked at specified position. More...
 
const SelectMgr_SortCriterionPickedData (const Standard_Integer theRank) const
 Returns the Entity for the object picked at specified position. More...
 
const Handle< SelectBasics_SensitiveEntity > & PickedEntity (const Standard_Integer theRank) const
 Returns the Entity for the object picked at specified position. More...
 
gp_Pnt PickedPoint (const Standard_Integer theRank) const
 Returns the 3D point (intersection of picking axis with the object nearest to eye) for the object picked at specified position. More...
 
Standard_Boolean Contains (const Handle< SelectMgr_SelectableObject > &theObject) const
 
const Handle< Select3D_BVHBuilder3dEntitySetBuilder ()
 Returns the default builder used to construct BVH of entity set. More...
 
void SetEntitySetBuilder (const Handle< Select3D_BVHBuilder3d > &theBuilder)
 Sets the default builder used to construct BVH of entity set. The new builder will be also assigned for already defined objects, but computed BVH trees will not be invalidated. More...
 
Standard_Boolean Modes (const Handle< SelectMgr_SelectableObject > &theSelectableObject, TColStd_ListOfInteger &theModeList, const SelectMgr_StateOfSelection theWantedState=SelectMgr_SOS_Any) const
 Returns the list of selection modes ModeList found in this selector for the selectable object aSelectableObject. Returns true if aSelectableObject is referenced inside this selector; returns false if the object is not present in this selector. More...
 
Standard_Boolean IsActive (const Handle< SelectMgr_SelectableObject > &theSelectableObject, const Standard_Integer theMode) const
 Returns true if the selectable object aSelectableObject having the selection mode aMode is active in this selector. More...
 
Standard_Boolean IsInside (const Handle< SelectMgr_SelectableObject > &theSelectableObject, const Standard_Integer theMode) const
 Returns true if the selectable object aSelectableObject having the selection mode aMode is in this selector. More...
 
SelectMgr_StateOfSelection Status (const Handle< SelectMgr_Selection > &theSelection) const
 Returns the selection status Status of the selection aSelection. More...
 
TCollection_AsciiString Status (const Handle< SelectMgr_SelectableObject > &theSelectableObject) const
 
void ActiveOwners (NCollection_List< Handle< SelectBasics_EntityOwner >> &theOwners) const
 Returns the list of active entity owners. More...
 
void AddSelectableObject (const Handle< SelectMgr_SelectableObject > &theObject)
 Adds new object to the map of selectable objects. More...
 
void AddSelectionToObject (const Handle< SelectMgr_SelectableObject > &theObject, const Handle< SelectMgr_Selection > &theSelection)
 Adds new selection to the object and builds its BVH tree. More...
 
void MoveSelectableObject (const Handle< SelectMgr_SelectableObject > &theObject)
 Moves existing object from set of not transform persistence objects to set of transform persistence objects (or vice versa). More...
 
void RemoveSelectableObject (const Handle< SelectMgr_SelectableObject > &theObject)
 Removes selectable object from map of selectable ones. More...
 
void RemoveSelectionOfObject (const Handle< SelectMgr_SelectableObject > &theObject, const Handle< SelectMgr_Selection > &theSelection)
 Removes selection of the object and marks its BVH tree for rebuild. More...
 
void RebuildObjectsTree (const Standard_Boolean theIsForce=Standard_False)
 Marks BVH of selectable objects for rebuild. Parameter theIsForce set as true guarantees that 1st level BVH for the viewer selector will be rebuilt during this call. More...
 
void RebuildSensitivesTree (const Handle< SelectMgr_SelectableObject > &theObject, const Standard_Boolean theIsForce=Standard_False)
 Marks BVH of sensitive entities of particular selectable object for rebuild. Parameter theIsForce set as true guarantees that 2nd level BVH for the object given will be rebuilt during this call. More...
 
SelectMgr_SelectingVolumeManagerGetManager ()
 Returns instance of selecting volume manager of the viewer selector. More...
 
void ResetSelectionActivationStatus ()
 Marks all added sensitive entities of all objects as non-selectable. More...
 
void AllowOverlapDetection (const Standard_Boolean theIsToAllow)
 Is used for rectangular selection only If theIsToAllow is false, only fully included sensitives will be detected, otherwise the algorithm will mark both included and overlapped entities as matched. More...
 
 Standard_DEPRECATED ("Deprecated method Init()") void Init()
 Begins an iteration scanning for the owners detected at a position in the view. More...
 
 Standard_DEPRECATED ("Deprecated method More()") 1 Standard_Boolean More()
 Continues the interation scanning for the owners detected at a position in the view, or continues the iteration scanning for the owner closest to the position in the view. More...
 
 Standard_DEPRECATED ("Deprecated method Next()") void Next()
 Returns the next owner found in the iteration. This is a scan for the owners detected at a position in the view. More...
 
 Standard_DEPRECATED ("Deprecated method Picked()") 1 Handle< SelectMgr_EntityOwner > Picked() const
 Returns the current selected entity detected by the selector;. More...
 
 Standard_DEPRECATED ("Deprecated method InitDetected()") void InitDetected()
 Initializes internal iterator for stored detected sensitive entities. More...
 
 Standard_DEPRECATED ("Deprecated method NextDetected()") void NextDetected()
 Makes a step along the map of detected sensitive entities and their owners. More...
 
 Standard_DEPRECATED ("Deprecated method MoreDetected()") Standard_Boolean MoreDetected()
 Returns true if iterator of map of detected sensitive entities has reached its end. More...
 
 Standard_DEPRECATED ("Deprecated method DetectedEntity() should be replaced by DetectedEntity(int)") 1 const Handle< SelectBasics_SensitiveEntity > &DetectedEntity() const
 Returns sensitive entity that was detected during the previous run of selection algorithm. More...
 
- Public Member Functions inherited from Standard_Transient
 Standard_Transient ()
 Empty constructor. More...
 
 Standard_Transient (const Standard_Transient &)
 Copy constructor – does nothing. More...
 
Standard_Transientoperator= (const Standard_Transient &)
 Assignment operator, needed to avoid copying reference counter. More...
 
virtual ~Standard_Transient ()
 Destructor must be virtual. More...
 
virtual void Delete () const
 Memory deallocator for transient classes. More...
 
virtual const opencascade::handle< Standard_Type > & DynamicType () const
 Returns a type descriptor about this object. More...
 
Standard_Boolean IsInstance (const opencascade::handle< Standard_Type > &theType) const
 Returns a true value if this is an instance of Type. More...
 
Standard_Boolean IsInstance (const Standard_CString theTypeName) const
 Returns a true value if this is an instance of TypeName. More...
 
Standard_Boolean IsKind (const opencascade::handle< Standard_Type > &theType) const
 Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...
 
Standard_Boolean IsKind (const Standard_CString theTypeName) const
 Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...
 
Standard_TransientThis () const
 Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero. More...
 
Standard_Integer GetRefCount () const
 Get the reference counter of this object. More...
 
void IncrementRefCounter () const
 Increments the reference counter of this object. More...
 
Standard_Integer DecrementRefCounter () const
 Decrements the reference counter of this object; returns the decremented value. More...
 

Protected Member Functions

 SelectMgr_ViewerSelector ()
 
void TraverseSensitives ()
 Traverses BVH containing all added selectable objects and finds candidates for further search of overlap. More...
 
virtual Standard_Boolean HasDepthClipping (const Handle< SelectMgr_EntityOwner > &theOwner) const
 Returns True if the owner provides clipping by depth for its sensitives. Override this method to tell the selector to use the DepthClipping method for the owner. Default implementation returns False for every owner. More...
 
void traverseObject (const Handle< SelectMgr_SelectableObject > &theObject, const SelectMgr_SelectingVolumeManager &theMgr, const Handle< Graphic3d_Camera > &theCamera, const Graphic3d_Mat4d &theProjectionMat, const Graphic3d_Mat4d &theWorldViewMat, const Standard_Integer theViewportWidth, const Standard_Integer theViewportHeight)
 Internal function that checks if there is possible overlap between some entity of selectable object theObject and current selecting volume. More...
 
void checkOverlap (const Handle< SelectBasics_SensitiveEntity > &theEntity, const gp_GTrsf &theInversedTrsf, SelectMgr_SelectingVolumeManager &theMgr)
 Internal function that checks if a particular sensitive entity theEntity overlaps current selecting volume precisely. More...
 

Protected Attributes

Standard_Boolean preferclosest
 
Standard_Boolean myToUpdateTolerance
 
SelectMgr_IndexedDataMapOfOwnerCriterion mystored
 
SelectMgr_SelectingVolumeManager mySelectingVolumeMgr
 
SelectMgr_SelectableObjectSet mySelectableObjects
 
SelectMgr_ToleranceMap myTolerances
 
NCollection_DataMap< Graphic3d_ZLayerId, Standard_IntegermyZLayerOrderMap
 
Handle< Select3D_BVHBuilder3dmyEntitySetBuilder
 

Additional Inherited Members

- Public Types inherited from Standard_Transient
typedef void base_type
 Returns a type descriptor about this object. More...
 
- Static Public Member Functions inherited from Standard_Transient
static const char * get_type_name ()
 Returns a type descriptor about this object. More...
 
static const opencascade::handle< Standard_Type > & get_type_descriptor ()
 Returns type descriptor of Standard_Transient class. More...
 

Detailed Description

A framework to define finding, sorting the sensitive primitives in a view. Services are also provided to define the return of the owners of those primitives selected. The primitives are sorted by criteria such as priority of the primitive or its depth in the view relative to that of other primitives. Note that in 3D, the inheriting framework StdSelect_ViewerSelector3d is only to be used if you do not want to use the services provided by AIS. Two tools are available to find and select objects found at a given position in the view. If you want to select the owners of all the objects detected at point x,y,z you use the Init - More - Next - Picked loop. If, on the other hand, you want to select only one object detected at that point, you use the Init - More - OnePicked loop. In this iteration, More is used to see if an object was picked and OnePicked, to get the object closest to the pick position. Viewer selectors are driven by SelectMgr_SelectionManager, and manipulate the SelectMgr_Selection objects given to them by the selection manager.

Tolerances are applied to the entities in the following way:

  1. tolerance value stored in mytolerance will be used to calculate initial selecting frustum, which will be applied for intersection testing during BVH traverse;
  2. if tolerance of sensitive entity is less than mytolerance, the frustum for intersection detection will be resized according to its sensitivity.

Constructor & Destructor Documentation

◆ SelectMgr_ViewerSelector()

SelectMgr_ViewerSelector::SelectMgr_ViewerSelector ( )
protected

Member Function Documentation

◆ ActiveOwners()

void SelectMgr_ViewerSelector::ActiveOwners ( NCollection_List< Handle< SelectBasics_EntityOwner >> &  theOwners) const

Returns the list of active entity owners.

◆ AddSelectableObject()

void SelectMgr_ViewerSelector::AddSelectableObject ( const Handle< SelectMgr_SelectableObject > &  theObject)

Adds new object to the map of selectable objects.

◆ AddSelectionToObject()

void SelectMgr_ViewerSelector::AddSelectionToObject ( const Handle< SelectMgr_SelectableObject > &  theObject,
const Handle< SelectMgr_Selection > &  theSelection 
)

Adds new selection to the object and builds its BVH tree.

◆ AllowOverlapDetection()

void SelectMgr_ViewerSelector::AllowOverlapDetection ( const Standard_Boolean  theIsToAllow)

Is used for rectangular selection only If theIsToAllow is false, only fully included sensitives will be detected, otherwise the algorithm will mark both included and overlapped entities as matched.

◆ checkOverlap()

void SelectMgr_ViewerSelector::checkOverlap ( const Handle< SelectBasics_SensitiveEntity > &  theEntity,
const gp_GTrsf theInversedTrsf,
SelectMgr_SelectingVolumeManager theMgr 
)
protected

Internal function that checks if a particular sensitive entity theEntity overlaps current selecting volume precisely.

◆ Clear()

void SelectMgr_ViewerSelector::Clear ( )

Empties all the tables, removes all selections...

◆ Contains()

Standard_Boolean SelectMgr_ViewerSelector::Contains ( const Handle< SelectMgr_SelectableObject > &  theObject) const

◆ EntitySetBuilder()

const Handle< Select3D_BVHBuilder3d > SelectMgr_ViewerSelector::EntitySetBuilder ( )
inline

Returns the default builder used to construct BVH of entity set.

◆ GetManager()

SelectMgr_SelectingVolumeManager& SelectMgr_ViewerSelector::GetManager ( )
inline

Returns instance of selecting volume manager of the viewer selector.

◆ HasDepthClipping()

virtual Standard_Boolean SelectMgr_ViewerSelector::HasDepthClipping ( const Handle< SelectMgr_EntityOwner > &  theOwner) const
protectedvirtual

Returns True if the owner provides clipping by depth for its sensitives. Override this method to tell the selector to use the DepthClipping method for the owner. Default implementation returns False for every owner.

Parameters
theOwner[in] the onwer to check.
Returns
True if owner provides depth limits for sensitive clipping.

Reimplemented in StdSelect_ViewerSelector3d.

◆ IsActive()

Standard_Boolean SelectMgr_ViewerSelector::IsActive ( const Handle< SelectMgr_SelectableObject > &  theSelectableObject,
const Standard_Integer  theMode 
) const

Returns true if the selectable object aSelectableObject having the selection mode aMode is active in this selector.

◆ IsInside()

Standard_Boolean SelectMgr_ViewerSelector::IsInside ( const Handle< SelectMgr_SelectableObject > &  theSelectableObject,
const Standard_Integer  theMode 
) const

Returns true if the selectable object aSelectableObject having the selection mode aMode is in this selector.

◆ Modes()

Standard_Boolean SelectMgr_ViewerSelector::Modes ( const Handle< SelectMgr_SelectableObject > &  theSelectableObject,
TColStd_ListOfInteger theModeList,
const SelectMgr_StateOfSelection  theWantedState = SelectMgr_SOS_Any 
) const

Returns the list of selection modes ModeList found in this selector for the selectable object aSelectableObject. Returns true if aSelectableObject is referenced inside this selector; returns false if the object is not present in this selector.

◆ MoveSelectableObject()

void SelectMgr_ViewerSelector::MoveSelectableObject ( const Handle< SelectMgr_SelectableObject > &  theObject)

Moves existing object from set of not transform persistence objects to set of transform persistence objects (or vice versa).

◆ NbPicked()

Standard_Integer SelectMgr_ViewerSelector::NbPicked ( ) const
inline

Returns the number of detected owners.

◆ OnePicked()

Handle< SelectMgr_EntityOwner > SelectMgr_ViewerSelector::OnePicked ( ) const
inline

Returns the picked element with the highest priority, and which is the closest to the last successful mouse position.

◆ Picked()

Handle< SelectMgr_EntityOwner > SelectMgr_ViewerSelector::Picked ( const Standard_Integer  theRank) const

Returns the entity Owner for the object picked at specified position.

Parameters
theRankrank of detected object within range 1...NbPicked()

◆ PickedData()

const SelectMgr_SortCriterion& SelectMgr_ViewerSelector::PickedData ( const Standard_Integer  theRank) const

Returns the Entity for the object picked at specified position.

Parameters
theRankrank of detected object within range 1...NbPicked()

◆ PickedEntity()

const Handle< SelectBasics_SensitiveEntity >& SelectMgr_ViewerSelector::PickedEntity ( const Standard_Integer  theRank) const
inline

Returns the Entity for the object picked at specified position.

Parameters
theRankrank of detected object within range 1...NbPicked()

◆ PickedPoint()

gp_Pnt SelectMgr_ViewerSelector::PickedPoint ( const Standard_Integer  theRank) const
inline

Returns the 3D point (intersection of picking axis with the object nearest to eye) for the object picked at specified position.

Parameters
theRankrank of detected object within range 1...NbPicked()

◆ RebuildObjectsTree()

void SelectMgr_ViewerSelector::RebuildObjectsTree ( const Standard_Boolean  theIsForce = Standard_False)

Marks BVH of selectable objects for rebuild. Parameter theIsForce set as true guarantees that 1st level BVH for the viewer selector will be rebuilt during this call.

◆ RebuildSensitivesTree()

void SelectMgr_ViewerSelector::RebuildSensitivesTree ( const Handle< SelectMgr_SelectableObject > &  theObject,
const Standard_Boolean  theIsForce = Standard_False 
)

Marks BVH of sensitive entities of particular selectable object for rebuild. Parameter theIsForce set as true guarantees that 2nd level BVH for the object given will be rebuilt during this call.

◆ RemoveSelectableObject()

void SelectMgr_ViewerSelector::RemoveSelectableObject ( const Handle< SelectMgr_SelectableObject > &  theObject)

Removes selectable object from map of selectable ones.

◆ RemoveSelectionOfObject()

void SelectMgr_ViewerSelector::RemoveSelectionOfObject ( const Handle< SelectMgr_SelectableObject > &  theObject,
const Handle< SelectMgr_Selection > &  theSelection 
)

Removes selection of the object and marks its BVH tree for rebuild.

◆ ResetSelectionActivationStatus()

void SelectMgr_ViewerSelector::ResetSelectionActivationStatus ( )

Marks all added sensitive entities of all objects as non-selectable.

◆ Sensitivity()

Standard_Real SelectMgr_ViewerSelector::Sensitivity ( ) const
inline

returns the Sensitivity of picking

◆ SetEntitySetBuilder()

void SelectMgr_ViewerSelector::SetEntitySetBuilder ( const Handle< Select3D_BVHBuilder3d > &  theBuilder)

Sets the default builder used to construct BVH of entity set. The new builder will be also assigned for already defined objects, but computed BVH trees will not be invalidated.

◆ SetPickClosest()

void SelectMgr_ViewerSelector::SetPickClosest ( const Standard_Boolean  theToPreferClosest)
inline

Set preference of selecting one object for OnePicked() method:

  • If True, objects with less depth (distance fron the view plane) are preferred regardless of priority (priority is used then to choose among objects with similar depth),
  • If False, objects with higher priority are preferred regardless of the depth which is used to choose among objects of the same priority.

◆ SortResult()

void SelectMgr_ViewerSelector::SortResult ( )

Sorts the detected entites by priority and distance. to be redefined if other criterion are used...

◆ Standard_DEPRECATED() [1/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method Init()"  )
inline

Begins an iteration scanning for the owners detected at a position in the view.

◆ Standard_DEPRECATED() [2/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method More()"  )
inline

Continues the interation scanning for the owners detected at a position in the view, or continues the iteration scanning for the owner closest to the position in the view.

◆ Standard_DEPRECATED() [3/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method Next()"  )
inline

Returns the next owner found in the iteration. This is a scan for the owners detected at a position in the view.

◆ Standard_DEPRECATED() [4/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method Picked()"  ) const

Returns the current selected entity detected by the selector;.

◆ Standard_DEPRECATED() [5/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method InitDetected()"  )
inline

Initializes internal iterator for stored detected sensitive entities.

◆ Standard_DEPRECATED() [6/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method NextDetected()"  )
inline

Makes a step along the map of detected sensitive entities and their owners.

◆ Standard_DEPRECATED() [7/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method MoreDetected()"  )
inline

Returns true if iterator of map of detected sensitive entities has reached its end.

◆ Standard_DEPRECATED() [8/8]

SelectMgr_ViewerSelector::Standard_DEPRECATED ( "Deprecated method DetectedEntity() should be replaced by DetectedEntity(int)"  ) const &

Returns sensitive entity that was detected during the previous run of selection algorithm.

◆ Status() [1/2]

SelectMgr_StateOfSelection SelectMgr_ViewerSelector::Status ( const Handle< SelectMgr_Selection > &  theSelection) const

Returns the selection status Status of the selection aSelection.

◆ Status() [2/2]

TCollection_AsciiString SelectMgr_ViewerSelector::Status ( const Handle< SelectMgr_SelectableObject > &  theSelectableObject) const

◆ traverseObject()

void SelectMgr_ViewerSelector::traverseObject ( const Handle< SelectMgr_SelectableObject > &  theObject,
const SelectMgr_SelectingVolumeManager theMgr,
const Handle< Graphic3d_Camera > &  theCamera,
const Graphic3d_Mat4d theProjectionMat,
const Graphic3d_Mat4d theWorldViewMat,
const Standard_Integer  theViewportWidth,
const Standard_Integer  theViewportHeight 
)
protected

Internal function that checks if there is possible overlap between some entity of selectable object theObject and current selecting volume.

Parameters
theObject[in] the selectable object for traversal.
theMgr[in] the (un)transformed copy of the selecting volume manager representing active selection frustum.
theCamera,theProjectionMat,theWorldViewMat[in] the source camera and matrices for theMgr given.
theViewportWidth,theViewportHeight[in] viewport (window) dimensions for evaluating object's transformation persistence.

◆ TraverseSensitives()

void SelectMgr_ViewerSelector::TraverseSensitives ( )
protected

Traverses BVH containing all added selectable objects and finds candidates for further search of overlap.

Field Documentation

◆ myEntitySetBuilder

Handle< Select3D_BVHBuilder3d > SelectMgr_ViewerSelector::myEntitySetBuilder
protected

◆ mySelectableObjects

SelectMgr_SelectableObjectSet SelectMgr_ViewerSelector::mySelectableObjects
mutableprotected

◆ mySelectingVolumeMgr

SelectMgr_SelectingVolumeManager SelectMgr_ViewerSelector::mySelectingVolumeMgr
protected

◆ mystored

SelectMgr_IndexedDataMapOfOwnerCriterion SelectMgr_ViewerSelector::mystored
protected

◆ myTolerances

SelectMgr_ToleranceMap SelectMgr_ViewerSelector::myTolerances
protected

◆ myToUpdateTolerance

Standard_Boolean SelectMgr_ViewerSelector::myToUpdateTolerance
protected

◆ myZLayerOrderMap

NCollection_DataMap<Graphic3d_ZLayerId, Standard_Integer> SelectMgr_ViewerSelector::myZLayerOrderMap
protected

◆ preferclosest

Standard_Boolean SelectMgr_ViewerSelector::preferclosest
protected

The documentation for this class was generated from the following file: