STK Graphics PrimitivesSend comments on this topic.
IAgStkGraphicsTextBatchPrimitive Interface

Description

Renders one or more strings in the 3D scene.

For best performance, avoid creating lots of batches with only a few strings each. See the Batching Performance Overview.

Public Methods

Public Method SetDefines the positions and text of strings in a text batch. The strings are rendered in the primitive's Reference Frame.
Public Method SetCartographicFor convenience. Defines the positions and text of strings in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set.
Public Method SetCartographicWithOptionalParametersFor convenience. Defines the positions, text, and optional parameters of strings in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set.
Public Method SetCartographicWithOptionalParametersAndRenderPassFor convenience. Defines the positions, text, and optional parameters of strings in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set.
Public Method SetPartialUpdates a subset of positions and/or text in a text batch.
Public Method SetPartialCartographicFor convenience. Updates a subset of positions and/or text in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set Partial.
Public Method SetPartialCartographicWithIndicesOrderFor convenience. Updates a subset of positions and/or text in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set Partial.
Public Method SetPartialCartographicWithOptionalParametersFor convenience. Updates a subset of positions, text, and/or per-string parameters in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set Partial.
Public Method SetPartialCartographicWithOptionalParametersIndicesOrderAndRenderPassFor convenience. Updates a subset of positions, text, and/or per-string parameters in a text batch using Cartographic positions. This is equivalent to converting each position in positions to Cartesian and calling Set Partial.
Public Method SetPartialWithIndicesOrderUpdates a subset of positions and/or text in a text batch.
Public Method SetPartialWithOptionalParametersUpdates a subset of positions, text, and/or optional per-string parameters in a text batch.
Public Method SetPartialWithOptionalParametersIndicesOrderAndRenderPassUpdates a subset of positions, text, and/or optional per-string parameters in a text batch.
Public Method SetWithOptionalParametersDefines the positions, text, and optional parameters of strings in a text batch. The strings are rendered in the primitive's Reference Frame.
Public Method SetWithOptionalParametersAndRenderPassDefines the positions, text, and optional parameters of strings in a text batch. The strings are rendered in the primitive's Reference Frame. renderPassHint is provided for efficiency.

Public Properties

Public Property AlignToPixelGets or sets whether the screen space position of each string is aligned to a pixel.
Public Property BoundingSphereScaleGets or sets the scale applied to the radius of this primitive's bounding sphere.
Public Property DistanceDisplayConditionPerStringGets or sets a Distance Display Condition that is evaluated per string in the text batch during rendering. This is different than Display Condition, which is evaluated once for the entire text batch. When DistanceDisplayConditionPerString is null, no per string display condition is evaluated.
Public Property FontGets the font used to render the text batch.
Public Property OutlineColorGets or sets the text's outline color.
Public Property OutlineTranslucencyGets or sets the text's outline translucency. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.
Public Property PerItemPickingEnabledGets or sets whether individual text indices will be included in the PickResults returned from the Scene's Pick method. Each text index that is picked will be returned as a BatchPrimitiveIndex.
Public Property RenderInScreenSpaceGets or sets whether the primitive is positioned and rendered in screen space coordinates.
Public Property SetHintGets the primitive's Set Hint. See the Set Hint Performance Overview for selecting an appropriate value to construct the primitive with.
Public Property TextureFilterGets or sets the filter used to filter the texture-based Font.

Interfaces

Implemented Interface
IAgStkGraphicsPrimitive

CoClasses that Implement IAgStkGraphicsTextBatchPrimitive

Example

Draw a set of strings
[C#]
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;

Array text = new object[]
{
    "Philadelphia",
    "Washington, D.C.",
    "New Orleans",
    "San Jose"
};

Array positions = new object[]
{
    39.88, -75.25, 0,    // Philadelphia
    38.85, -77.04, 0, // Washington, D.C.   
    29.98, -90.25, 0, // New Orleans
    37.37, -121.92, 0    // San Jose
};

IAgStkGraphicsGraphicsFont font = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("MS Sans Serif", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, true);
IAgStkGraphicsTextBatchPrimitive textBatch = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font);
((IAgStkGraphicsPrimitive)textBatch).Color = Color.White;
textBatch.OutlineColor = Color.Red;
textBatch.SetCartographic("Earth", ref positions, ref text);

manager.Primitives.Add((IAgStkGraphicsPrimitive)textBatch);
Draw a set of uniquely colored strings
[C#]
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
Array strings = new object[]
{
    "San Francisco",
    "Sacramento",
    "Los Angeles",
    "San Diego"
};

Array positions = new object[]
{
    37.62, -122.38, 0.0,
    38.52, -121.50, 0.0,
    33.93, -118.40, 0.0,
    32.82, -117.13, 0.0
};

Array colors = new object[]
{
    (uint)Color.Red.ToArgb(),
    (uint)Color.Green.ToArgb(),
    (uint)Color.Blue.ToArgb(),
    (uint)Color.White.ToArgb()
};

IAgStkGraphicsTextBatchPrimitiveOptionalParameters parameters = manager.Initializers.TextBatchPrimitiveOptionalParameters.Initialize();
parameters.SetColors(ref colors);

IAgStkGraphicsGraphicsFont font = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("MS Sans Serif", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, false);
IAgStkGraphicsTextBatchPrimitive textBatch = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font);
textBatch.SetCartographicWithOptionalParameters("Earth", ref positions, ref strings, parameters);

manager.Primitives.Add((IAgStkGraphicsPrimitive)textBatch);
Draw a set of strings in various languages
[C#]
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
//
// Create the strings
//
char[] german = { '\u0057', '\u0069', '\u006C', '\u006B', '\u006F', '\u006D', '\u006D', '\u0065', '\u006E' };
char[] french = { '\u0042', '\u0069', '\u0065', '\u006E', '\u0076', '\u0065', '\u006E', '\u0075', '\u0065', '\u0020' };
char[] portuguese = { '\u0042', '\u0065', '\u006D', '\u002D', '\u0076', '\u0069', '\u006E', '\u0064', '\u006F' };
char[] english = { '\u0057', '\u0065', '\u006C', '\u0063', '\u006F', '\u006D', '\u0065' };
char[] russian = { '\u0414', '\u043E', '\u0431', '\u0440', '\u043E', '\u0020', '\u043F', '\u043E', 
                   '\u0436', '\u0430', '\u043B', '\u043E', '\u0432', '\u0430', '\u0442', '\u044C' };
char[] arabic = {  '\u0623', '\u0647', '\u0644', '\u0627', '\u064B', '\u0020', '\u0648', '\u0020', 
                   '\u0633', '\u0647', '\u0644', '\u0627', '\u064B' };

Array text = new object[]
{
    new string(german),
    new string(french),
    new string(portuguese),
    new string(english),
    new string(russian),
    new string(arabic)
};

//
// Create the positions
//
Array positions = new object[]
{
    51.00, 09.00, 0.0,
    46.00, 02.00, 0.0,
    39.50, -08.00, 0.0,
    38.00, -97.00, 0.0,
    60.00, 100.00, 0.0,
    25.00, 45.00, 0.0
};

IAgStkGraphicsGraphicsFont font = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("Unicode", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, true);
IAgStkGraphicsTextBatchPrimitive textBatch = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font);
textBatch.SetCartographic("Earth", ref positions, ref text);

manager.Primitives.Add((IAgStkGraphicsPrimitive)textBatch);
Draw a set of strings
[Visual Basic .NET]
Dim manager As IAgStkGraphicsSceneManager = DirectCast(root.CurrentScenario, IAgScenario).SceneManager

Dim text As Array = New Object() {"Philadelphia", "Washington, D.C.", "New Orleans", "San Jose"}

Dim positions As Array = New Object() {39.88, -75.25, 0, _
                                       38.85, -77.04, 0, _
                                       29.98, -90.25, 0, _
                                      37.37, -121.92, 0}

Dim font As IAgStkGraphicsGraphicsFont = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("MS Sans Serif", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, True)
Dim textBatch As IAgStkGraphicsTextBatchPrimitive = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font)
DirectCast(textBatch, IAgStkGraphicsPrimitive).Color = Color.White
textBatch.OutlineColor = Color.Red
textBatch.SetCartographic("Earth", positions, text)

manager.Primitives.Add(DirectCast(textBatch, IAgStkGraphicsPrimitive))
Draw a set of uniquely colored strings
[Visual Basic .NET]
Dim manager As IAgStkGraphicsSceneManager = DirectCast(root.CurrentScenario, IAgScenario).SceneManager
Dim strings As Array = New Object() {"San Francisco", "Sacramento", "Los Angeles", "San Diego"}

Dim positions As Array = New Object() _
{ _
    37.62, -122.38, 0.0, _
    38.52, -121.5, 0.0, _
    33.93, -118.4, 0.0, _
    32.82, -117.13, 0.0 _
}

Dim colors As Array = New Object() _
{ _
    Color.Red.ToArgb(), _
    Color.Green.ToArgb(), _
    Color.Blue.ToArgb(), _
   Color.White.ToArgb() _
}

Dim parameters As IAgStkGraphicsTextBatchPrimitiveOptionalParameters = manager.Initializers.TextBatchPrimitiveOptionalParameters.Initialize()
parameters.SetColors(colors)

Dim font As IAgStkGraphicsGraphicsFont = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("MS Sans Serif", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, False)
Dim textBatch As IAgStkGraphicsTextBatchPrimitive = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font)
textBatch.SetCartographicWithOptionalParameters("Earth", positions, strings, parameters)

manager.Primitives.Add(DirectCast(textBatch, IAgStkGraphicsPrimitive))
Draw a set of strings in various languages
[Visual Basic .NET]
Dim manager As IAgStkGraphicsSceneManager = DirectCast(root.CurrentScenario, IAgScenario).SceneManager
'
' Create the strings
'
Dim german As Char() = {ChrW(87), ChrW(105), ChrW(108), ChrW(107), ChrW(111), ChrW(109), ChrW(109), ChrW(101), ChrW(110)}
Dim french As Char() = {ChrW(66), ChrW(105), ChrW(101), ChrW(110), ChrW(118), ChrW(101), ChrW(110), ChrW(117), ChrW(101), ChrW(32)}
Dim portuguese As Char() = {ChrW(66), ChrW(101), ChrW(109), ChrW(45), ChrW(118), ChrW(105), ChrW(110), ChrW(100), ChrW(111)}
Dim english As Char() = {ChrW(87), ChrW(101), ChrW(108), ChrW(99), ChrW(111), ChrW(109), ChrW(101)}
Dim russian As Char() = {ChrW(1044), ChrW(1086), ChrW(1073), ChrW(1088), ChrW(1086), ChrW(32), ChrW(1087), ChrW(1086), _
                         ChrW(1078), ChrW(1072), ChrW(1083), ChrW(1086), ChrW(1074), ChrW(1072), ChrW(1090), ChrW(1100)}
Dim arabic As Char() = {ChrW(1571), ChrW(1607), ChrW(1604), ChrW(1575), ChrW(1611), ChrW(32), ChrW(1608), ChrW(32), _
                        ChrW(1587), ChrW(1607), ChrW(1604), ChrW(1575), ChrW(1611)}

Dim text As Array = New Object() _
{ _
    New String(german), _
    New String(french), _
    New String(portuguese), _
    New String(english), _
    New String(russian), _
    New String(arabic) _
}

'
' Create the positions
'
Dim positions As Array = New Object() {51.0, 9.0, 0.0, _
                                       46.0, 2.0, 0.0, _
                                       39.5, -8.0, 0.0, _
                                       38.0, -97.0, 0.0, _
                                       60.0, 100.0, 0.0, _
                                       25.0, 45.0, 0.0}

Dim font As IAgStkGraphicsGraphicsFont = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline("Unicode", 12, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, True)
Dim textBatch As IAgStkGraphicsTextBatchPrimitive = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font)
textBatch.SetCartographic("Earth", positions, text)

manager.Primitives.Add(DirectCast(textBatch, IAgStkGraphicsPrimitive))
Draw a new Text Primitive
[Python - STK API]
# IAgScenario scenario: Scenario object
manager = scenario.SceneManager
font = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline('MS Sans Serif', 24, AgEStkGraphicsFontStyle.eStkGraphicsFontStyleBold, True)
textBatch = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font)
textBatch.SetCartographic('Earth', [[0], [0], [0]], ['Example Text'])  # Lat, Lon, Alt
manager.Primitives.Add(textBatch)
Draw a new Text Primitive
[MATLAB]
% IAgScenario scenario: Scenario object
manager = scenario.SceneManager;
font = manager.Initializers.GraphicsFont.InitializeWithNameSizeFontStyleOutline('MS Sans Serif', 24, 'eStkGraphicsFontStyleBold', true);
textBatch = manager.Initializers.TextBatchPrimitive.InitializeWithGraphicsFont(font);
textBatch.SetCartographic('Earth', {0;0;0}, {'Example Text'});   % Lat, Lon, Alt
manager.Primitives.Add(textBatch);

See Also

© 2024 Analytical Graphics, Inc. All Rights Reserved.