VSXML Documentation

KISTERS AG

Fileversion 17


Table of contents

Validation

Upgrade old VSXML

For hassle free validation of VSXML files the <VSXML> node is required to have the following three attributes defined:

<VSXML xmlns="http://viewer.kisters.de/VSXML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://viewer.kisters.de/VSXML VSXML.xsd" ...>
    <!-- Content -->
</VSXML>

Newer versions of 3DViewStation add these attributes per default, if you got a VSXML file without them please feel free to add them using any text editor.

Note

The xsi:schemaLocation="http://viewer.kisters.de/VSXML VSXML.xsd" specifies the location of the XSD file to validate against.
If the VSXML.xsd file is not located next to your VSXML file you have to either remove this attribute or update the path to the XSD file on you system.
Please just update the last part of the attribute's value and leave http://viewer.kisters.de/VSXML as it is.

Visual Studio Code

Necessary extension: XML Extension by Red Hat

RedHat's extension supports different ways to validate XML files as described in this GitHub wiki article.

This extension requires the <VSXML> node to contain all attributes described in Upgrade old VSXML.
If that's the case and the XSD file can be found, the extension should provide IntelliSense and auto validation capabilities automatically.

Notepad++

XSD validation can be done using the Xml Tools plugin, the latest version at the time of writing is version 3.1.1.1.
Go to Plugins -> Plugin manager -> Show Plugin manager, search for Xml Tools, check the plugin's list entry and click on Install.
Notepad++ will restart for installation.

If the VSXML contains an xsi:schemaLocation attribute (see above) the plugin automatically validates against the XSD file defined in it otherwise the plugin will prompt you to manually select an XSD file for validation.

Note For validation to work correctly please ensure that the <VSXML> node contains at least the xmlns="http://viewer.kisters.de/VSXML" attribute mentioned in Upgrade old VSXML.

VSXML

Attributes

Name Type
Version
[optional]
String
FileVersion
[optional]
Integer
Created
[optional]
String
UnitScale
[optional]
Float
Calibration2D
[optional]
Float
UpVector
[optional]
UpVector

Children

Name Type
BoundingBox
[optional]
BoundingBox
Node
[several]
Node

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML" Version="2021.0.119-85407f07" FileVersion="17" Created="Wed Jun  2 16:23:30 2021" UnitScale="1.000000" Calibration2D="1.000000" UpVector="Z">
  <BoundingBox Center="42.014015 28.500000 -45.155006" Extents="43.164040 28.845001 45.155006"/>
  <Node Name="RootNode" Type="Root" FileName="Test.3dvs"/>
</VSXML>

Node

Children

Name Type
Attribute
[optional]
[several]
Attribute
VectorExport
[optional]
VectorExport
Constraints
[optional]
Constraints
RenderState
[optional]
RenderState
BoundingBox
[optional]
BoundingBox
Node
[optional]
[several]
Node
PhysicalProperties
[optional]
PhysicalProperties
Animation
[optional]
Animation

Additional PMI node children

Name Type
Anchors
[optional]
PMIAnchors
LockVectors
[optional]
PMILockVectors
PMIText
[several]
PMIText
LeaderLines
[optional]
PolyLines
TextLines
[optional]
PolyLines
PMIReference
[several]
PMIReference

Additional Dimensioning node children

Name Type
HelperLines
[optional]
PolyLines

Attributes

Name Type Description
Id
[optional]
Integer Id of the node.
Type
[optional]
NodeType Type of the node
Root only allowed on first level!
CustomId
[optional]
String Custom node id.
Name
[optional]
String Node name
FileName
[optional]
FileName Relative or full file path for Desktop / ActiveX
Relative file path in ModelRepository for WebViewer
Importing 3DVS or native CAD Model to a node
Dimensioning
[optional]
Integer
Material
[optional]
Material
Color
[optional]
Color Color and transparency of the node
A
[optional]
Alpha Node alpha
Ignored if Color is used
RGB
[optional]
RGB Node color
Ignored if Color is used
ColorOverwrite
[optional]
ColorOverwrite Specifies which color is used
Geometry
[optional]
Integer Geometry Id
UnitScale
[optional]
Float
Transformation
[optional]
Transformation Transformation matrix
Translation
[optional]
Vector3f
Rotation
[optional]
Vector4f
Scale
[optional]
Vector3f
Show
[optional]
Bool Initial node visibility
If not defined default visisibility is true
You can set the initial visibility by VSXML Show attribute in UpdateScene or ImportVSXMLToNode. Default is true ("1") if not defined in VSXML.
Same attribute is used by VSXML in SetNodeProperties. No change of visibility if not defined in VSXML.
Ghost
[optional]
Bool
Replace
[optional]
Integer
TransparencyOverwrite
[optional]
Bool Specifies whether the node color is used regardless of transparency
Constraints
[optional]
Integer
CalloutId
[optional]
Integer

Additional PMI Node Attributes

Name Type
MarkupType
[optional]
Integer
For possible values see MarkupType
ScreenAligned
[optional]
Bool
Zoomable
[optional]
Bool
AlwaysOnTop
[optional]
Bool
ShowBackground
[optional]
Bool
Immutable
[optional]
Bool
AlwaysHighlightReference
[optional]
Bool
Frame
[optional]
Integer
ShowFrame
[optional]
Bool
FrameType
[optional]
Integer
For possible values see FrameType
Alignment
[optional]
Integer
For possible values see MarkupAlignment
CameraScaling
[optional]
Float
ParallelPosition
[optional]
Vector3f
BillboardPosition
[optional]
Vector3f
FixedPosition
[optional]
Vector2f
ParallelAnchor
[optional]
Vector3f
LineEnd
[optional]
Integer
BackgroundColor
[optional]
Color
TriangleColor
[optional]
Color
Label
[optional]
String
Anchor
[optional]
Integer
BackgroundVertices
[optional]
String

Additional 2D document attributes

Name Type
DocumentId
[optional]
Integer

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
  <Node CustomId="15ed4b28-0886-48c7-9949-34c38844786c" Name="Seen Root Node" Type="Root">
    <Node Name="Second level" Type="ProductOccurrence">
    	<Node Name="Dustcap1" Type="ProductOccurrence" Transformation="1 0 0 0 0 1 0 0 0 0 1 0 -300 -200 -100 1">
    		<Attribute key="InstanceName" value="sample1"/>
    		<!-- More Attributes -->
      	</Node>
  	</Node>
  	<!-- More Nodes -->
  </Node>
</VSXML>

Attribute

Note
3DViewStation versions prior to version 2020.1.385 require the following attributes to be lower cased, i.e. key and value.
From 2020.1.385 on you can use any casing.

Attributes

Name Type Description
Key String Attribute Name
Value String Attribute Value

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
    <Node>
        <Attribute Key="Cost" Value="156€"/>
        <Attribute Key="Product Number " Value="AD1874"/>
    </Node>
</VSXML>

VectorExport

Defines how a node is exported to DXF.

Attributes

Name Type Description
ExportColor
[optional]
Color
HLRMode
[optional]
HLRMode Hidden Line Removal
Block
[optional]
Block DXF group
(eg. AutoCAD can highlight this blocks)
Layer
[optional]
Layer DXF layer
LineReductionMode
[optional]
LineReductionMode

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
    <Node>
        <VectorExport IllustrationColor="#FFFFFFFF" HLRMode="Silhouette" Block="Part_127-1" Layer="Welding$59" LineReductionMode="None"/>
    </Node>
</VSXML>

Constraints

Defines which attributes can not be changed after loading.

Attributes

Name Type
Cut
[optional]
Bool
Show
[optional]
Bool
Color
[optional]
Bool
ColorOverwrite
[optional]
Bool
Material
[optional]
Bool
Transparency
[optional]
Bool
Ghost
[optional]
Bool
TransparencyOverwrite
[optional]
Bool

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
    <Node>
        <Constrains Cut="0" Show="0" Color="1" ColorOverwrite="1" Material="0" Transparency="0" Ghost="0"/>
    </Node>
</VSXML>

RenderState

Attributes

Name Type Description
Cuttable
[optional]
Bool Specifies if this geometry can be cut by sectioning.

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
    <Node>
        <RenderState Cuttable="0"/>
    </Node>
</VSXML>

BoundingBox

Attributes

Name Type
Center
[optional]
Vector3f
Extents
[optional]
Vector3f
Orientation
[optional]
Quaternion

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
    <Node>
        <BoundingBox Center="-63.5 3.17499 0" Extents="63.5 53.975 42.8625" Orientation="0 0 0 -1"/>
    </Node>
</VSXML>

VsxmlBoundingBox

Attributes

Name Type
Center
[optional]
Vector3f
Extents
[optional]
Vector3f

Example

<VSXML xmlns="http://viewer.kisters.de/VSXML">
  <BoundingBox Center="42.014015 28.500000 -45.155006" Extents="43.164040 28.845001 45.155006"/>
</VSXML>

PMIAnchors

Child Elements

Name Type
Anchor
[several]
PMIAnchor

PMIAnchor

Attributes

Name Type Description
ConnectedNode
[optional]
Integer Id of the connected node
EndType
[optional]
Integer
For possible values see AnchorEndType
ConnectionType
[optional]
Integer
For possible values see AnchorConnectionType
Color
[optional]
Color
Position
[optional]
Vector3f
KnockOut
[optional]
Bool
Visible
[optional]
Bool

PMILockVectors

Attributes

Name Type
Position
[optional]
Vector3f
Direction
[optional]
Vector3f
Normal
[optional]
Vector3f

PMIText

Attributes

Name Type
Size
[optional]
Float
GeometrySize
[optional]
Vector2f
UseModelUnits
[optional]
Bool
Color
[optional]
Color
Transformation
[optional]
Transformation
Font
[optional]
String
Content
[optional]
String
Attribute
[optional]
Integer

PolyLines

Child Elements

Name Type
Line
[optional]
PolyLine

PolyLine

Child Elements

Name Type
Vertices
[optional]
PolyLineVertices

Attributes

Name Type
IsLinelist
[optional]
Bool
Color
[optional]
Color

PolyLineVertices

Attributes

Name Type Description
NumVertices
[optional]
Integer
Coordinates
[optional]
String List of Vector3f elements separated by spaces.
Example: "1.0 2.0 3.0 1.0 2.0 3.0"

PMIReference

Attributes

Name Type
NodeId
[optional]
Integer
Type
[optional]
Integer
Indices
[optional]
String
List of integers, e.g. "1 2 3"
Color
[optional]
Color

PhysicalProperties

Attributes

Name Type
Density
[optional]
Float

Animation

Attributes

Name Type
RotationSpeed
[optional]
Float
CoordinateSystem
[optional]
UnsignedLong

Appendix

Types

Alpha

8bit hexadecimal value representing a color's alpha channel.

#AA

AnchorConnectionType

None = 0
Direct = 1
Rectangle = 2
Curve = 3
Distance = 4
Angle = 5

AnchorEndType

None = 0
Arrow = 1
AngledLine = 2
Cross = 3
Sphere = 4

Block

Limited to 31 characters to provide DXF R14 compatibility

Letters: A - Z

Numbers: 0 - 9

Special characters: "$", "_", "-"


Bool

"1" as true and "0" as false.


Color

For "Color" its an 32 bit ARGB color.

#AARRGGBB

HLRMode

All 			// Normal visibility of lines in 2D Export
SelfClipping	// The Node (Component) geometry itself is clipped.
  				// You cannot see lines of its back side.
   				// Lines generated for this Node will not be clipped by any other object
NoClipping		// No lines are clipped
Silhouette		// Only silhouete (outline) of Node geometry is visible,
      			// no clipping by other objects.

FrameType

Rectangle = 0
Circle = 1
Underline = 2

Layer

Limited to 31 characters to provide DXF R14 compatibility

Letters: A - Z

Numbers: 0 - 9

Special characters: "$", "_", "-"


LineReductionMode

None		// All lines visible
EdgesOnly	// Reducing lines by recognition of hard edges

MarkupAlignment

None = 0
Top = 1
Bottom = 2
Left = 3
Right = 4
TopBottom = 5
LeftRight = 6
Rectangle = 7
Circle = 8
NearToSolid = 9

Material

Chrome shiny
Steel
Steel polished
Gold shiny
Gold matt
Copper shiny
Copper matt
Aluminium
Plastic Rough
Plastic Smooth
Rubber
Mirror
Cabin Glass
Glass light
Solid Paint
Metallic Paint
Powdercoat

ColorOverwrite

Vertex    // Vertex color is used if present, otherwise node color.
Node      // Node color is used.
Material  // Material color is used if render mode is not set to "NoMaterial"
          // and the node has a material with color.
          // Otherwise node color is used.

NodeType

None
Root
ProductOccurrence
Ri_BrepModel
Ri_PolyBrepModel
Ri_Set
Ri_PolyWire
Ri_TessMarkup
Part
AxisRoot
Axis
PMIView
Annotation
AnnotationReference
AnnotationSet
Curve
Line
Plane
Direction
Point
PointSet
CoordinateSystem
Handle_Root
Handle_Arrow
Handle_Sphere
Handle_Curlyarrow
Solid
Wire
AnnotationItem
Markup_Text
Dimensioning
PointMarker
EdgeMarker
CircleMarker
AxisMarker
ReferenceLine
LineMarker
TriangleMesh
Markup_Circle
Markup_Rectangle
Markup_Freehand
CutGeometry_Surface
CutGeometry_Wire
PMIMarkup_Text
PMIMarkup_Dimension
PMIMarkup_Arrow
PMIMarkup_Balloon
PMIMarkup_CircleCenter
PMIMarkup_Coordinate
PMIMarkup_Datum
PMIMarkup_Fastener
PMIMarkup_Gdt
PMIMarkup_Locator
PMIMarkup_MeasurementPoint
PMIMarkup_Roughness
PMIMarkup_Welding
PMIMarkup_Table
PMIMarkup_Other
OffsetLine
CutGeometry_Set
MasterRootNode
MarkupSet
DataAnalysisResult
Markup
UnitTranslation
Document2D
AnimationCoordinateSystem
CustomCoordinateSystem
Highlight
SplitSession
SplitDirectionRoot
SplitFaceGroupUp
SplitFaceGroupDown
SplitFaceGroupUnassigned
GlareEffect
PMIMarkup_JT_Start
PMIMarkup_JT_CalloutDimension
PMIMarkup_JT_Centerline
PMIMarkup_JT_Chamfer
PMIMarkup_JT_CuttingPlaneSymbol
PMIMarkup_JT_DatumFeatureSymbol
PMIMarkup_JT_Dimension
PMIMarkup_JT_FeatureControlFrame
PMIMarkup_JT_Section
PMIMarkup_JT_SurfaceFinish
PMIMarkup_JT_ThreadFeature
PMIMarkup_JT_UserDefinedSymbol
PMIMarkup_JT_End

Markup Type

Note: Markup type values might be required in Integer form.
They are numbered in ascending order, i.e. Text has the value 1, Dimension has the value 2 and so on.

Text = 1
Dimension
Arrow
Balloon
Circlecenter
Coordinate
Datum
Fastener
GDT
Locator
MeasurementPoint
Roughness
Welding
Table
Other
AngleDimension

Quaternion

(XYZW)\begin{pmatrix} X \\ Y \\ Z \\ W \\ \end{pmatrix}

\Uparrow\Downarrow

X Y Z WX \ Y \ Z \ W

Example:

(0.2390.3700.0990.892)\begin{pmatrix} 0.239 \\ 0.370 \\ 0.099 \\ 0.892 \\ \end{pmatrix}

"0.239 0.370 0.099 0.892"

RGB

24 bit color value.

#RRGGBB

Transformation

4 x 4 Matrix written as space separated String. (Row 1 to 4) See [Transformation matrix](#Transformation matrix) for detailed information.

(m11m12m13m14m21m22m23m24m31m32m23m34m41m42m33m44)\begin{pmatrix} m _{11} & m _{12} & m _{13} & m _{14} \\ m _{21} & m _{22} & m _{23} & m _{24} \\ m _{31} & m _{32} & m _{23} & m _{34} \\ m _{41} & m _{42} & m _{33} & m _{44} \\ \end{pmatrix}

\Uparrow\Downarrow

m11 m12 m13 m14 m21 m22 m23 m24 m31 m32 m33 m34 m41 m42 m43 m44 m_{11} \ m _{12} \ m _{13} \ m _{14} \ m_{21} \ m _{22} \ m _{23} \ m _{24} \ m_{31} \ m _{32} \ m _{33} \ m _{34} \ m_{41} \ m _{42} \ m _{43} \ m _{44}

Example:

(10000100001010.50.055.551)\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 10.5 & 0.05 & -5.55 & 1 \\ \end{pmatrix}

"1 0 0 0 0 1 0 0 0 0 1 0 10.5 0.05 -5.55 1"

String

A simple string.


Float

A floating point number


UnsignedLong

A 64bit unsigned integer value.


UpVector

String value, valid values are


Vector2f

Vector of two floating point numbers.

Example

"1.0 2.0"


Vector3f

Vector of three floating point numbers.

Example

"1.0 2.0 3.0"


Vector4f

Vector of four floating point numbers.

Example

"1.0 2.0 3.0 4.0"


Calculations

Transformation matrix

Identity matrix (no rotation, no movement):

(1000010000100001)\begin{pmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{pmatrix}



Movement X, Y or Z axis change the last part:

(100001000010XYZ0)\begin{pmatrix} { \color{Red}1 } & { \color{Red}0 } & { \color{Red}0 } & 0 \\ { \color{Red}0 } & { \color{Red}1 } & { \color{Red}0 } & 0 \\ { \color{Red}0 } & { \color{Red}0 } & { \color{Red}1 } & 0 \\ { \color{Blue}X } & { \color{Blue}Y } & { \color{Blue}Z } & 0 \end{pmatrix}


For simple rotations change the first part of the transformation matrix.



Reference orientation (no rotation, identity matrix):

(100010001)\begin{pmatrix} { \color{Red}1 } & { \color{Red}0 } & { \color{Red}0 }\\ { \color{Red}0 } & { \color{Red}1 } & { \color{Red}0 }\\ { \color{Red}0 } & { \color{Red}0 } & { \color{Red}1 }\\ \end{pmatrix}

which equals:

row1 row2 row3
1 0 0 0 1 0 0 0 1


Rotation by 90 degrees about y axis:

(001010100)\begin{pmatrix} { \color{Red}0 } & { \color{Red}0 } & { \color{Red}1 }\\ { \color{Red}0 } & { \color{Red}1 } & { \color{Red}0 }\\ { \color{Red}-1 } & { \color{Red}0 } & { \color{Red}0 }\\ \end{pmatrix}

which equals:

row1 row2 row3
0 0 1 0 1 0 -1 0 0


Rotation by 180 degrees about y axis:

(100010001)\begin{pmatrix} { \color{Red}-1 } & { \color{Red}0 } & { \color{Red}0 }\\ { \color{Red}0 } & { \color{Red}1 } & { \color{Red}0 }\\ { \color{Red}0 } & { \color{Red}0 } & { \color{Red}-1 }\\ \end{pmatrix}

which equals:

row1 row2 row3
-1 0 1 0 1 0 0 0 -1


More samples for simple rotations

http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToMatrix/examples/index.htm

http://www.euclideanspace.com/maths/geometry/affine/matrix4x4/index.htm

Math on computing the rotation matrix You can compute rotation from any angle about an axis using this formula.

Basic rotations

A basic rotation (also called elemental rotation) is a rotation about one of the axes of the Coordinate system. The following three basic rotation matrices rotate vectors by an angle θ\theta about the x, y and z axis, in three dimensions, using the right hand rule - which codifies their alternating signs. (The same matrices can also represent a clockwise rotation of the axes)

Rx(θ)=(1000cosθsinθ0sinθcosθ)R_x(\theta)= \begin{pmatrix} 1 & 0 & 0 \\ 0 & cos\theta & -sin\theta \\ 0 & sin\theta & -cos\theta \end{pmatrix}

Ry(θ)=(cosθ0sinθ010sinθ0cosθ)R_y(\theta)= \begin{pmatrix} cos\theta & 0 & sin\theta \\ 0 & 1 & 0 \\ -sin\theta & 0 & cos\theta \end{pmatrix}

Rz(θ)=(cosθsinθ0sinθcosθ0001)R_z(\theta)= \begin{pmatrix} cos\theta & -sin\theta & 0 \\ sin\theta & cos\theta & 0 \\ 0 & 0 & 1 \end{pmatrix}

For column vectors, each of these basic vector rotations appears counter-clockwise when the axis about which they are located points toward the observer, the coordinate system is right-handed, and the angle θ\theta is positive. RzR_z, for instance, would rotate a vector aligned with the x-axis towards the y-axis, as can easily be checked by operating with RzR_z on the vector (1,0,0):

Rz(90°)=(100)=(cos90°sin90°0sin90°cos90°0001)(100)=(010100001)(100)=(010)R_z(90°)= \begin{pmatrix} 1 \\ 0 \\ 0 \end{pmatrix} = \begin{pmatrix} cos 90° & -sin 90° & 0 \\ sin 90° & cos 90° & 0 \\ 0 & 0 & 1 \end{pmatrix} \begin{pmatrix} 1 \\ 0 \\ 0 \end{pmatrix} = \begin{pmatrix} 0 & -1 & 0 \\ 1 & 0 & 0 \\ 0 & 0 & 1 \end{pmatrix} \begin{pmatrix} 1 \\ 0 \\ 0 \end{pmatrix} = \begin{pmatrix} 0 \\ 1 \\ 0 \end{pmatrix}

This is similar to the rotation produced by the above mentioned 2-D rotation matrix.