---

Let's Identify a Few Terms, First

There are a few words and phrases that will be used frequently in this discussion. Let's talk about 'em first, and perhaps that will allow the remainder of the discussion to be less confusing. Or maybe not.

Real World - I use this term to mean the set of all viewable objects in our field of vision. In order for objects within the Real World to be mapped in a Plot Box, a coordinate system must be overlayed upon the Real World. In this article, we are using a 2D coordinate system, and ignoring the 3rd dimension.

RWOs - Acronym for Real World Objects. An RWO can be represented as a collection of lines.

Lines - In this article, lines are the entities of which RWOs are made.

Nodes - A line is defined by it's two endpoints, or nodes. The node at start of a line will be called the inode ("eye-node"). The node at the end of a line is called the jnode ("jay-node").

Viewport - A rectangular frame moved around within the Real World. A Viewport is the user's window into the Real World. RWOs which appear in the Viewport will be mapped to the Plot Box. The Viewport has a specific height and width, just like a picture frame has a specific height and width. In this article, the width of the Viewport is 4 feet, and the height of the Viewport is 3 feet. At any one time, the Viewport also has a specific location within the Real World. In this article, the Viewport's location will be defined by the x- and y-coordinate of the Viewport's upper left hand corner. The Viewport can be moved to a new location, at which time the coordinates of its upper left hand corner will naturally change.

Plot Box - The Liberty BASIC graphic control within which the contents of the Viewport are drawn. A Plot Box can be either a Graphic Window or a GraphicBox. In this article (and in the demo), a GraphicBox will serve as the Plot Box.

Aspect Ratio - The Aspect Ratio is the ratio of the Viewport's width to its height. Additionally, since the contents of the Viewport will be mapped to the Plot Box, the math is less complicated if the Plot Box has the same aspect ratio as the Viewport. In this article, the aspect ratios of the Viewport and the Plot Box will be the same. That Aspect Ratio will be 1.333.

Real World Coordinates - The x- and y-coordinates of a point or node with respect to the coordinate system overlayed upon the Real World. Also called simply "world coordinates". If an object is motionless in the Real World, then its world coordinates will not change. However, its screen coordinates will change every time the Viewport is moved.

Screen Coordinates - The coordinates assumed by a point when it is mapped to the Plot Box.

"Real-World" Objects Must Have Coordinates

In this little article, we will discuss drawing real-world objects (RWOs) inside of a Liberty BASIC GRAPHICBOX. But if we are going to accurately represent the size of these RWOs, as well as their position in space relative to other RWOs, we must define our RWOs with coordinates.

Actually, the RWOs that we use are made of lines. But each line has two endpoints, which I usually call nodes. As I indicated in the "Terms" section, the first endpoint of a line is the inode while the second endpoint is called the jnode. The nodes have x- and y-coordinates.

The Real World Objects To Be Mapped

The RWOs that we will map to a Liberty BASIC graphicbox are shown on the right. Think of the picture as an 8 foot by 10 foot wall with grafitti. The grafitti characters are the RWOs. Note that "LB" is scrawled on the lower left quadrant of the wall, and a star is in the upper right quadrant. These RWOs are defined by 15 nodes. The Real World coordinates of the nodes are given in the table below. The origin (0,0) of this coordinate system is the lower left-hand corner of the wall. Positive Y is upward from the origin, while positive X is rightward from the origin.

Table of
Real World Coordinates
----------------------

Node No.   X       Y
  1      1.00     3.00
  2      1.50     0.50
  3      2.50     1.50
  4      2.50     4.00
  5      3.00     1.00
  6      4.00     2.00
  7      4.00     3.00
  8      3.00     3.00
  9      4.00     3.50
  10     3.50     4.00
  11     4.50     5.50
  12     9.00     7.50
  13     7.00     4.00
  14     7.00     7.50
  15     9.00     4.50

Using a "Viewport" To Map the RWOs

A Viewport is essentially a moveable, rectangular frame within the Real World. Since the Real World extends infinitely in all directions, it would be impossible to map every object everywhere to our graphicbox. So, we will only focus on objects within the Viewport. As indicated in "Terms", our Viewport is 4 feet wide and 3 feet high, with an Aspect Ratio of

(4 / 3) = 1.333.

The nodes within the Viewport will be mapped to a GraphicBox control called the Plot Box. The size of the Plot Box will be 320 pixels wide by 240 pixels high. Just like the Viewport, it has an Aspect Ratio of

(320 / 240) = 1.333.

In Figure 2 on the left, the Viewport has been moved to a location in the Real World. The coordinates of the upper left hand corner of the Viewport are (VPx,VPy). Also note that we've identified an arbitrary point within the Viewport. The coordinates of the arbitrary point are (Wx,Wy).

Below the Viewport, we are showing a Liberty BASIC application that contains a Plot Box. The size of the Plot Box is 320 pixels wide by 240 pixels high. The origin of the Plot Box (0,0) is its upper left hand corner. The Real World point with coordinates (Wx,Wy) will map to the Plot Box with Plot Box coordinates (Sx,Sy). We don't know the values of Sx and Sy yet, but we will figure that out.

The essence of mapping RWOs to the Plot Box is this: the point represented by (Wx,Wy) must have the same distance relationship to the edges of the Viewport as (Sx,Sy) does to the edges of the Plot Box. If we want that to be true, then the following ratios can be made:

(Wx - VPx)/(4 feet) = (Sx - 0)/(320 pixels), and

(VPy - Wy)/(3 feet) = (Sy - 0)/(240 pixels)

For both of the equations above, the units on each side of the equals sign will cancel. When that is done, here is what remains:

(Wx - VPx)/(4) = (Sx)/(320), and

(VPy - Wy)/(3) = (Sy)/(240)

In the first equation, let's solve for Sx:

Sx = (320/4)*(Wx - VPx)

In the second equation, let's solve for Sy:

Sy = (240/3)*(VPy - Wy)

You may not realize it, but we have reached a milestone. These two equations accomplish our objective: we have taken a node in the Real World with coordinates (Wx,Wy) and found its equivalent Plot Box coordinates (Sx,Sy).

Why can we solve for Sx and Sy? Because all the other quantities are known. Wx and Wy are known, because those will be the coordinates of one of the nodes of our RWOs. VPx and VPy are known, because we will place the Viewport in a location of our own choosing.

For instance, let's move the upper left hand corner of our Viewport to Real World coordinate (x=3.00, y=7.50) and find the equivalent screen coordinates of Node 11. If you look back at the table above, you will see that the coordintes of Node 11 are (x=4.50, y=5.50). Using this information, let's solve for Sx and Sy for Node 11.

Sx for Node 11 = (320/4)*(4.50 - 3.00) = 120

Sy for Node 11 = (240/3)*(7.50 - 5.50) = 160

So, when the Viewport is at (x=3.00, y=7.50), Node 11 will map to the Plot Box at GraphicBox coordinates (x=120, y=160).

So, Why Stop At One Node?

Well, it was interesting mapping a single node to the Plot Box, but we would like to draw complex Real World Objects in our Plot Box. So, we need to solve (Sx,Sy) for each of the 15 nodes that make up our RWOs. I like to do it in a counted loop. Here's a way:

For i = 1 to 15
    Sx(i) = (320/4)*(Wx(i) - VPx)
    Sy(i) = (240/3)*(VPy - Wy(i))
Next i

Recall that the nodes are nothing less than the endpoints of the lines that make up our RWOs. With the screen coordinates of all 15 nodes found, we can draw our RWOs by using Liberty BASIC "line x1 y1 x2 y2" command.

Demo Program: Viewport.bas

Viewport.bas (screenshot on right) was written to accompany this article. The small GraphicBox on the left of the application contains a representation of the Real World Objects shown in Figure 1 above. That same GraphicBox contains a Viewport. The user can move the Viewport by left-clicking on the Viewport's handle, which is the small, solid square in the upper left hand corner of the Viewport. (Do not hold down the left button and "drag" the mouse pointer. Rather, click once and let the mouse button come up. The Viewport attaches to the mouse pointer.) To release the Viewport from the mouse pointer, right-click once.

The Plot Box is shown on the right hand side of the application window. When the users moves the Viewport, she will notice that the RWOs are continuously re-plotted in the Plot Box.

---