Visual3D™ Documentation

Wed, 11 Apr 2007 21:38:22 -0400

Visual3D GRAPHICS LIBRARY DOCUMENTATION

by Serg Koren

Serg@VisualNewt.com

http://www.VisualNewt.com

07/27/1999 - 1.0.8

CONTENTS

Introduction

Registering

Using the Library

Global Variables

The API Functions

Specialized Functions

LOADARRAY S, A

LLOAD2DARRAY S, A, SX, SY

LIBVER

POLYGON R, T

SPIRAL N, R, T

ELLIPSE Xc, Yc, A, B, Phi

2-D Functions

SETORIGIN X,Y

PLOTMOVETO X,Y,N

PLOT X1, Y1, X2, Y2

INITGRAF X1, Y1, X2, Y2

INTER X1, Y1, X2, Y2, X3, Y3, X4, Y4, X, Y

ANGLE X, Y, A

ANGLIN X1, Y1, X2, Y2

TRANS2 Tx, Ty, M

SCALE2 Sx, Sy, M

ROT2 Theta, M

MULT2 M1, M2, M3

CLIP X1, Y1, X2, Y2

COVER X1, Y1, X2, Y2

r = DOT (V1, V2)

VECPROD V1, V2, R

DRAWAXIS2

3-D FUNCTIONS

PTOFXSECT K, N, B, D

INV M, MI

PTPLANES N, K, PT

LINEPLANES P, Q, K, D, B

TRAN Tx, Ty, Tz, M

SCALE( Sx,Sy,Sz,A)

ROT D,Theta, M

MULT M1, M2, M3

OBSERVE M

ORTHOGONAL M

PERSPECTIVE M

STEREO M

CUBEINPERSPECTiVE M

DRAWAXIS

The Coordinate System

Defining and Drawing 3D Orthogonal Objects

Defining and Drawing 3D Stereoscopic Objects

Defining and Drawing 3D Perspective Objects

The Example Program

A Word On The Hidden Line Algorithm

Planned Enhancements

Support

___________________________________

Introduction

This is a document detailing the API for the Visual3D(tm) graphics library.Visual3D(tm)gives developers using NSbasic the ability to plot and draw two and three-dimensional graphics.The library supports simple plotting, orthogonal as well as perspective views.It supports both clipping and covering.In addition, the library exposes utility as well as matrix transformation functions.

Registering

Registering the Visual3D(tm) graphics library allows you to create applications with the library and distribute them.Registering also removes the shareware notice.You will also receive the next version (2.0) for free.Site licenses (beyond a single user) are available.

Register via either:

Internet:http://www.VisualNewt.com/Visual3D.html

Postal: Send $15.00 in check or postal money order made out in US funds to:

Serg Koren

485 Brown Briar Cir.

Horsham, PA 19044-1974USA

Using the Library

The graphics library is located in the file Visual3D.nsb and this file must be CHAINed via the statement:

CHAIN "<path>\Visual3D.nsb",FALSE

You must then initialize the library with a call to INITGRAF (see API functions).

Global Variables

X,Y

OldX, OldY

OldOX,OldOY

Reserved by library.Do not use.

ScaleFact

Generic scaling factor.Use for simple scaling.For accurate scaling see SCALE2 for 2D scaling and SCALE for 3D scaling.

Clipping

Flag indicating whether object should be clipped.

0 - do not clip

1 - clip

Covering

Flag indicating whether object should be covered.

0 - do not cover

1 - cover

ClipX, ClipY

CoverX, CoverY

Defines the clipping and covering rectangles.The dimensions of the rectangles are +/-2ClipX, +/-2ClipY and +/-2CoverX, +/-2CoverY centered at the origin.

Screen

The name of the graphics drawing area.This is an NSbasic PictureBox object.See INITGRAF for default values.

NumVert

Defines the number of vertices contained in the 3D object to be drawn.An object can contain 500 vertices.

VertX, VertY, VertZ

Arrays defining the x, y, and z coordinates of the vertices contained in the 3D objec to be drawn.Each is dimensioned to 500.

AXISTRANSFORM

Transformation matrix (4 x 4) for 3D axes.This is initialized to the identity matrix.This matrix is used to plot the x,y,z axes in 3D space.

NumLines

Defines the number of lines connecting the vertices of the 3D object to be drawn.An object can have up to 500 lines.

LineV

Array defining the index of connected vertices.That is, LineV(1,j) Line(2,j) points to the index of the corresponding coordinate to connect.The (3,j) element of the array determines the color to be used when drawing the line.

(3,1) = -n - use n as the color for all line segmnts

(3,1) = -1 - use a random color for each line segment.

The dimensions of LineV are (3 x 500).

ActiveColor

The default color used to draw lines.This defaults to vbBlack.If ActiveColor is set to -1 it will generate a random color each time a line is drawn.

XOff, YOff

The x and y offsets into Screen indicating the (0,0) origin point.That is, the (x,y) in Screen coordinates of the center of Screen.

DIST

The distance from the viewpoint to the origin.

PPD

The distance from the eye to the perspective plane.

EYEDIF

The distance from the bridge of the nose to the center of the eye.This defaults to 4.4.This variable is only used to produce stereoscopic views.

NumFacets

The number of sides an object has.Used in drawing perspective views.

LineF

An array (100,500) indicating the index of the Ith line bounding the Jth facet.Facet lines must be defined consistenly clockwise or counterclockwise.This array is used in drawing perspective views.

IndexF

An array (500) specifying the number of lines (LineF) bounding the Jth facet. This array is used in drawing perspective views.

IHID

A flag indicating how hidden lines will be drawn.Only used for drawing perspective views.

True - hidden lines are removed

False - hidden lines are drawn as dashed perspective lines.

The API Functions

The following is a list of lbrary functions included in the current release:

Specialized Functions

V = LIBVER

Returns the version number of the graphics library

V - returned string

LOADARRAY S, A

Load an array from a comma-delimited string.

S - A comma-delimited string containing values to be loaded into the array.

A - A one dimensional array to be loaded.

LOAD2DARRAY S, A, SX, SY

Load a 2D array, having dimensions (SX x SY) from a comma-delimited string.

S - A comma-delimited string containing values to be loaded into the array.

A - A two-dimensional array to be loaded.

SX - Size of X dimension of the array A.

SY - Size of Y dimension of the array A.

POLYGON R, T

Draw a polygon having 100 segments of a given radius having a segment every T radians.This can be used to draw circles providing the angle T is small enough.

R - radius

T - angle to increment by (radians)

SPIRAL N, R, T

Draw a spiral having N turns, outer radius R, with initial angle T

N - number of spiral turns

R - outer radius

T - initial angle with respect to x axis

ELLIPSE Xc, Yc, A, B, Phi

Draw an ellipse with major axis A, minor axis B centered at (Xc, Yc) with the major axis making an angle Phi with the positive x direction.

Xc, Yc - ellipse center

A - major axis

B - minor axis

Phi - rotation angle

2-D Functions

SETORIGIN X,Y

Sets the origin of the universe to x,y.Initially, this is the center point of Screen.

X, Y - (x,y) coordinates relative to existing origin.

PLOTMOVETO X,Y,N

Move or draw to a point.This routine is the only one you should use to move the current pen point without drawing.This routine ignores the clipping and covering routines.If you wish to have a line clipped or covered use PLOT

X,Y- x and y coordinates of a point in local coordinates.

N - control flag:

2 plot to X, Y

3 move pen to X, Y

-2 plot to X, Y and make X, Y the new origin

-3 move pen to X, Y and make X, Y the new origin

PLOT X1, Y1, X2, Y2

This routine draws a line from (X1, Y1) to (X2,Y2).This routine invokes CLIP and COVER based on the settings of the Clipping and Covering global variables.

X1, Y1 - the x and y coordinates of the first endpoint of the line

X2, Y2 - the x and y coordinates of the other endpoint of the line

INITGRAF X1, Y1, X2, Y2

Initializes the graphics library.Initializes a drawing area (an NSbasic PictureBox object called "Screen").The default scale (SCALEFACT) is set to 20 and the origin to the center point with respect to Screen.The default clipping rectangle is set to 50x8 (ClipX = 25, ClipY = 4).The default covering rectangle is set to 8x50 (CoverX = 4, CoverY = 25).The default drawing color (ActiveColor) is set to black (vbBlack). The default viewpoint (EyeX, EyeY, EyeZ) for 3d objects is (130,40,100).The distance to the perspective plane (PPD) is set to 100.

X1, Y1 - upper left coordinate of drawing area.

X2, Y2 - lower right coordinate of drawing area

INTER X1, Y1, X2, Y2, X3, Y3, X4, Y4, X, Y

Find X, Y the intersection point of two lines from (X1, Y1) to (X2, Y2) and (X3, Y3) and (X4, Y4).

(X1, Y1) (X2, Y2) - x, y coordinates of the first line

(X3, Y3) (X4, Y4) - x, y coordinates of second line

X, Y - x, y coordinates of intersection point

ANGLE X, Y, A

Find angle of a line from (0, 0) to (X, Y) with respect to the x axis

X, Y - x,y coordinates of a point on the line

A - angle

ANGLIN X1, Y1, X2, Y2

Find acute angle between two lines which both pass through (0, 0)

X1, Y1 - point on first line

X2, Y2 - point on second line

TRANS2 Tx, Ty, M

Two-dimensional axis translation matrix.

Tx - Translation of x

Ty - Translation of y

M - returned translation matrix (3 x 3)

SCALE2 Sx, Sy, M

Two-dimensional scaling matrix.

Sx - Scaling of x

Sy - Scaling of y

M - returned scaling matrix (3 x 3)

ROT2 Theta, M

Two-dimensional rotation matrix.

Theta - Angle to rotate (in radians)

M - returned rotation matrix (3 x 3)

MULT2 M1, M2, M3

Matrix multiplication.

M1 - Matrix 1 (3 x 3)

M2 - Matrix 2 (3 x 3)

M3 - returned matrix product (3 x 3)

CLIP X1, Y1, X2, Y2

Clip and draw line (X1, Y1) to (X2, Y2) to global rectangle having size (+/-2ClipX, +/-2ClipY).(See Globals).

(X1, Y1) (X2, Y2) - line to clip.

COVER X1, Y1, X2, Y2

Cover and draw line (X1, Y1) to (X2, Y2) with global rectangle having size (+/-2CoverX, +/-2CoverY).(See Globals).NOTE:Covering is the compliment of clipping.

(X1, Y1) (X2, Y2) - line to cover.

r = DOT (V1, V2)

Find the dot product of two vectors.

r - dot product

V1 - first vector (3)

V2 - second vector (3)

VECPROD V1, V2, R

Find the vector product R of two vectors.

V1 - first vector (3)

V2 - second vector (3)

R - returned vector product

DRAWAXIS2

Draw the x and y axes centered at the origin (0, 0).

3-D FUNCTIONS

PTOFXSECT K, N, B, D

Find point of intersection between a line (B = RMU * D) and a plane (N . X = K).

K - scalar

N - vector (x, y, z) normal to plane (N . X = K)

(B, D) - base vector (x,y,z) to (x1,y1,z1)

INV M, MI

Find the inverse matrix MI of the matrix M.

M - matrix to invert (3 x 3)

MI - returned inverse matrix (3 x 3)

PTPLANES N, K, PT

Find the point of intersection of three planes N(I, ) . X = K(I); I = 1,2 or 3.N(I, ) represents the normal to the Ith plane.

N - array of normals to the planes (3 x 3)

K - column vector (3)

PT - returned intersection point (3)

LINEPLANES P, Q, K, D, B

Find the line (B + RMU * D) common to two planes (P . X=K(1) and Q . X=K(2)

P - normal to first plane (3)

Q - normal to second plane (3)

K - constants for two planes (3)

D - returned directional vector of line (3)

B - returned base point of line (3)

TRAN Tx, Ty, Tz, M

Calculate 3-d axes translation matrix

Tx - translation of x axis

Ty - translation of y axis

Tz - translation of z axis

M - returned translation matrix (4 x 4)

SCALE Sx, Sy, Sz, M

Calculate 3-d axes scaling matrix

Sx - scaling of x axis

Sy - scaling of y axis

Sz - scaling of z axis

M - returned scaling matrix (4 x 4)

ROT D,Theta, M

Calculate 3-d axes rotation matrix about a direction.

D - axis to rotate around

1 - x

2 - y

3 - z

Theta - angle of rotation

M - returned rotation matrix (4 x 4)

MULT M1, M2, M3

3-d matrix multiplication (4 x 4)

M1 - matrix one (4 x 4)

M2 - matrix two (4 x 4)

M3 - returned matrix product (4 x 4)

OBSERVE M

Determine the observation matrix taking into account the observer's coordinare (EyeX, EyeY,EyeZ) and maintaining the vertical. This function is called by ORTHOGONAL.

M - Returned observation matrix.

ORTHOGONAL M

Draw the orthogonal view of the objects having NumLines (stored in LineV), and NumVerts vertices (stored in VertX, VertY, VertZ).

M - transformed object matrix for object to be drawn.

PERSPECTIVE M

Draws the perspective view of the object having NumLines (stored in LineV), and NumVerts vertices (stored in VertX, VertY, VertZ), and NumFacets sides.The global array LineF(I,J) defines the index of the Ith line bounding the Jth facet.The number of lines is defined by the global array IndexF(J).This routine supports hidden line removal.

M - transformed object matrix for object to be drawn.

STEREO M

Draws a stereoscopic view of an object using orthogonal projections.The seperation of views is determined by the global variable EyeDif.

M - transformed object matrix for object to be drawn.

CUBEINPERSPECTVE M

Draws a cube in perspective.This is an optimized cube drawing routine and does not support hidden line removal.

DRAWAXIS

Draw the x, y and z axes using the transformation matrix stored in AXISTRANSFORM.

The Example Program

The example program provides sample code on how to use the library.The complete example is found in the file 3DDemo.nsb, and provides a runnable set of graphics examples which use the library.To run the example, start NSbasic, load 3DDemo.nsb, and exceute it.

Here are some sample values to try for some of the 3d samples.

· For orthogonal objects try setting the viewpoint to (0,0,0)

· Turn off axis, scale 40, for perspective objects.Compare what the hidden lines checkbos does.(You may need to erase the screen to see the effect.)

· For a stereoscopic cube try a viewpoint of (10,30,40) and with the perspective plane 25.

· Play around with the controls and settings to get a feel for the library's capabilities.

Please note that the demo program only demonstrates using the API, you can define and draw any objects you want in your own programs.Also, the program uses two additional libraries, and the following lines may need to be changed:

CHAIN "\My Documents\NSbasic\Inputbox.nsb",FALSE

CHAIN "\My Documents\NSBasic\Menus.nsb",FALSE

The code snippets below are extracted from the example program.Specifically, the example program shows you:

Loading the library:

CHAIN "\My Documents\NSBasic\Visual3D.nsb",FALSE

You may need to change this line if you've placed the library in a different directory.

Drawing the x, y axes:

SUB AXISCHECK

IF Axis.Value THEN

DRAWAXIS2 <--- draw the x,y axes

END IF

END SUB

Drawing a circle using POLYGON:

SUB Circle_click

POLYGON 10,0.062831853 <--- draw a circle

AXISCHECK

END SUB8

A more complicated example:Whenever clipping or covering is involved you need to retain the endpoint of the previous line as the start of the current one.

SUB Sine_click

DIM X,Y,I

DIM OX,OY

PLOTMOVETO -8,SIN(-8) ,3 <--- move cursor

OX = -8 <--- save previous location

OY = SIN(-8)

FOR I = -8 TO 8 STEP 0.02

X= I <---- get new location

Y = SIN(X)

PLOT X,Y,OX,OY <---- plot the line

OX =X <---- make the last point, previous

OY = Y

NEXT

AXISCHECK <---- plot axes?

END SUB

Draw an offset and rotated ellipse:

SUB Ellips_click

ELLIPSE 50,-10,10,30,36 <---- plot ellipse

AXISCHECK

END SUB

Change the origin: (NOTE:The actual demo code uses a replacement INPUTBOX)

SUB Origin_click

DIM X,Y

X = INPUTBOX ("Enter new X coordinate for origin.","Reset Origin X","1000")

Y = INPUTBOX ("Enter new Y coordinate for origin.","Reset Origin Y","1500")

PLOTMOVETO CINT(X),CINT(Y),-3 <---- move to x,y and make it (0, 0)

END SUB

Color handling:

SUB SETUPCOLOR(Object)

DIM I

IFColorMap.Value = 0 THEN

ActiveColor = vbBlack <---- set default color

EXIT SUB

END IF

SELECT CASE Object

CASE ACube

FOR I = 1 TO NumLines <---- set each segment differently

IF I MOD 2 =1 THEN

LineV(3,I) = vbBlue

ELSE

LineV(3,I) = vbRed

END IF

NEXT

LineV(3,4) = -1 <---- set a segment to random color

CASE ASquare

ActiveColor = vbGreen

<...>

CASE ATetrahedron

LineV(3,1) = -vbRed <---- set entire object to red

CASE AnIcosohedron

LineV(3,1) = -1 <---- set each segment randomly

CASE ELSE

ActiveColor = vbBlack

END SELECT

END SUB

Initialize the graphics library:

SUB Main

SetupGUI' and wait for events

INITGRAF0,0,350,200 <---- initialize library

END SUB

The Coordinate System

The graphics library uses a flexible coordinate system located relative to the center coordinate point of the global variable Screen.This is (0,0,0) for the universe, but can be changed using various API calls. The x coordinate increases to the right and the y coordinate toward the bottom of the PictureBox.For 3D graphics, the z coordinate increases behind the screen (the z coordinate of your eyes is negative).

The origin of the 2D coordinate system can be altered by changing the values found in the global coordinates X and Y, and then calling SETORIGIN to update its visual representation.To alter the origin of the 3D system, you should do so by utilizing the transformation functions ROT, TRANS, SCALE, multiply the individual resulting matrices together, and store the result in the global matrix AXISTRANSFORM.

Defining and Drawing 3D Orthogonal Objects

Before a 3D object can be drawn, its structure must first be defined.Defining a 3D object involves specifying the number of vertices in the object, the coordinates of the vertices, and the set of vertices that define the edges of the object, as well aas the actual number of edges.

The sample program shows how this is done for several objects; we explain the process using a cube in detail.

· Define the coordinates for the object's corners with the object centered at the origin (0,0,0).This example defines the vertices as threecomma-delimited strings (one for the x, y, and z coordinates) and uses the utility function LOADARRAY to load the array of vertices into the VertX, VertY, VertZ arrays.Alternately, you can load the VertX, VertY, VertZ arrays directly by reading the coordinates from a file, or by prompting the user.We also set the number of vertices in the cube in the global variable NumVerts.

DIM Xs,Ys,Zs <----define temporary storagr

NumVerts = 8 <---- define the number of vertices in the cube

Xs = "1,1,1,1,-1,-1,-1,-1" <---- x coordinates of vertices

Ys = "1,1,-1,-1,1,1,-1,-1" <---- y coordinate of vertices

Zs = "1,-1,1,-1,1,-1,1,-1" <---- z coordinate of vertices

LOADARRAY Xs,VertX <---- load x coordinates into global array

LOADARRAY Ys,VertY <---- load y coordinates into global array

LOADARRAY Zs,VertZ <---- load z coordinates into global array

· Next, define the edges connecting the corners of the cube.These need to be stored in the form of indexes into the VertX, VertY, and VertZ arrays.These indexes are stored in the LineV array which has dimensions of (2,500).The ith edge is stored in elements (1,i) which corresponds to the index of the first corner, and (2,i) which corresponds to the index of the second corner.Again, although you could load these elements directly, the example program makes use of a utility function LOAD2DARRAY which corresponds to LOADARRAY, except that it loads a two-dimensional array.Again, we also must set the global variable containing the number of lines (edges) in the object.

DIM Lines <---- get temporary space

NumLines = 12 <---- define number of edges

Lines = "1,2,2,4,4,3,3,1,5,6,6,8,8,7,7,5,1,5,2,6,3,7,4,8" <---- define adjoining index pairs into Vert array

LOAD2DARRAY Lines,LineV,2,NumLines <---- load array sized (2,NumLines)

· The definition of the structure of the cube is now complete.The next step is to transform the location of the cube from the origin (0,0,0), to its final position in space.This is done using the ROT, TRAN, SCALE functions.Each of these produces a transformation matrix.To get the final transformation matrix for the object, multiply the individual matrixes (using MULT).The cube example rotates the cube around the z axism translates it and then rotates it about the y axis.

DIM A(4,4), B(4,4), C(4,4), S(4,4),PHI <---- get temporary space

PHI = 0.92795218 <---- angle to rotate (in radians)

ROT 3,PHI,A <---- rotate universe around z

TRAN 1500.0,0.0,0.0,B <---- move origin to (1500,0,0)

ROT 2,-PHI,C <---- rotate universe around -y

MULT B,A,S

MULT C,S,P <---- final transform is C x B x A

· Next, detrmine the observer's viewpoint coordinates.This is done by setting the global variables EyeX, EyeY and EyeZ.In the sample program this is done via prompting the user in Viewpoint_click.

· Finally, draw the defined and transformed object by calling the function ORTHOGONAL passing it the final transformation matrix

ORTHOGONAL P <---- draw it

Orthogonal drawings honor the settings of the global variables Clipping and Covering.

Defining and Drawing 3D Stereoscopic Objects

Drawing an object in stereoscopic mode is identical to drawing it in orthogonal mode except that you must set the global variable EyeDif to half the distance between two eyes, and call the routine STEREO instead ofORTHOGONAL.

Defining and Drawing 3D Perspective Objects

Perspective mode requires a bit more set up, and provides more options.First you must set up the definition of the object you want drawn, in the same manner done for an orthogonal view.Additionally, you must specify the distance from the viewpoint (EyeX, EyeY, EyeZ) and the perspective plane.The perspective plane is analogous to the screen through which the object is viewed.However, this is not necessarily the distance from your eye to your device's screen.The perspective plane is drawn on your screen, but it can be located any distance (even behind the object.The closer the plane is to your eye, the smaller the object will appear.Planes behind the object will display the object in larger than normal size.This distance is stored in the global variable PPD.

In addition to the vertices and lines that make up the object you defined for orthogonal views, you must now also define the facets (sides) that make up the object.

· Set the global variable NumFacets to the number of sides your object has (a cube has six).

NumFacets = 6

· Set the distance PPD (eye to perspective plane).

· Define the facets for the object (you need to define these consistently clockwise or counterclockwise.)

InF = "4,4,4,4,4,4,4,4,4,4,4,4"

LOADARRAY InF,IndexF

LinF = "1,2,3,4,0,0,5,6,7,8,0,0,1,10,5,9,0,0,2,11,6,10,0,0,3,11,7,12,0,0,4,12,8,9,0,0"

LOAD2DARRAY LinF,LineF,6,NumFacets

· For perspective views to be drawn properly, the origin of viewer space needs to be inside the object. Use the IDENTITY matrix routine to return the proper observation matrix if the origin is inside the object.(Our cube setup has the origin at (0,0,0) and the vertices at 1 or -1 so the cube complies with this rule.)

IDENTITY P

· Set the value of the global variable IHID to either hide hidden lines, or draw them as dashed lines.

· Now call either the PERSPECTIVE or CUBEINPERSPECTIVE to draw the object.

A Word On The Hidden Line Algorithm

The hidden line algorithm used by Visual3d(tm) assumes convex objects.Concave objects will produce undefined results.

Planned Enhancements

The next release of the Visual3D(tm)2.0 library will include a more general hidden line algorithm allowing concave objects, and support for bodies of rotation.Version 3.0 will have color fill and hidden plane removal.

Support

Suggestions, comments, questions, and bug reports should be sent to:Serg@VisualNewt.com.

----END DOC---

Visual3D™ Graphics Library | VisualNewt Software | Serg Koren

Visual3D™ Graphics Library

FOR IMMEDIATE RELEASE:

REGISTER:

FEATURES:

REQUIREMENTS:

PRICE:

AVAILABILITY:

DOWNLOAD THE DEMO:

Download it!

Visual3D™ Screen Shots

2D

3D Orthogonal

3D Perspective

Visual3D™ Documentation

Visual3D GRAPHICS LIBRARY DOCUMENTATION