VRML(3)

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/