Get documents about "User's Guide User's Guide
Document Sample
User’s Guide
Last Modified May 3rd 2007
Introduction
The 3D Data Viewer (3DDV) is a tool that enables its users to visualize 3D models and interact with
elements within the model to view data plots related to the features of interest. Although the tool can
developed
be fitted to meet other needs, this tool was developed to provide researchers working on physical
models fitted with sensing devices a 3D virtual equivalent to better organize and understand the data
they are collecting. Users typically interact with the viewer by visualizing the 3D virtual model (rotating,
zooming in/out, etc) and clicking on the sensors of interest within the model to plot the data acquired,
overlaying plots as needed for comparison purposes.
The audience of this guide should be users who are preparing the model file that will be loaded by the
3DDV. This guide will focus on the file format of the model files.
Model Composition
As you know by now, the models in the 3D Data Viewer serve two purposes: the first is to visualize a
model in 3D space; the second is to plot data series for the shapes that have data associated with them.
As such the logical breakdown of structures within a the 3DDV models are standard shapes that only
eing
serve a visual purpose, and data shapes that in addition to being visualized, also have data associated
high
with them that can be plotted when the user requests it. The following is a flowchart showing a high-
level overview of the elements that compose a 3DDV model.
Model
Groups
Data
Shapes
Shapes
Geometry Data Geometry
describes
Each shape has a geometry associated with it which describes its appearance (is it a cube? cylinder? etc).
shapes.
Groups in the 3DDV are collections of shapes and data shapes. Each group’s appearance can be
controlled independently to show/hide it from the 3D view as well as control transparency settings.
an
Other than that groups have no effect on how data is organized or plotted as far as the 3DDV is
concerned. However, it’s important to think of how users will be interacting with the model when
2
deciding which shapes to group together. Questions to ask when grouping the shapes: Which shapes will
the user need to hide from the view in order to better visualize other shapes of interest? Do I want to
group all my sensors into one group to easily show and hide them? If the model is packed with sensors
does it make sense to group sensors by type?
Model Files
Typical models will have two paired files: a 3DDV model file with the *.m3dv extension (the m3dv file
format is described in the next section) and a data file containing the data that will be attached to the
data shapes. If the model file will only be used to represent a model in 3D space but won’t contain any
data shapes then a data file won’t be needed.
M3DV File Format
The file format for the model files loaded into the 3DDV is XML-based. These files have an extension
m3dv and can be opened in any text editor such as WordPad on Windows. With the text editor the user
can manually edit an existing file or even create a new model file. The data elements within the file have
a certain hierarchy that needs to be adhered to or the loader will not be able to read the files. A high
level overview of the model file hierarchy is as follows (the details of the each section are described later
in this guide):
• Model
o Title
o Data-File
File-Name
Delimiter
Skip-Rows
o Geometries
Cuboids
Cylinders
Spheres
o Groups
Name
Color
Border
Starter-Appearance
Shapes
• Geometry / Geometry-id
• Color
• Border
• Starter-Appearance
• Coordinates
• Metadata
• Series
3
If this is your first time to edit an XML file, it would probably be a good idea to read a short tutorial
before you start editing or creating m3dv files. At the time of this guide’s writing, W3Schools had a good
tutorial available at http://www.w3schools.com/xml/.
Model
The top element in the m3dv file hierarchy is the model element. This element contains all other sub-
elements that make-up the 3D model and data elements to be visualized in the viewer.
<model>
1 per file
<model>
<title>…</title>
<data-file>…</data-file>
<geometries>…</geometries>
<group>…</group>
</model>
title
required The name of the model that will be displayed in the viewer.
text <title>My title</title>
data-file
optional The data-file is a block that defines the data-file that will be used for data elements
block within the model. If this block isn’t defined, then the viewer can still be used to visualize
the models in 3D but the plotting capabilities will not be used.
see the data-file section for the detailed specification
geometries
optional If some of the shapes that will be displayed in the viewer share a common geometry,
block one definition can be made in the geometries block and referenced later from the shape
definitions rather than defining each geometry multiple times for each shape.
see the geometries section for the detailed specification
group
required Each set of shapes will be grouped together in a group block. At least one group block is
block necessary per model.
see the group section for the detailed specification
Data-File
Each m3dv file can be associated with multiple data files. The numerical data that will be plotted is
stored in the separate data files. It is assumed that the data files will be arranged in columns separated
by some delimiter (typically a tab or comma) and that the first row in the data file will contain the
header names for the data columns. Each data file can optionally have a second row, immediately
following the column headings, containing the units for each data column.
4
Note: The header names in the first row from the data file will be used when defining the data
shapes that will plot data.
A sample tab-delimited data file:
Time PPT1 PPT2 A1
sec KPa KPa g
20.83333 0 0 0
20.90278 -0.00961 -0.00919 0
20.97222 -0.03846 -0.00919 0.009779
21.04167 0 0.018368 0.029339
21.11111 -0.00961 -0.01838 0.01956
21.18056 0.009613 0 0.048898
21.25 0 -0.00919 0.009779
<data-file>
0 to many per model
<data-file>
<file-name>…</file-name>
<delimiter>…</delimiter>
<skip-rows>…</skip-rows>
</data-file>
file-name
required The name of the data file. If the file is located in the same directory as the model file,
text then the name and extension is all that is needed:
<file-name>filename.txt</file-name>
Otherwise, the full path is required when entering the file name:
<file-name>C:\My Data Directory\filename.txt</file-name>
delimeter
optional The delimiter character that separates columns in the data file. The delimiter entry can
text be TAB, COMMA, or any other character (although it is recommended to stick with
either tab or comma). Examples:
<delimiter>TAB</delimiter>
<delimiter>COMMA</delimiter>
<delimiter>q</delimiter>
skip-rows
th
optional If this option is set, the data reader will skip to every n row when plotting the data. For
number the most part, this option shouldn’t be needed, but if the data file you are using as input
has a lot of values and is slowing down the application when you plot the data, skipping
data rows will make things faster and more responsive. For instance if you set the value
to 10 then the program will skip 10 rows of data for every reading it makes. E.g.:
<skip-rows>10</skip-rows>
5
Geometries
look
A geometry in the 3D Data Viewer terminology is the definition of how a shape will loo as well as its
dimensions. However, the location of the shape is defined at the shape block and not the geometry one.
Two shapes can share the same geometry definition even though they might be located at different
locations in the model since coordinates are defined at the shape level (see the shape section for more
geometries
details). In fact, if two shapes have identical geometries it is preferable to share the geometry between
them rather than defining a separate one for each one as this brings several benefits: decreases the size
of the model file increasing the speed at which a model file is read by the 3DDV; increases ththe
keeps
performance of the viewer since it keep less copies of geometries in memory.
The geometries block in the model definition is a collection of the shared geometries that will be used
if y
across several shapes. For readability purposes, i a geometry will only be used by a single shape, then it
is preferred to define it at the shape level block and not the shared geometries one (although if that’s
how it is defined, technically there’s nothing that will stop the program from working).
a
Geometries in the 3D Data Viewer only consist of a basic set of primitive 3D geometries. The currently
supported geometries are:
• Cubes
• Cuboids (3D rectangles)
• Cylinders
• Spheres
follows:
The geometries block can have different geometries from the list above defined in its block, as follow
<geometries>
<cube>…</cube>
<sphere>…</sphere>
<sphere>…</sphere>
etc ...
</geometries>
The order in which the geometries appear within the block is unimportant.
The following are the definitions of the
<cube> 0 to many per geometries block, 0 or 1 per shape
<cube>
<id>…</id>
<size>…</size>
</cube>
id
6
optional This is the field that shapes use to reference shared geometries. If a geometry is defined
text if
within the shape block then this field is not needed. Otherwise, i this geometry is
defined in the geometries block then the id is required. E.g.:
shared-cube</id>
<id>shared
size
required The length of any one of the edges. All edges are equal in size.
number 5</size>
<size>5</size
<cuboid>
0 to many per geometries block, 0 or 1 per shape
<cuboid>
<id>…</id>
sizex>
<sizex>…</sizex>
sizey>
<sizey>…</sizey>
sizez>
<sizez>…</sizez>
</cuboid>
id
optional This is the field that shapes use to reference shared geometries. If a geometry is defined
text if
within the shape block then this field is not needed. Otherwise, i this geometry is
defined in the geometries block then the id is required. E.g.:
<id>shared-cuboid</id>
<id>shared
sizex
required The length the edges along the X axis.
number 5</sizex>
<sizex>5</sizex
sizey
required The length the edges along the Y axis.
number 4</sizey>
<sizey>4</sizey
sizez
required The length the edges along the Z axis.
number 7</sizez>
<sizez>7</sizez
<cylinder>
0 to many per geometries block, 0 or 1 per shape
<cylinder>
<id>…</id>
radius>
<radius>…</radius
</cylinder>
id
7
optional This is the field that shapes use to reference shared geometries. If a geometry is defined
text if
within the shape block then this field is not needed. Otherwise, i this geometry is
defined in the geometries block then the id is required. E.g.:
<id>shared-cylinder</id>
<id>shared
radius
required cylinder.
The radius of the cylinder
number 5</radius>
<radius>5</radius
<sphere>
0 to many per geometries block, 0 or 1 per shape
<sphere>
<id>…</id>
radius>
<radius>…</radius>
</sphere>
id
optional This is the field that shapes use to reference shared geometries. If a geometry is defined
text if
within the shape block then this field is not needed. Otherwise, i this geometry is
defined in the geometries block then the id is required. E.g.:
ometries
<id>shared-sphere</id>
<id>shared
radius
required sphere.
The radius of the sphere
number 5</radius>
<radius>5</radius
Appearance Settings
Appearance settings are a set of parameters that can be applied to a group block or a shape block.
sub-shapes
When applied to a group it’s automatically applied to all sub shapes within the group. When applied to a
shape it applies only to that shape, and overrides any appearance setting the shape inherited from the
group it belongs to.
<color>…</color>
<border>
<show>…</show>
<color>…</color>
</border>
<transparency>…</transparency>
appearance>…</starter-appearance>
<starter-appearance>…</starter
color
optional Applies a color to the shape(s) this appearance setting is defined for. If no color is set
text either at the group or shape level, then the default color is used (gray). Colors are set
8
similar to how they are in HTML files. For a complete description of how to define a
color in HTML please visit http://www.w3schools.com/html/html_colors.asp. The
following example sets the color of the shape(s) to white.
<color>#FFFFFF</color>
border: show
optional Shapes can be displayed with a line border visible around them. The options are either
text yes or no. The following set’s the border visible for a group/shape:
<border>
<show>yes</show>
</border>
border: color
optional If the border is set to be shown, the color can be set. If the border is visible but no
text border color is set, the default color of black is used. Setting the color uses the same
rules as the general color property described above. The following sets the border color
to yellow:
<border>
<show>yes</show>
<color> #FFFF00</color>
</border>
transparency
optional When a shape or group is set to be transparent by the user, the default transparency
number used is 50%. This can be customized to make objects more or less opaque when the
transparency is set. The lower the number, the less transparent the shape/group
becomes. The range is from 0-100. E.g:
<transparency>80</transparency>
starter-appearance
optional The default initial state groups and shapes are displayed in when the model is first
text loaded is solid. This can be changed for groups and shapes to one of the three following
choices:
<starter-appearance>SOLID</starter-appearance>
<starter-appearance>LINE</starter-appearance>
<starter-appearance>TRANSPARENT</starter-appearance>
Group
As described previously, groups are a collection of shapes grouped to control their appearance
collectively. It’s no surprise then that most of the parameters in a group relate to the appearance
settings.
9
<group> 1 to many per model
<group>
<name>…</name>
[appearance settings, described previously]
<shape>…</shape>
<shape>…</shape>
</group>
name
required The name of a group will be displayed in the appearance control panel in the 3D Data
text Viewer interface. This should be a short identifier (one or two words only due to the
space constraints in the display area).
<name>Group 1</name>
shape
required Each group block should have at least one shape block.
block see the shape section for the detailed specification
Shape
Shapes are objects that will be displayed in the 3D view display area. Shapes can be defined with data
properties which will enable the user to select the shape and plot its data.
<shape>
1 to many per group
<shape>
<name>…</name>
<geometryid>…</geometryid>
[one of the geometries described in the geometries section]
[appearance settings described in the appearance settings section]
<coordinates>
<x>…</x>
<y>…</y>
<z>…</z>
</coordinates>
<coordinates-end>
<x>…</x>
<y>…</y>
<z>…</z>
</coordinates-end>
<meta>
<name>…</name>
<value>…</value>
</meta>
<series>
<x>…</x>
10
<y>…</y>
</series>
</shape>
name
optional The name of a shape will be displayed as metadata. However, this name will only be
text shown if there is other metadata associated with the shape in question (see the shape
meta property).
<name>Shape 1</name>
geometryid
required The id identifier set for a geometry declared in the geometries section. This will tell the
text model loader to use the shared geometry rather than try to declare a new one. If the
block
shape will be using it’s own geometry and not one of the shared ones, then the
<geometryid> attribute can be substituted for a geometry definition (cube, cuboid,
cylinder, sphere, etc). Examples:
<geometryid>shared-cube</geometryid>
or
<cube>
<size>3</size>
</cube>
coordinates
required Each shape must have a coordinates block specifying its location. Each axis needs to be
block filled out. E.g.:
<coordinates>
<x>0</x>
<y>0</y>
<z>0</z>
</coordinates>
meta
optional As the user hovers their mouse over shapes, if a shape has metadata associated with it
block the 3DDV will display to the sidebar. This can be any kind of information and several
meta blocks can be defined per shape. The name is a label that will appear before the
value to describe what it is. The following shows metadata specifying the manufacturer
of a shape displayed on the screen:
<meta>
<name>Manufacturer</name>
<value>Acme Manufacturing, Inc</value>
</meta>
series
optional The way to declare a data shape, allowing the user to select and plot data, is to add the
block optional series property. This property is tied to the header information provided in the
data file (see the data-file section). The 2D plot can have any of the columns on the X
and Y axis. However, the name entered under each axis must have a matching data
11
column in the data file. The following shows an example of a plot that relies on two
columns in the data file, time and sensor1, to construct a time series plot.
<series>
<x>time</x>
<y>sensor1</y>
</series>
12
Related docs
