Skip to content

add_scene_3d_labeladd_scene_3d_labelAddScene3dLabelAddScene3dLabeladd_scene_3d_labelT_add_scene_3d_labelπŸ”—

Short descriptionπŸ”—

add_scene_3d_labeladd_scene_3d_labelAddScene3dLabelAddScene3dLabeladd_scene_3d_labelT_add_scene_3d_label β€” Add a text label to a 3D scene.

SignatureπŸ”—

add_scene_3d_label( scene_3d Scene3D, string Text, point ReferencePoint, point Position, string RelatesTo, out integer LabelIndex )add_scene_3d_label( : : Scene3D, Text, ReferencePoint, Position, RelatesTo : LabelIndex )void AddScene3dLabel( const HTuple& Scene3D, const HTuple& Text, const HTuple& ReferencePoint, const HTuple& Position, const HTuple& RelatesTo, HTuple* LabelIndex )static void HOperatorSet.AddScene3dLabel( HTuple scene3D, HTuple text, HTuple referencePoint, HTuple position, HTuple relatesTo, out HTuple labelIndex )def add_scene_3d_label( scene_3d: HHandle, text: MaybeSequence[str], reference_point: Sequence[Union[float, int]], position: Sequence[Union[float, int, str]], relates_to: Sequence[str] ) -> int

Herror T_add_scene_3d_label( const Htuple Scene3D, const Htuple Text, const Htuple ReferencePoint, const Htuple Position, const Htuple RelatesTo, Htuple* LabelIndex )

Hlong HScene3D::AddScene3dLabel( const HTuple& Text, const HTuple& ReferencePoint, const HTuple& Position, const HTuple& RelatesTo ) const

Hlong HScene3D::AddScene3dLabel( const HString& Text, const HTuple& ReferencePoint, const HTuple& Position, const HTuple& RelatesTo ) const

Hlong HScene3D::AddScene3dLabel( const char* Text, const HTuple& ReferencePoint, const HTuple& Position, const HTuple& RelatesTo ) const

Hlong HScene3D::AddScene3dLabel( const wchar_t* Text, const HTuple& ReferencePoint, const HTuple& Position, const HTuple& RelatesTo ) const (Windows only)

int HScene3D.AddScene3dLabel( HTuple text, HTuple referencePoint, HTuple position, HTuple relatesTo )

int HScene3D.AddScene3dLabel( string text, HTuple referencePoint, HTuple position, HTuple relatesTo )

DescriptionπŸ”—

add_scene_3d_labelAddScene3dLabel adds a label with the text in Texttexttext to the 3D scene Scene3Dscene3Dscene_3d and returns its index in LabelIndexlabelIndexlabel_index.

The reference point of the label must be given as [X, Y, Z][X, Y, Z] point in the coordinate system of the 3D scene in ReferencePointreferencePointreference_point. It is valid to create labels without a reference point by passing an empty tuple to ReferencePointreferencePointreference_point, however RelatesTorelatesTorelates_to must be set to 'window'"window" in this case (see the description of RelatesTorelatesTorelates_to below).

If multiple label texts are supplied in Texttexttext, multiple labels are created. It is possible to set one reference point for all labels or a specific reference point for each label. The same applies to Positionpositionposition and RelatesTorelatesTorelates_to.

Labels can be positioned fixed in window coordinates or relative to the projection of the reference point. The two parameters Positionpositionposition and RelatesTorelatesTorelates_to are used for positioning.

Fixed positioning

If RelatesTorelatesTorelates_to is set to 'window'"window", the Label is shown at a fixed position in the window (or rendered image), even if the pose of the 3D scene is changed. There are two ways to specify the position. You can either supply the [Row, Column][Row, Column] coordinates of the top left corner of the label in Positionpositionposition or use one of the predefined positions:

'top_left'"top_left" 'top'"top" 'top_right'"top_right"
'left'"left" 'center'"center" 'right'"right"
'bottom_left'"bottom_left" 'bottom'"bottom" 'bottom_right'"bottom_right"

Relative positioning

If RelatesTorelatesTorelates_to is set to 'point'"point", the Label is shown at a position relative to the projection of the reference point. This way, the label moves with the reference point if the pose of the 3D scene is changed. There are two ways to specify the position. You can either supply the [Row, Column][Row, Column] offset of the top left corner of the label in Positionpositionposition or use one of the predefined positions:

'top_left'"top_left" 'top'"top" 'top_right'"top_right"
'left'"left" 'center'"center" 'right'"right"
'bottom_left'"bottom_left" 'bottom'"bottom" 'bottom_right'"bottom_right"

The operator set_scene_3d_label_paramSetScene3dLabelParam can be used to change these values and to set other parameters such as the label’s color and font.

Execution informationπŸ”—

Execution information
  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Processed without parallelization.

ParametersπŸ”—

Scene3Dscene3Dscene_3d (input_control) scene_3d β†’ (handle)(handle)HTuple (HHandle)HScene3D, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the 3D scene.

Texttexttext (input_control) string(-array) β†’ (string)(string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Text of the label.

Default: 'label'"label"

ReferencePointreferencePointreference_point (input_control) point-array β†’ (real / integer)(real / integer)HTuple (double / Hlong)HTuple (double / int / long)Sequence[Union[float, int]]Htuple (double / Hlong)

Point of reference of the label.

Number of elements: 3

Positionpositionposition (input_control) point-array β†’ (string / real / integer)(string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)Sequence[Union[float, int, str]]Htuple (char* / double / Hlong)

Position of the label.

Default: 'top'"top"
List of values: 'bottom', 'bottom_left', 'bottom_right', 'center', 'left', 'right', 'top', 'top_left', 'top_right'"bottom", "bottom_left", "bottom_right", "center", "left", "right", "top", "top_left", "top_right"

RelatesTorelatesTorelates_to (input_control) string-array β†’ (string)(string)HTuple (HString)HTuple (string)Sequence[str]Htuple (char*)

Indicates fixed or relative positioning.

Number of elements: 1
Default: 'point'"point"
List of values: 'point', 'window'"point", "window"

LabelIndexlabelIndexlabel_index (output_control) integer β†’ (integer)(integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Index of the new label in the 3D scene.

ResultπŸ”—

add_scene_3d_labelAddScene3dLabel returns 2 (H_MSG_TRUE) if all parameters are correct. If necessary, an exception is raised.

Combinations with other operatorsπŸ”—

Combinations

Possible predecessors

create_scene_3dCreateScene3d

Possible successors

set_scene_3d_label_paramSetScene3dLabelParam

See also

remove_scene_3d_instanceRemoveScene3dInstance

ModuleπŸ”—

3D Metrology