add_scene_3d_labelT_add_scene_3d_labelAddScene3dLabelAddScene3dLabeladd_scene_3d_label (Operator)
Name
add_scene_3d_labelT_add_scene_3d_labelAddScene3dLabelAddScene3dLabeladd_scene_3d_label — Add a text label to a 3D scene.
Signature
void AddScene3dLabel(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)
static void HOperatorSet.AddScene3dLabel(HTuple scene3D, HTuple text, HTuple referencePoint, HTuple position, HTuple relatesTo, out HTuple labelIndex)
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_labeladd_scene_3d_labelAddScene3dLabelAddScene3dLabelAddScene3dLabeladd_scene_3d_label adds a label with the text in TextTextTextTexttexttext to the
3D scene Scene3DScene3DScene3DScene3Dscene3Dscene_3d and returns its index in LabelIndexLabelIndexLabelIndexLabelIndexlabelIndexlabel_index.
The reference point of the label must be given as [X,Y,Z] point in the
coordinate system of the 3D scene in ReferencePointReferencePointReferencePointReferencePointreferencePointreference_point.
It is valid to create labels without a reference
point by passing an empty tuple to ReferencePointReferencePointReferencePointReferencePointreferencePointreference_point, however
RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to must be set to 'window'"window""window""window""window""window" in this case
(see the description of RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to below).
If multiple label texts are supplied in TextTextTextTexttexttext, 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 PositionPositionPositionPositionpositionposition and RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to.
Labels can be positioned fixed in window coordinates or relative to the
projection of the reference point. The two parameters PositionPositionPositionPositionpositionposition
and RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to are used for positioning.
Fixed positioning
If RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to is set to 'window'"window""window""window""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] coordinates of the top left corner of the label in
PositionPositionPositionPositionpositionposition or use one of the predefined positions:
|
'top_left'"top_left""top_left""top_left""top_left""top_left" |
'top'"top""top""top""top""top" |
'top_right'"top_right""top_right""top_right""top_right""top_right" |
|
'left'"left""left""left""left""left" |
'center'"center""center""center""center""center" |
'right'"right""right""right""right""right" |
|
'bottom_left'"bottom_left""bottom_left""bottom_left""bottom_left""bottom_left" |
'bottom'"bottom""bottom""bottom""bottom""bottom" |
'bottom_right'"bottom_right""bottom_right""bottom_right""bottom_right""bottom_right"
|
Relative positioning
If RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to is set to 'point'"point""point""point""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] offset of the top left corner of the label in
PositionPositionPositionPositionpositionposition or use one of the predefined positions:
|
'top_left'"top_left""top_left""top_left""top_left""top_left" |
'top'"top""top""top""top""top" |
'top_right'"top_right""top_right""top_right""top_right""top_right" |
|
'left'"left""left""left""left""left" |
'center'"center""center""center""center""center" |
'right'"right""right""right""right""right" |
|
'bottom_left'"bottom_left""bottom_left""bottom_left""bottom_left""bottom_left" |
'bottom'"bottom""bottom""bottom""bottom""bottom" |
'bottom_right'"bottom_right""bottom_right""bottom_right""bottom_right""bottom_right"
|
The operator set_scene_3d_label_paramset_scene_3d_label_paramSetScene3dLabelParamSetScene3dLabelParamSetScene3dLabelParamset_scene_3d_label_param can be
used to change these values and to set other parameters such as the
label's color and font.
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
Scene3DScene3DScene3DScene3Dscene3Dscene_3d (input_control) scene_3d → HScene3D, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Handle of the 3D scene.
TextTextTextTexttexttext (input_control) string(-array) → HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Text of the label.
Default:
'label'
"label"
"label"
"label"
"label"
"label"
ReferencePointReferencePointReferencePointReferencePointreferencePointreference_point (input_control) point-array → HTupleSequence[Union[float, int]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)
Point of reference of the label.
Number of elements:
3
PositionPositionPositionPositionpositionposition (input_control) point-array → HTupleSequence[Union[float, int, str]]HTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)
Position of the label.
Default:
'top'
"top"
"top"
"top"
"top"
"top"
List of values:
'bottom'"bottom""bottom""bottom""bottom""bottom", 'bottom_left'"bottom_left""bottom_left""bottom_left""bottom_left""bottom_left", 'bottom_right'"bottom_right""bottom_right""bottom_right""bottom_right""bottom_right", 'center'"center""center""center""center""center", 'left'"left""left""left""left""left", 'right'"right""right""right""right""right", 'top'"top""top""top""top""top", 'top_left'"top_left""top_left""top_left""top_left""top_left", 'top_right'"top_right""top_right""top_right""top_right""top_right"
RelatesToRelatesToRelatesToRelatesTorelatesTorelates_to (input_control) string-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Indicates fixed or relative positioning.
Number of elements:
1
Default:
'point'
"point"
"point"
"point"
"point"
"point"
List of values:
'point'"point""point""point""point""point", 'window'"window""window""window""window""window"
LabelIndexLabelIndexLabelIndexLabelIndexlabelIndexlabel_index (output_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Index of the new label in the 3D scene.
Result
add_scene_3d_labeladd_scene_3d_labelAddScene3dLabelAddScene3dLabelAddScene3dLabeladd_scene_3d_label returns 2 (
H_MSG_TRUE)
if all parameters are correct.
If necessary, an exception is raised.
Possible Predecessors
create_scene_3dcreate_scene_3dCreateScene3dCreateScene3dCreateScene3dcreate_scene_3d
Possible Successors
set_scene_3d_label_paramset_scene_3d_label_paramSetScene3dLabelParamSetScene3dLabelParamSetScene3dLabelParamset_scene_3d_label_param
See also
remove_scene_3d_instanceremove_scene_3d_instanceRemoveScene3dInstanceRemoveScene3dInstanceRemoveScene3dInstanceremove_scene_3d_instance
Module
3D Metrology