vrml(3) - Linux man page

Name

VRML - Specification independent VRML methods (1.0, 2.0, 97)

Synopsis

use VRML;

$vrml = new VRML(2);
$vrml->browser('Cosmo Player 2.0','Netscape');
$vrml->at('-15 0 20');
$vrml->box('5 3 1','yellow');
$vrml->back;
$vrml->print;
$vrml->save;

OR with the same result

use VRML;

VRML->new(2)
->browser('Cosmo Player 2.0','Netscape')
->at('-15 0 20')->box('5 3 1','yellow')->back
->print->save;

Description

These modules were conceived for the production of VRML worlds on WWW servers via GCI and/or for generating abstract worlds. They are the clarity of Perl scripts with VRML code to increase and (hopefully) for VRML beginners the entrance in VRML facilitate. In the following the modules are described briefly.

VRML::Base

contains base functionality such as a producing, an outputting and saving. It represents the base class for all other modules

VRML::VRML1

combines several VRML 1.0 nodes into complex methods - e.g. geometric shapes inclusive there material. This module accepts angle data in degrees and as material color names. The methods have the same names as in the VRML specification (if meaningfully), are however in lower case.

VRML::VRML1::Standard

implemented only the VRML 1.0 nodes. All method names are identical (in the way of writing) with those of the VRML specification. The parameters are arranged after the frequency of their use (subjective estimate). This module is possibly omitted in the next version. The production of the VRML nodes takes over then VRML::Base.

VRML::VRML2

combines several VRML 2.0 nodes into complex methods - e.g. geometric shapes inclusive there material. This module accepts angle data in degrees and as material color names. The methods have the same names as in the VRML specification (if meaningfully), are however in lower case. The names are also as far as possible identical to those of the module VRML::VRML1 . Thus the user between the VRML versions which can be produced can switch.

Contains for example $in{ VRML } '1' or '2' (e.g. via CGI ), then only the following line at the start of the Perl script must be inserted.

new VRML($in{'VRML'})

VRML::VRML2::Standard

implemented only the VRML 2.0 nodes. All method names are identical (in the way of writing) with those the VRML specification. The parameters are arranged after the frequency of their use (subjective estimate) This module is possibly omitted in the next version. The production of the VRML nodes takes over then VRML::Base.

VRML::Color

contains the color names and conversion functions.

The VRML methods are at present identically in the modules VRML::VRML1 .pm and VRML::VRML2 .pm implemented. The basic methods like "new", "print" or "save" are in the module VRML::Base described.

Description

The methods of this module are easier to use than the VRML::*::Standard methods because the methods are on a higher level. For example you can use X11 color names and it's simple to apply textures to an object. All angles could be assigned in degrees.

If a method does the same like its VRML pedant then it has the same name but in lowercase (e.g. box). The open part of a group method ends with a _begin (e.g. anchor_begin). The closing part ends with an _end (e.g. anchor_end). For a detailed description how the generated node works, take a look at the VRML 2.0 specification on VAG .

Following methods are currently implemented. (Values in '...' must be strings!)

Groups

begin

begin('comment')

Before you use an geometry or transform method please call this method. It's necessary to calculate something at the end.

Example:

new VRML
->begin
  ->at('0 0.1 -0.3')
    ->sphere(1,'red')
  ->back
->end
->print;

end

end('comment')

After "end" there should no geometry or transformation. This method completes the calculations of viewpoints etc.

at('type=value','type=value', ...)

is the short version of the method "transform_begin". It has the same parameters as "transform_begin".

Example:

$vrml
->at('0 2 0')
  ->sphere(0.5,'red')
->back

back

is the short version of the method "transform_end".

anchor_begin

anchor_begin('url', 'description', 'parameter', 'bboxSize', 'bboxCenter')

url         MFString []
description SFString ""
parameter   MFString []
bboxSize    SFVec3f  undef
bboxCenter  SFVec3f  '0 0 0'

Example:

$vrml
->anchor_begin('http://www.gfz-potsdam.de/~palm/vrmlperl/',
  'VRML-Perl Moduls', 'target=_blank')
  ->sphere(1,'blue')
->anchor_end;

anchor_end

close "anchor_begin".

billboard_begin

billboard_begin('axisOfRotation', 'bboxSize', 'bboxCenter')

axisOfRotation  SFVec3f  '0 1 0'
bboxSize        SFVec3f  undef
bboxCenter      SFVec3f  '0 0 0'

billboard_end

close "billboard_begin".

collision_begin

collision_begin(collide, proxy, 'bboxSize', 'bboxCenter')

collide    SFBool  1
proxy      SFNode  NULL
bboxSize   SFVec3f undef
bboxCenter SFVec3f '0 0 0'

Example:

$vrml
->collision_begin(1, sub{$vrml->box('5 1 0.01')})
  ->text('collide','yellow',1,'MIDDLE')
->collision_end

collision_end

close "collision_begin".

group_begin('comment')

Example:

$vrml
->group_begin
  ->sphere(1,'red')
->group_end

group_end

close "group_begin".

lod_begin

lod_begin('range', 'center')

range  MFFloat []
center SFVec3f '0 0 0'

Example:

$vrml
->lod_begin('30')
  ->text('good readable')
  ->group_begin->group_end # empty Group
->lod_end

lod_end

close "lod_begin".

switch_begin

switch_begin(whichChoice)

whichChoice SFInt32 -1

switch_end

close "switch_begin".

transform_begin

transform_begin('type=value','type=value', ...)

Where type can be:

t = translation
r = rotation
c = center
s = scale
so = scaleOrientation
bbs = bboxSize
bbc = bboxCenter

Example:

$vrml
->transform_begin('t=0 1 0','r=180')
  ->cone('0.5 2','red')
->transform_end

transform_end

close "transform_begin".

inline

inline('url', 'bboxSize', 'bboxCenter')

url        MFString []
bboxSize   SFVec3f  undef
bboxCenter SFVec3f  '0 0 0'

Independent Methods

background

background( frontUrl => '...', leftUrl => '...', rightUrl => '...', backUrl => '...', bottomUrl => '...', topUrl => '...', skyColor => '...', skyAngle => '...', groundColor => '...', groundAngle => '...' )

frontUrl    MFString []
leftUrl     MFString []
rightUrl    MFString []
backUrl     MFString []
bottomUrl   MFString []
topUrl      MFString []
skyColor    MFColor  ['0 0 0']
skyAngle    MFFloat  []
groundColor MFColor  []
groundAngle MFFloat  []

This is a parameter hash. Only use the parts you need.

Example:

$vrml->background(skyColor => 'lightblue',
                  frontUrl => 'http://www.yourdomain.de/bg/berge.gif');

backgroundcolor

backgroundcolor('skyColor', 'groundColor')

skyColor     SFColor  '0 0 0'
groundColor  SFColor  '0 0 0'

is the short version of "background". It specifies only colors.

Example:

$vrml->backgroundcolor('lightblue');

backgroundimage

backgroundimage('url')

url SFString ""

is the short version of "background". It needs only one image. The given Url will assigned to all parts of the background cube.

Example:

$vrml->backgroundimage('http://www.yourdomain.de/bg/stars.gif');

title

title('string')

string SFString ""

Example:

$vrml->title('My virtual world');

info

info('string')

string MFString []

Example:

$vrml->info('last update: 8.05.1997');

worldinfo

worldinfo('title', 'info')

title  SFString ""
info   MFString []

combines "title" and "info".

navigationinfo

navigationinfo('type', speed, headlight, visibilityLimit, avatarSize)

type         MFEnum     ['WALK', 'ANY'] # ANY, WALK, FLY, EXAMINE, NONE
speed        SFFloat    1.0
headlight    SFBool     1
visibilityLimit SFFloat 0.0
avatarSize   MFFloat    [0.25, 1.6, 0.75]

Example:

$vrml->navigationinfo('WALK', 1.5, 0, 1000);

viewpoint_begin

starts the hidden calculation of viewpoint center and distance for the method "viewpoint_auto_set()". It collects also the viepoints to place they in the first part of the VRML source.

viewpoint

viewpoint('description', 'position', 'orientation', fieldOfView, jump)

description SFString          ""
position    SFVec3f           0 0 10
orientation SFRotation/SFEnum 0 0 1 0 # FRONT, LEFT, BACK, RIGHT, TOP, BOTTOM
fieldOfView SFFloat           45 # Grad
jump        SFBool            1

Example:

$vrml->viewpoint('Start','0 0 0','0 0 -1 0',60);

is the same like

$vrml->viewpoint('Start',undef,'FRONT',60);

viewpoint_set

viewpoint_set('center', distance, fieldOfView, avatarSize)

center       SFVec3f '0 0 0'
distance     SFFloat 10
fieldOfView  SFFloat 45 # Grad
avatarSize   MFFloat [0.25, 1.6, 0.75]

places six viewpoints around the center.

viewpoint_auto_set

sets all parameters of "viewpoint_set" automatically.

viewpoint_end

close "viewpoint_begin".

Shapes

box

box('size', 'appearance')

size       SFVec3f  '2 2 2' # width height depth
appearance SFString ""      # see Appearance

cone

cone('bottomRadius height', 'appearance')

bottomRadius height SFVec2f '1 2'
appearance          SFString "" # see Appearance

cylinder

cylinder('radius height', 'appearance')

radius height SFVec2f  '1 2'
appearance    SFString "" # see Appearance

line

line('from', 'to', radius, 'appearance', 'path')

from        SFVec3f   ""
to          SFVec3f   ""
radius      SFFloat   0 # 0 = haarline
appearance  SFString  ""
path        SFEnum    "" # XYZ, XZY, YXZ, YZX, ZXY, ZYX

draws a line (cylinder) between two points with a given radius. If radius is '0' only a hairline will be printed. The last parameter specifies the devolution along the axes. An empty stands for direct connection.

Example:

new VRML(2)
->begin
  ->line('1 -1 1', '-3 2 2', 0.03, 'red', 'XZY')
  ->line('1 -1 1', '-3 2 2', 0.03, 'white')
->end
->print;

pyramid

pyramid('size', 'appearance')

size       SFVec3f  '2 2 2' # width height depth
appearance SFString ""      # see Appearance

Example:

$vrml->pyramid('1 1 1','blue,green,red,yellow,white');

sphere

sphere(radius, 'appearance')

radius     SFFloat  1
appearance SFString "" # see Appearance

elevationgrid

elevationgrid(height, color, xDimension, zDimension, xSpacing, zSpacing, creaseAngle, colorPerVertex, solid)

height          MFFloat  []
color           MFColor  [] # resp. material and color
xDimension      SFInt32  0
zDimension      SFInt32  0
xSpacing        SFFloat  1.0
zSpacing        SFFloat  1.0
creaseAngle     SFFloat  0
colorPerVertex  SFBool   1
solid           SFBool   0

If color is not a reference of an ARRAY it would be assumed that color is the appearance.

Example:

open(FILE,"<height.txt");
my @height = <FILE>;
open(COL,"<color.txt");
my @color = <COL>;
$vrml->navigationinfo(["EXAMINE","FLY"],200)
     ->viewpoint("Top","1900 6000 1900","TOP")
     ->elevationgrid(\@height, \@color, undef, undef, 250, undef, 0)
     ->print;

text

text('string', 'appearance', 'font', 'align')

string     MFString []
appearance SFString "" # see Appearance
font       SFString '1 SERIF PLAIN'
align      SFEnum   'BEGIN' # BEGIN, MIDDLE, END

billtext

billtext('string', 'appearance', 'font', 'align')

string     MFString []
appearance SFString "" # see Appearance
font       SFString '1 SERIF PLAIN'
align      SFEnum   'BEGIN' # BEGIN, MIDDLE, END

does the same like method "text", but the text better readable.

Appearance

appearance('type=value1,value2 ; type=...')

The appearance method specifies the visual properties of geometry by defining the material and texture. If more than one type is needed separate the types by semicolon. The types can choosen from the following list.

Note: one character mnemonic are colors two characters mnemonic are values in range of [0..1] more characters are strings like file names or labels

d = diffuseColor
e = emissiveColor
s = specularColor
ai = ambientIntensity
sh = shininess
tr = transparency
tex = texture filename,wrapS,wrapT
name = names the MovieTexture node (for a later route)

The color values can be strings (X11 color names) or RGB-triples. It is possible to reduce the intensity of colors (names) by appending a two digit value (percent). This value must be separated by an underscore (_) or a percent symbol (%). Note: Do not use a percent symbol in URL 's. It would be decoded in an ascii character.

Sample (valid color values): '1 1 0' # VRML standard ' FFFF00 ' or 'ffff00', '255 255 0', 'yellow'

or reduced to 50% '.5 .5 .5' # VRML standard '808080', '128 128 0', 'yellow%50' or 'yellow_50'

For a list of X11 color names take a look at VRML::Color

Misc

directionallight

directionallight('direction', intensity, ambientIntensity, 'color', on)

direction         SFVec3f  '0 0 -1'
intensity         SFFloat  1
ambientIntensity  SFFloat  1
color             SFColor  '1 1 1' #white
on                SFBool   1

Example:

$vrml->directionallight("0 0 -1", 0.3);

sound

sound('url','description', 'location', 'direction', intensity, loop, pitch)

url         MFString []
description SFString ""
location    SFVec3f  '0 0 0'
direction   SFVec3f  '0 0 1'
intensity   SFFloat  1.0
loop        SFBool   0
pitch       SFFloat  1.0

def

def('name')

name SFString ""

Example:

$vrml->def('RedSphere')->sphere(1,'red')

use

use('name')

name SFString ""

Example:

$vrml->use('RedSphere')

route

route('from','to')

FROM.feldname SFString ""
TO.feldname   SFString ""

Interpolators

interpolator

interpolator('name','type',[keys],[keyValues])

name      SFString ""
type      SFEnum   "" # Color, Coordinate, Normal, Orientation,
                      # Position und Scalar
keys      MFFloat  [] # [0,1]
keyValues MF...    [] # Type of Interpolator

Sensors

cylindersensor

cylindersensor('name',maxAngle,minAngle,diskAngle,offset,autoOffset,enabled)

name       SFString ""
maxAngle   SFFloat  undef
minAngle   SFFloat  0
diskAngle  SFFloat  15
offset     SFFloat  0
autoOffset SFBool   1
enabled    SFBool   1

planesensor

planesensor('name',maxPosition,minPosition,offset,autoOffset,enabled)

name         SFString  ""
maxPosition  SFVec2f  undef
minPosition  SFVec2f  '0 0'
offset       SFVec3f  '0 0 0'
autoOffset   SFBool  1
enabled      SFBool  1

proximitysensor

proximitysensor('name',size,center,enabled)

name    SFString ""
size    SFVec3f  '0 0 0'
center  SFVec3f  '0 0 0'
enabled SFBool   1

spheresensor

spheresensor('name',offset,autoOffset,enabled)

name       SFString   ""
offset     SFRotation '0 1 0 0'
autoOffset SFBool     1
enabled    SFBool     1

timesensor

timesensor('name',cycleInterval,loop,startTime,stopTime,enabled)

name          SFString ""
cycleInterval SFFloat  1
loop          SFBool   0
startTime     SFFloat  0
stopTime      SFFloat  0
enabled       SFBool   1

touchsensor

touchsensor('name',enabled)

name    SFString ""
enabled SFBool   1

Example:

$vrml
->begin
    ->touchsensor('Switch')
    ->sphere(1,'white')
    ->def('Light')->directionallight("", 1, 0, 'red', 0)
    ->route('Switch.isActive', 'Light.on')
->end
->print->save;

visibitysensor

visibitysensor('name',size,center,enabled)

name    SFString ""
size    SFVec3f  '0 0 0'
center  SFVec3f  '0 0 0'
enabled SFBool   1

See Also

VRML::VRML2

VRML::VRML2::Standard

VRML::Base

http://www.gfz-potsdam.de/~palm/vrmlperl/ for a description of VRML-modules and how to obtain it.

Author

Hartmut Palm <palm@gfz-potsdam.de>

Homepage http://www.gfz-potsdam.de/~palm/