Documentation
Overview
Let's see how KEna looks at startup:
It is an empty window with menu and toolbar. To create anything
useful, we have to open a library by selecting option
File | Open library .
We can see that the bed on the left is inside transparent blue
box. This means that we have clicked it and marked for insertion into
the model. If we then click in the main window, the bed is added to
the model.
clicking in the main window. Library window also has more scrollbars
than it is usual. Scrollbars marked with
'm' in the bottom right corner
move image, while the scrollbar marked with
'z' is used for zooming.
After we insert element to model, the main window looks similar to
the one below:
If we
didn't do it so far, it is time to save the model. After that we can
view 3D image:
We can see that here we have even two more scrollbars. They are used
to rotate the view.
How to begin
This section describes few simple steps for starting a new project.
- At startup we usually first open one or more libraries with predefined
elements. This can be done with menu option
File | Open
library . Two libraries are included in the distribution:
basic.k1l and furnitureDemo.k1l
- To insert elements from library to model we should first
click an element in the library. When it is marked with a
transparent blue box, we can insert it into the model by
clicking in the model window.
- Once an element is inserted into the model, we can change its
position by dragging it with mouse. If we press the right mouse
button while dragging the element, it is rotated by 90 degrees.
- Options, which are used often, are also available in a context
menu. Available options depend also on the element, which is selected,
because elements may add options for editing parameters.
- To view our work in 3D view, we can select menu option
Tools | 3D
View or click a tool bar button.
- 3D scene may be moved with scrollbars or mouse wheel and
modification keys (Shift, Alt, Ctrl).
- By default a headlight (directional light) in 3D view is used to
illuminate the world. With menu option Options | Headlight On/Off in 3D window we can
turn it off. All elements become black in such case. For more
detailed lightening we can insert lights from library into the
model. Lights can be found in both libraries included in the
distribution. If both headlight and additional light are active, 3D
scene is to bright. In such case we disable the headlight.
User interface
The main application menu
The following menu options are available:
File - this menu contains standard options. The only important
exception is option 'Open Library' , which is usually the
first option used, when we start a new project. We can use it to open
one or several libraries of elements.
Edit - this menu also contains standard options.
View - this menu currently contains only option to
scale 2D view to whole window.
Tools - this menu contains the following options:
3D view - this option opens 3D window and displays
current model in 3D.
Select language - this option can be used, when
we want to select different language for user interface. Currently
supported languages are English, Slovenian and partially
Macedonian language.
Plugins - this menu contains options provided by
plugins. Originally it is empty.
Help - everybody knows this one.
Tool bar
Toolbar contains most often used commands. If we place mouse cursor
above button and wait a second or two, a tool tip is displayed, which
explains button's purpose. Please see description of commands in menu
description above.
Navigation
2D and 3D views can be moved, rotated and zoomed with scrollbars on the
right side and at the bottom of the window. But there exists also
faster way. We can move around with mouse wheel and meta keys.
2D view
- mouse wheel - move up / down
- mouse wheel + Alt - move left / right
- mouse wheel + Ctrl - zoom in / out
3D view
- mouse wheel - move up / down
- mouse wheel + Alt - move left / right
- mouse wheel + Ctrl - zoom in / out
- mouse wheel + Ctrl + Shift - rotate around X axis
- mouse wheel + Shift - rotate around Z axis
Library internals
KEna library has exactly the same format as any model. This means
that any model can also be used as a library. The only limitation of
the current version of KEna is that we have to manually make a 3D
view of the model in the same directory as k1m
file is located. This simply means that we display 3D view of the
model with menu option Tools | 3D View. File with the same name as
model file and extension x3d is created in
directory called 3d . Then we use some file
management tool (Windows Explorer for example) to copy the file to the
directory, where the model is located.
It is also true the other way around - any library can be opened in
KEna as model and edited. The only information lost in this process
are XML comments. That's the reason why we should enter comments into
description tags of library and elements.
Since editing capabilities of KEna are limited (we can not add or
remove parameters for example) library is usually edited in text
editor. A good text editor like vi or Emacs is recommended. It
is also possible to use Notepad, but any editor, which supports XML
format, will make a job much easier.
Library format overview
KEna library uses XML format. XML is not described here, but there are
many tutorials available on the net. The first line of library file
needs no explanation:
<?xml version="1.0" encoding="UTF-8"?>
Then the following elements are used:
- root element
- description
- application parameters
- class elements
- object elements
They are described in the following sections.
The root element
The root element is named 'K1Model'. It must contain the following
attributes:
name - library name
author - author's name
defaultNamespace - all elements, which have no
namespace defined, are automatically put into this namespace. Namespace
is used to prevent confusion, when elements in different libraries
have the same name and are used in the same model. For example, if
your library contains element with name "House", and you also want to
use your friend's library, which also contains an element with name
"House", the program can not know, which house is used. That's the
point, where namespaces are used. It is recommended to use the same
convention as used in Java language: Namespace should be always
written in all-lowercase ASCII letters and should be one of the
top-level domain names, currently com, edu, gov, mil, net, org, or
one of the English two-letter codes identifying countries as
specified in ISO Standard 3166, 1981.
Subsequent components of the namespace vary according to your
naming conventions. Example: mycompany.com.furniture.kitchens
Example of root element:
<K3Model name='LivingRooms' ver='1.1'
author='marko.klopcic@volja.net'
defaultNamespace='si.mk.k1demo'>
Description element
This element contains description of the library in human readable
text. It is intended for library users and designers. The element
should contain attribute short , which value should be one
short statement describing the library. If we want to provide more
detailed description, we can enter it to element's body as
CDATA section. Usually the short description is intended
for users, while detailed description should describe inner working of
the element in more detail and is therefore more useful to designers.
Example:
<description short='Demo Library, ver 1.3, (C) Marko Klopcic, 1007.'>
<![CDATA[Details go here. You may add <html> tag at the
beginning to turn html formatting on.]]>
</description>
Application parameters
This XML element defines parameters, which are
available to main application and plugins. They are automatically put
to default namespace. Example of such parameter is information about
customer, if the model contains furniture for sale. These parameters
are not visible to classes and objects.
Example:
<appParams>
<param name = "customerName" type = "string" value = "Jaka"/>
<param name = "customerAddress" type = "string" value = "1000 Ljubljana"/>
</appParams>
For syntax of parameter definition see the next section.
Classes and objects
There are two kinds of elements in K1 library - K1Class and
K1Object. Elements of type K1Class are not visible, but serve as
prototypes for creating visible elements of type K1Object.
It is possible to have a library without classes, but usually the
good designer will extract common properties of objects into
reusable classes.
Since the format of class and object elements is almost identical,
only class elements will be described.
K1Class and K1Object elements
The root element describes name, version and inheritance
relation. Example:
<K1Class name="Table" ver="1.0" base="FurnitureBase">
<K1Object name="Table" ver="1.0" base="FurnitureBase">
Description of attributes:
'name' - defines element identifier
'ver' - defines element version
'base'
- defines base element. This means that current element is a base
element with additional parameters and geometry. This relation is very
similar to inheritance in Java and similar languages. Parameters can
also be set in derived class, while geometry is always added. Derived
class can not remove geometry from base class.
Child elements
Both elements have the same child elements:
- description - describes the element
- params - contains elements parameters
- parts - contains references to elements, which are used as
subparts of this element
- view2d - contains 2D description of an element
- view3d - contains 3D description of an element
- propertiesUI - description of dialog for editing parameters
- plugins - data intended for plugins
<description>
This element describes element. It's syntax is the same as for
description element of the
library.
<params>
This section contains parameters, which are later used in other
sections, especially in <view2d> and <view3d>. It
contains three subsections: <public>,
<protected>, and
<private> . Parameters defined in
<public> section are accessible to other
elements, parameters defined in <protected>
section are accessible to derived elements, and parameters defined
in <private> section are visible only in the
element itself.
Parameters are defined by <param> XML tag with
attributes:
'name' - contains parameter id
'type' - defines parameter type
'value - defines parameter value
The following parameter types are available:
double - floating point values. This is the
default type, if attribute 'type' is omitted.
int - integer type (32 bit signed)
string - string type, for text
clor3f - color type, consisting of 3 floating
point RGB values in the range [0..1]. Example: "0 0.7 0.25"
tuple3d - this type consists of 3 double precision
values. Usually it is used for coordinates.
tuple4d - - this type consists of 4 double precision
values. Usually it is used for rotations, where the first three
values define vector and the fourth one defines angle of rotation
around the vector.
tuple3f - this type consists of 3 single precision
values.
tuple4f - - this type consists of 4 single precision
values.
All types, which consist of multiple numbers, can also be
referenced by their components. For example, if we have parameter
<param name = "translation" type="tuple3d" value="0 2 0"/>,
we can write:
<param name = "distance" value="translation.x"/>
Components are referenced as follows:
- tuple3d, tuple3f: x, y, z. Example: translation.x
- tuple4d, tuple4f: x, y, z, a. Example: rotation.a
- color3f : r, g, b. Example: color.g
Note: Because of parser limitations in current version of
the program, multi component values must be referenced by their
components, if used in the 'value' attribute. See parameter
'color' in the next example.
Example of params section:
<params>
<public>
<param name = "w" value="1"/>
<param name = "h" value="1"/>
<param name = "d" value="1.45"/>
<param name = "translation" type="tuple3d" value="0 2 0"/>
<param name = "rotation" type="tuple4d" value="0 1 0 1.571"/>
<param name = "color" type="color3f" value = "0.85 0.85 0.85"/>
<param name = "text" type = "string" value='"B4009"'/>
</public>
<protected>
<param name = "weight" value="2.645"/>
<param name = "doorColor" type="color3f"
value="color.r color.g color.b"/>
</protected>
<private>
<param name = "light" type='int' value="1"/>
</private>
</params>
Special parameters
Every element must have the following parameters:
- elemQName - qualified name of the element including namespace
(string type)
- w - element's width
- h - element's height
- d - element's depth
- translation - element's position
- rotation - element's rotation
- overlapControl - if set to '1', the program takes care in
view 2D, that the element does not intersect with other
elements. This significantly speeds up design in some cases.
If they are not defined in the library, they are automatically
added by the program. Please note that it is designer's
responsibility that the element's with equals the visual one. It is
possible to set parameter 'w' to one value, but then not to use it
in <view3d> at all. Program KEna will not complain in such case,
but it is considered a bad element design.
There are also additional parameters, which have additional
support by the program:
- color - if defined in the library, it is possible to set this
value in the standard Properties dialog. Its usage depends on
element, but as its name suggest it usually defines element's color.
- text - if defined in the library, it is possible to set this
value in the standard Properties dialog. Its usage depends on
element, but usually it is displayed in 2D and/or 3D view.
- bottom - defines lower bounds used in overlapping control. Set
to 0 in most cases.
- localH - defines height used for overlapping control. Set to
h in most cases.
- __defaultY - When element is inserted from library to 2D view,
value of this parameter is used as its Y position (usually distance from
the floor)
All parameters, which start with double underscore character, are
reserved. Therefore it is strongly discouraged to use double
underscore character prefix for user defined parameters. This
prefix may only be used by developers of KEna program.
parts
This section references existing elements, which are used as
building blocks of the element. Let's see an example, where we used
the existing element Box with parameters w, h, d and
color to create a new element called Tower .
<K1Class name='Tower' ...
<parts>
<element name="bottomBox" src="Box">
<set name = "translation" value="0 0 0"/>
<set name = "w" value="w"/>
<set name = "h" value="(h/3)"/>
<set name = "d" value="d"/>
<set name = "color" value="color.r color.g color.b"/>
</element>
<element name="middleBox" src="Box">
<set name = "translation" value="0 (h/3) 0"/>
<set name = "w" value="(w/2 + h / 2)"/>
<set name = "h" value="(h/3)"/>
<set name = "d" value="(d/2)"/>
<set name = "color" value="color.r color.g color.b"/>
</element>
<element name="topBox" src="Box">
<set name = "translation" value="0 (2*h/3) 0"/>
<set name = "w" value="(w/4)"/>
<set name = "h" value="(h/3)"/>
<set name = "d" value="(d/4)"/>
<set name = "color" value="color.r color.g color.b"/>
</element>
</parts>
...
</K1Class>
Attribute 'src' of tag <element>
must reference the existing element.
Attribute 'name' of tag <set>
refers to public parameter of the element Box ,
while names of parameters in expression defined by
'value' attribute refer to parameters of the composed
element. For example:
<set name = "h" value="(h/3)"/>
This statement sets the height of included element (Box in our
case) to 1/3 of the height of the composed element (Tower in our
case).
view2d
It is important to understand that 2D and 3D view of an element
may not be related. This means that even if we define 3D view,
element is not visible in 2D view until we define its 2D
view. This approach has a disadvantage of double work, because we
have to define 2 views of one element. However, we also have more
freedom. For example, 2D view may display elements as symbols or
provide additional information important for design, which should not
be visible in 3D view.
2D view of an element is described in the SVG format. This format
is standardized, so we can find more information about it on the
net. However, this version of KEna program supports only very
limited set of drawing commands:
- polygon - polygon shape
- line - simple line
- ellipse - ellipse (can also display circle)
Examples:
<ellipse id="tloris" fill="none" stroke="black" stroke-width="0.02"
cx="(w/2)" cy="(-d/2)" rx="(w/2)" ry="(d/2)"/>
<polygon id="tloris" fill="none" stroke="black" stroke-width="0.02"
points="$ptLBB.x,$ptLBB.z $ptLBF.x,$ptLBF.z $ptRBF.x,$ptRBF.z
$ptRBB.x,$ptRBB.z"/>
<line x1="ptLBF.x" y1="ptLBF.z" x2="ptRBF.x" y2="ptRBF.z" stroke="red"
stroke-width="0.02"/>
All shapes, which have attribute id = "tloris" are
used in overlapping control. Parameters ptLBB, ptLBF, ... in the
example must be defined in <params> section.
The following predefined colors are available for stroke:
- black
- blue
- cyan
- dark-gray
- gray
- green
- light-gray
- magenta
- orange
- pink
- red
- white
- yellow
- aqua
- fuchsia
- lime
- maroon
- navy
- olive
- purple
- silver
- teal
See also also section 6 Basic HTML data types
of HTML 4.01 SpecificationIn the example above we can
also see referencing of element's parameters:
- numerical values in strings - they are referenced by prefixing
with '$' sign. See tag
polygon , attribute
points above.
- numerical values in single value expressions - they are
referenced directly. See tag
line above.
- string values - they have to be prefixed with '%' sign. See
ktext tag below.
There is also one non-standard command used for text,
ktext .
Example:
<ktext text="%(text)" stroke="black"
font-size="0.07" x =".03" y = "(-.15)"/>
<ktext text="$w x $d" stroke="black"
font-size=".05" x =".03" y = "(-.05)"/>
Element's origin
When designing a new element, a question arises, where should we
define elements origin, that's point with coordinate x = 0, y =
0. There are actually 2 main possibilities, each with its
advantages and disadvantages. The first possibility is to put
origin to one of the elements corners. This simplifies design,
because we do not have to divide its width and depth by 2 all the
time. When we use snapping, it can be the same as elements
resolution. For example, if elements are designed with 1cm
accuracy, snapping of 1 cm (0.01 m) is good for correct positioning
of all elements, including the ones with odd width or depth. If we
have origin in the center of the element, then we need to have
snapping set to 0.5 cm. However, central origin has other
advantages. Rotating of the element works nicer, and alignments in
the properties dialog work better regardless of element's
orientation.
Central origin is preferred, but program KEna enables us to put
origin to other parts of element, if we have a good reason.
view3D
This section contains 3D description of elements. KEna was designed
to be neutral to 3D format used in this section, but current
version only supports XML formats. If we want to use the built-in
viewer, only part of X3D specification is currently supported. It
is always possible to open the generated 3D output file in other
viewers, which implement X3D
specification.
The following X3D nodes are currently supported:
Examples:
Draw contents of 'text' parameter:
<view3D format="x3d">
<Transform translation='0 -.20 0'>
<Shape>
<Appearance>
<Material diffuseColor='1 0 0'/>
</Appearance>
<Text string='"%(text)"'>
<FontStyle size='0.1'/>
</Text>
</Shape>
</Transform>
</view3D>
Draw box of size w x wallW x d :
<view3D format='x3d'>
<Transform translation="$(w/2) $(wallW/2) $(-d/2)">
<Shape>
<Box size="$w $wallW $d"/>
<Appearance>
<Material diffuseColor="%color"/>
</Appearance>
</Shape>
</Transform>
</view3D>
Parameters are referenced the same way as in view2d .
propertiesUI
Usually we want to change element's parameters during model
design. KEna by default provides dialog for editing default parameters
x, y, z, w, h, d, rotation , and two additional ones,
which are used by most elements: color and
text .
When this is not enough, and often it is not, designer of elements can
give user the possibility to edit other values. This section is
intended for definition of additional editing dialogs for editing
parameters. Users can access these dialogs from a context menu.
Currently there are only limited possibilities for dialog
design, so result may not be visually pleasant. However, all parameter
types are supported. Example:
<propertiesUI>
<panel name = "SizePanel" layout="boxX">
<editor type = "doubleEditor" text = "Width:" param = "w"/>
<editor type = "doubleEditor" text = "Depth:" param = "d"/>
</panel>
<panel name = "ColorPanel" layout="boxY">
<editor type = "colorEditor" text = "Color: " param = "color"/>
</panel>
<dialog name = "basicProperties" title = "Size & Color">
<include panel="SizePanel"/>
<rigidArea y="15"/>
<hr/>
<rigidArea y="15"/>
<include panel="ColorPanel"/>
<rigidArea y="15"/>
<hr/>
</dialog>
</propertiesUI>
<panel> tags define panels with editors. The
'name' attribute is used as panel's ID later when dialog is
composed. 'layout' attribute can be either 'boxX' or
'boxY' . The first value places editors next to each other
from left to right, while 'boxY' places them in top down
direction.
<editor> tag defines editor to be used (attribute
'type' ), text shown to the user (attribute
'text' ), and name of parameter to be set by the specified
editor (attribute 'param' ).
<dialog> tag composes dialog. It includes panels
defined above (tag <include> , and defines empty
space (tag <rigidArea> ) between them. We can also
insert horizontal lines (tag <hr> ). Panels are
always placed from top to bottom.
plugins
KEna supports plugins. This section may contain any information
required by plugins. For details please refer to plugins manual,
when available.
Special elements
Some elements have special status. They contain information needed
by all elements or general information for presentation, which
applies to whole 3D scene. Their names start with double underscore
character. Please do not use this prefix for your elements, because
it is reserved for use by developers of KEna.
__modelProperties
Class with name __modelProperties contains parameters, which
are visible to all elements in the same namespace. If we combine
elements from multiple namespaces in the model, there is also one
__modelProperties class for each namespace. It is automatically
copied from the library where element was inserted from to the model.
Example of such parameter is flag for displaying names of elements in
3D view. Instead of setting this value for all elements, we can turn
it on with single setting:
<param name = "showNames" type = "int" value = "1"/>
The following parameters are used by library browser:
- backgroundColor - color used for background in the library
- minX - min value of X scrollbar
- maxX - max value of X scrollbar
- minY - min value of Y scrollbar
- maxY - max value of Y scrollbar
- minZ - min value of Z scrollbar
- maxZ - max value of Z scrollbar
- initX - initial value of X scrollbar
- initY - initial value of X scrollbar
- initZ - initial value of X scrollbar
Example:
<param name = "minX" value = "-10"/>
__header
This class is used as header of the output file describing 3D view. It
may not use parameters defined in __modelProperties in the library. Namespace of
__header element changes
to the namespace of the model, when it is inserted to the model. It is
inserted into the model automatically, when the first element is
inserted.
__scene_header
This class describes scene properties of 3D view. See __header for description of parameters and
insertion.
__selector
This class enables selection of elements in the library. It must be
part of every element, which we want to be selectable. If some element
does not contain '__selector', it is visible in the library but can
not be selected and inserted into the model. See demo libraries for
definition and example of usage.
Tutorial
Template class
The first step, when creating a new element is usually copy pasting a
similar element or template. One of possible templates is given below:
<K1Class name="Box" base="DemoBase">
<params>
<public>
<param name="w" value='1'/>
<param name="h" value='2'/>
<param name="d" value='3'/>
<param name = "color" type="color3f" value="1 0 1"/>
</public>
</params>
<view2d>
<polygon id="tloris" fill="none" stroke="black" stroke-width="0.02"
points="$(-w/2),$(-d/2) $(-w/2),$(d/2) $(w/2),$(d/2)
$(w/2),$(-d/2)"/>
<ktext text="Box" stroke="black" font-size="0.07" x ="0.0"
y = "(-.15)"/>
<ktext text="$w x $d" stroke="black" font-size=".05" x ="0.0"
y = "(-.05)"/>
</view2d>
<view3d format="x3d">
<Transform translation="0 $(h/2) 0">
<Shape>
<Appearance>
<Material diffuseColor="%color"/>
</Appearance>
<Box size='$w $h $d'/>
</Shape>
</Transform>
</view3d>
</K1Class>
Examples of elements based on this template can be seen in
basic.k1l library.
Template object
Although object elements can contain all data and do not need to be
based on a class, it is a good design principle to create a class
first, and then set only parameters in objects. Simple example is
given below:
<K1Object name="box" base = "Box">
<params>
<public>
<param name="w" value='2'/>
</public>
</params>
</K1Object>
Import from other applications
Since there is currently no support for design of visual presentations
in KEna, we can use other applications for this task and then
copy-paste data to KEna library. Unfortunately X3D format is not
widely supported, but VRML is very similar to X3D, and it is widely
supported. So we can export model from other application in VRML
format, then edit it in text editor, and copy paste it to KEna library.
This technique has been used with Art Of Illusion to
create some elements in the furniture library, which you can find in
the distribution.
Library design by example
This section contains simple library with comments, which explain the
most important features.
<?xml version="1.0" encoding="UTF-8"?>
<K1Model name='Furniture' ver='0.1' author='Marko Klopcic'
defaultNamespace='si.mk.k1demo'>
<classes>
<K1Class name="__modelProperties">
</K1Class>
<!-- This special class defines information, which is used as --
-- header in 3D output file. -->
<K1Class name="__header">
<view3d format="x3d">
<head>
<meta name='filename' content='sobe.x1l'/>
<meta name='author' content='Marko Klopcic'/>
<meta name='translator' content='/'/>
<meta name='created' content='30 August 2007'/>
<meta name='revised' content='30 August 2007'/>
<meta name='description' content='Library for general rooms.'/>
<meta name='url' content=''/>
<meta name='generator' content='KEna'/>
<meta name='license' content='../../license.html'/>
</head>
</view3d>
</K1Class>
<!-- This special class describes general scene information
according to X3D specification -->
<K1Class name="__scene_header">
<view3d format="x3d">
<Background skyAngle='1.309, 1.571'
skyColor='1 1 1'
groundColor='0 0 0'/>
<NavigationInfo type='"EXAMINE" "ANY"'/>
</view3d>
</K1Class>
<!-- User defined class follows. By convention class names
start with capital letter. -->
<K1Class name="Box">
<params>
<public>
<param name="w" value='1'/>
<param name="h" value='2'/>
<param name="d" value='3'/>
</public>
</params>
<view2d>
<polygon id="tloris" fill="none" stroke="black"
stroke-width="0.02"
points="0,$(-d) 0,0 $w,0 $w,$(-d)"/>
<ktext text="Box" stroke="black" font-size="0.07" x =".03"
y = "(-.15)"/>
<ktext text="$w x $d" stroke="black" font-size=".05" x =".03"
y = "(-.05)"/>
</view2d>
<view3d format="x3d">
<Shape>
<Appearance>
<Material diffuseColor='.1 .9 .9'/>
</Appearance>
<Box size='$w $h $d'/>
</Shape>
</view3d>
</K1Class>
</classes>
<objects>
<!-- Object based on class is defined here - it only changes
parameters. By convention object names start with lower case
letter -->
<K1Object name="box" base = "Box">
<params>
<public>
<param name="w" value='2'/>
</public>
</params>
</K1Object>
</objects>
</K1Model>
|