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/