====== View 4D ====== 

===== Overview =====
This component visualizes 3d objects in space and time. It is used to show a 3d-stick-figure for marker based motion analysis. But it is also possible to show arbitrary 3d objects like planes, spheres or bones. The scene can move with the time correspondig to the global time position defined by the [[http://nimue-platform.de/doku.php?id=guicomponents:timesynchronization|Time Synchronization component]]. Different views of the same scene at time are possible and a lot of specific 3d objects e.g. to visualize the ground, force plates, bottom of support areas, segments centre of mass points, ... are available. 

{{ :guicomponents:view3d.png?700 |}}

{{ :guicomponents:stick-figure.png?200|}}



===== Configuration =====

==== Markers and Points ====
<Marker>- and <Point>-elements visualize spherical objects. Many markerbased motion analysis measurement systems use retroreflective spherical markers, with different diameters, which can visualized with the <Marker>-element. All other points are visualized with the <Point>-element. <Marker>- and <Point>-element differs in the diameter and the default colors.

Each marker is defined as an child to the <MarkerSet>-element:

<code xml>
<MarkerSet name="Markers">
    <Marker name="ABC" origin="ABC"/>
</MarkerSet>
</code>

And each <Point>-element is defined as an child of the <PointSet>-element:

<code xml>
<PointSet name="Point">
       <Point name="D" origin="D"/>
</PointSet>
</code>

The <MarkerSet>- and the <PointSet>-element must have an attribute "name", which can be used by the graphical user interface to visualize and edit the visualization description.

A <Marker>-element is a specialized version of a <Point>-element. It defines a default behavoir to visualize sperical markers as used for marker based motion analysis measurement systems.

^ Attribute ^ Default ^ Description ^ Required ^
| radius | 0.00475mm | float | No ^
| color | gray | red, green, blue, grey | No ^
| origin | | | No ^
| visible | true | (not used) | No ^
| comment |  -  | comment | No ^

==== Connection Sets ====
A <Connection>-element visualizes the connection between two markers or points by a stick. Each connection is defined as a child of the <ConnectionSet>-element. The <ConnectionSet>-element is defined as an child of the <MarkerSet>-element.

<code xml>
<MarkerSet name="ABC">
   <ConnectionSet name="">
      <Connection name="AB" start="A" end="B"
   </ConnectionSet>
</MarkerSet>
</code>

==== Arrows ====
An <ArrowSet>-element defines a list of arrows and its child elements of type <Arrow> define this arrows.
===Attributes===
^ Attribute ^ Default ^ Description ^ Required ^
^ name | | name of the element | Yes |
^ start | | Startposition of the arrow. | Yes |
^ end | | Endposition of the arrow. | No | 
^ mid (not implemented yet)| | Alternative to the attributes start and end, the arrow can be defined by the attributes mid and vector (and optional length). The attribute mid defines the mid of the arrow. The direction is then defined by the attribute vector. The default length is 0.1m. This can be changed by the attribute length. | No |
^ vector | | Alternative to the attributes start and end, the arrow can be defined by start and vector. The attribute vector defines the direction of the arrow. The default length is 0.1m.  This can be changed by the attribute length. If the attribute "start" is not set, than (0,0,0) is used as start position. | No |
^ radius (not yet implemented) | 0.005 | Radius of the cylinder. | No |
^ length (not implemented yet) | 0.1m | This attribute is used optional in combination with the vector attribute. It defines the length of the arrow. The current implementation uses a fix length of 0.1m only. | No |
^ comment | | | No |
^ color | blue | green,red, green, blue, gray | No |
^ visible | true | | No | 

===Example===
<code xml>
<ArrowSet name="Arrows">         
       <Arrow name="MyArrow" start="RMEP" end="RLEP"/>     
</ArrowSet> 
</code>

==== Frames ====

The <Frame>-elements shows a coordinate system represented by three orthogonal vectors. The colors of these vectors are identical to the colors used by Vicon Nexus:

^ Axis ^ Color ^
| X | green ^
| Y | blue ^
| Z | red ^

The following attributes can be used to customize the frame visualization:

^ Attribute ^ Default ^ Unit ^ Description ^ Required ^
^ name | | String | Name of the element | Yes ^
^ xColor | red | RGB | color of the x-axis | No ^
^ yColor | green | RGB | color of the y-axis | No ^
^ zColor | blue | RGB | color of the z-axis | No ^
^ origin | | [m,m,m] | Vector-3d position of the coordinate system | No |
^ visible | true | boolean | | No ^
^ rotation | | | Quat4d or Matrix3d data | Yes ^
^ radius | 0.1 | [m] | Radius of the sphere to visualize the origin of the coordinate syste | No ^
^ length | 0.15 | [m] | length of the axis (not yet implemented) | No ^
^ diameter | length/20.0 | [m] | diamter of the coordinate system axes (not yet implemented) | No ^

Each <Frame>-element must be contained in a named <FrameSet>-element container. Have a look at the following example:

<code xml>
  <FrameSet>
        <Frame name="Mir"
               origin="MirPosition"
               rotation="Mir"/>
        <Frame name="Labor"
               origin="LaborPosition"
               rotation="Labor"/>
  </FrameSet>
</code>

==== Global Frame ====

The <GlobalFrame>-element visualized the global coordinate system, represented by three orthogonal vectors. The colors of these vectors are different to the colors used by Vicon Nexus:

^ Axis ^ Color ^
| X | red^
| Y | green^
| Z | blue^

<code xml>
    <GlobalFrame/>
</code>
==== Shapes ====
The <ShapeSet>-element defines a [[https://en.wikipedia.org/wiki/Wavefront_.obj_file|".obj"-file]] in the view-folder of the project, which includes one or more shapes. With the <Shape>-children elements these elements can be referenced and visualiszed at specified poses.

Example:

<code xml>
  <ShapeSet name="Golembones" filename="golembones.obj">
        <Shape name="head"
               origin="HeadPosition"
               rotation="HeadRotation"/>
  </ShapeSet>
</code>

Attributes of the <Shape>-elements:

^ Attribute ^ Default ^ Description ^ Required ^
^ name | default | Name of the element as defined in the ".obj"-file. | Yes |
^ origin |  | name of the timeserie, which defines the position, where to place the shape. | Yes |
^ rotation | | name of the timeserie which defines the orientation the shape is shown. | Yes |
^ scale | 0.2 | Scale applyed to the bone size | No |

The loader of the obj-fileformat is not complete. Only a [[https://download.java.net/media/java3d/javadoc/1.4.0/com/sun/j3d/loaders/objectfile/ObjectFile.html | subset]] of the identifiers are currently supported.
==== Example ====

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<?DOCTYPE View4d PUBLIC "-//Nimue//DTD View4d Def 1.0//EN" 
 "http://www.orat.de/Nimue/dtds/view4d_1.0.dtd"?>

<View4d name="Full Body">

 <MarkerSet name="Markers">
 
 <!-- thorax -->
 <Marker name="CLAV" origin="CLAV"/>
 <Marker name="STRN" origin="STRN"/>
 <Marker name="C7" origin="C7"/>
 <Marker name="RSHO" origin="RSHO"/> 
 <Marker name="LSHO" origin="LSHO"/> 
 <Marker name="T10" origin="T10"/> 
 
 <!-- pelvis -->
 <Marker name="SACR" origin="SACR"/>
 <Marker name="RASI" origin="RASI"/>
 <Marker name="LASI" origin="LASI"/>
 
 <!-- left leg -->
 <Marker name="LTHI" origin="LTHI"/>
 <Marker name="LKNE" origin="LKNE"/>
 <Marker name="LTIB" origin="LTIB"/>
 <Marker name="LANK" origin="LANK"/>
 <Marker name="LHEE" origin="LHEE"/>
 <Marker name="LTOE" origin="LTOE"/>
 
 <!-- right leg -->
 <Marker name="RTHI" origin="RTHI"/>
 <Marker name="RKNE" origin="RKNE"/>
 <Marker name="RTIB" origin="RTIB"/>
 <Marker name="RHEE" origin="RHEE"/>
 <Marker name="RTOE" origin="RTOE"/>
 <Marker name="RANK" origin="RANK"/>
 
 <!-- KAD -->
 <Marker name="LKD2" origin="LKD2"/>
 <Marker name="RKD2" origin="RKD2"/>
 <Marker name="RKAX" origin="RKAX"/>
 <Marker name="LKD1" origin="LKD1"/>
 <Marker name="RKD1" origin="RKD1"/>
 <Marker name="LKAX" origin="LKAX"/>
 <!--Marker name="PELF" origin="PELF"/--> 
 
 <!-- right arm -->
 <Marker name="RRAD" origin="RRAD"/>
 <Marker name="RULN" origin="RULN"/> 
 <Marker name="RELB" origin="RELB"/>
 <Marker name="RELBW" origin="RELBW"/> 
 <Marker name="RHUMS" origin="RHUMS"/>
 
 <!-- left arm -->
 <Marker name="LRAD" origin="LRAD"/>
 <Marker name="LULN" origin="LULN"/>
 <Marker name="LELB" origin="LELB"/>
 <Marker name="LELBW" origin="LELBW"/>
 <Marker name="LHUMS" origin="LHUMS"/>
 
 <!-- head -->
 <Marker name="RMAS" origin="RMAS"/>
 <Marker name="LMAS" origin="LMAS"/>
 <Marker name="HEAD" origin="HEAD"/>
 
 <ConnectionSet name="Connections">
 
 <!-- shoulder -->
 <Connection name="1" start="C7" end="RSHO"/>
 <Connection name="2" start="RSHO" end="CLAV"/> 
 <Connection name="3" start="CLAV" end="LSHO"/> 
 <Connection name="4" start="LSHO" end="C7"/>
 
 <!-- thorax -->
 <Connection name="5" start="CLAV" end="STRN"/> 
 <Connection name="6" start="C7" end="T10"/> 
 <Connection name="7" start="T10" end="SACR"/> 
 
 <!-- pelvis -->
 <Connection name="8" start="SACR" end="RASI"/> 
 <Connection name="9" start="RASI" end="LASI"/> 
 <Connection name="10" start="LASI" end="SACR"/> 
 
 <!-- right leg -->
 <Connection name="11" start="RASI" end="RTHI"/> 
 <Connection name="12" start="RTHI" end="RKNE"/> 
 <Connection name="13" start="RKNE" end="RTIB"/> 
 <Connection name="14" start="RTIB" end="RANK"/> 
 
 ...
 
 </MarkerSet> 

 <!--ConjunctRotationField name="RVectorField"
 origin="ThoraxUncalibratedPosition"
 rotation="ThoraxUncalibrated"/>

 <NavigationFrame name="Navigation"
 origin="RSHO"
 rotation="ThoraxUncalibrated"/-->
</View4d>
</code>