Using eps.lib

John Light
3 August 2003

Table of contents

1. Introduction
1.1 What you get
1.2 What you need to do
2. Hello, Lens
2.1 In C++
2.2 In Visual Basic
3. Focus and Surround
4. Lens and Environment
4.1 Blending
4.2 Folding
5. 2D and 3D
6. Multiple Surrounds
7. Miscellaneous issues
7.1 Dropoff Adjustments
7.2 Performance
7.3 Simulating other lenses
7.4 Windows link issue (LNK4098)
7.5 Object lifetimes
7.6 Using epsCOM.dll
7.8 Using eps.lib with OpenGL
8. The C++ API
8.1 epsEnums
8.2 epsVec2, epsVec3
8.3 epsLens
8.4 epsSurround
8.5 epsEnvironment
9. The Visual Basic API (COM)
9.1 Enums
9.2 EPSVec2
9.3 EPSVec3
9.4 EPSLens
9.5 EPSLensRegion
9.6 EPSEnvironment

1Introduction

Elastic Presentation Space is a unifying concept for software lenses and distortions. It was the subject of Dr. Sheelagh Carpendale's Ph.D. thesis and, through support from Intel Corporation, has been embodied in a software library. The library is available for Windows and Linux.

Prior to the availability of the EPS library, putting lenses into an application required a specific implementation of a lens algorithm. This has limited the use of software lenses. With eps.lib, adding a software lens to a visual application is quite easy, as you will see.

1.1What you get

The library package includes the following files:

  • eps.lib -- the lens library for Windows. Linked /NODEFAULTLIB, it can be included in any program.
  • epslib.so -- the lens library for Linux. A shared libary.
  • epslib.h -- the include file for eps.lib. Include this in your C++ code to use the library.
  • epsCOM.dll -- a Component Object Model version of eps so you can use Visual Basic.
  • epsWrapperD.h -- a set of classes that wrap epslib.h and look kinda like the old library.
  • epsWrapperS.h -- same as above but using floats instead of doubles like the old library.

1.2What you need to do

Include epslib.h in C++ source files that need to access the libary. Link with eps.lib.

If you are using Visual Basic, add a Reference to "epsCOM 2.0 Type Library".

2Hello, Lens

2.1In C++

#include "epslib.h"
#include "stdio.h"
int main(int argc, char* argv[])
{
epsLens lens;
epsVec2 in, out;
float magnification;
for (float x = -120; x <= 120; x += 40) {
in.Set(x, 0);
magnification = lens.Magnify2D(&in, &out);
printf("(%4.2f, 0) ->\t(%4.2f, %4.2f)\tmag = %.2fx\n",
x, out.x, out.y, magnification);
}
return 0;
}

produces the following output

(-120.00, 0) -> (-122.22, 0.00) mag = 1.02x
(-80.00, 0) -> (-90.35, 0.00) mag = 1.13x
(-40.00, 0) -> (-61.15, 0.00) mag = 1.53x
(0.00, 0) -> (0.00, 0.00) mag = 2.00x
(40.00, 0) -> (61.15, 0.00) mag = 1.53x
(80.00, 0) -> (90.35, 0.00) mag = 1.13x
(120.00, 0) -> (122.22, 0.00) mag = 1.02x

The output reflects the default setting for a lens:

  • Center: (0, 0, 0)
  • Shape: Circle, radius 10
  • Magnification: 2x
  • Dropoff: Gaussian, width 100

2.2In Visual Basic

Private Sub Form_Load()
Dim lens As New EPSLens
Dim region as New EPSLensRegion
Dim inv As New EPSVec2
Dim outv As New EPSVec2
Dim magnification As Single
lens.AddRegion region
For x = -120 To 120 Step 40
inv.Set x, 0
magnification = lens.MagnifiedPoint2DandMagnification(inv, outv)
Debug.Print "(" & x & ",0) ->" & vbTab & "(" & outv.x & ", " _
& outv.y & ")" & vbTab & "mag = " & magnification & "x"
Next
End Sub

generates much the same output.

3Focus and Surround

A lens consist of two parts: the Focus and the Surround. The focus is the center region that is magnified by the specified magnification value. It can have the following shapes:

  • Point,
  • Horizontal line,
  • Vertical line,
  • Square,
  • Rectangle,
  • Circle, and
  • Polyline (not currently implemented).

You can do the following to the focus of the lens:

  • Change its size,
  • Change its shape,
  • Change its magnification,
  • Move its center,
  • Rotate the whole lens,
  • Rotate just the top of the lens, and
  • Change how it blends with other lenses.

The Surround is the part of the lens that makes a transition from the focus region to the area around the lens. The Surround typically has a non-zero width over which its magnification drops from the focus magnification to 1. The curves change in magnification follows one of several mathematical Dropoff functions, which each have a particular feel.

  • Manhattan. This is really no transition at all. the magnification immediately drops from full value to one outside of the lens. Typically, some of the surrounding context is obscured behind the lens.
  • Linear. The magnification drops linearly between the Focus and edge of the lens. There may be a noticeable discontinuity at both ends of the transition.
  • Gaussian. The Gaussian function is continuous in both value and derivative adjacent to the Focus, and it is nearly continuous in both at the edge of the lens. In fact, a Gaussian Dropoff typically continues a bit beyond the nominal Surround width so it can appear continuous at the outside.
  • Power. The power Dropoff represents the family of curve y=x**n. (n = 2 give a parabola.) Their magnification drops rapidly next to the Focus and is fully continuous with the area outside the lens.
  • Hyperbolic. This function is really a section of a hyperbolic curve. It drops off rapidly near the Focus and is only somewhat continuous with the outside of the lens.
  • Cosine. This is continuous with the Focus and forms a somewhat abrupt edge with the area outside the lens.
  • Cylindrical. This is continuous with the Focus and forms a totally abrupt edge with the area outside the lens. Not recommended for any use. Provided only for completeness.
  • Drop Gaussian. Here the asymptotic edge of the Gaussian function is eliminated by expanding the Gaussian function to fill the full range. A result is that the outside edge is more noticeable while maintaining continuity at the focus.

continuous with Focus / continuous with Outside / comment
Manhattan / no / no / always loses data underneath
Linear / no / no / sometimes appear to bulge
Gaussian / yes / yes / can lose data on sides
Power / no / yes / nearly even compression of data
Hyperbolic / no / somewhat / nearly even compression of data
Cosine / yes / no / compression of data can be bothersome
Cylindrical / yes / no / usually loses data near edge
Drop Gaussian / yes / somewhat / can lose data on sides

You can do the following to the Surround:

  • Change the Dropoff function,
  • Change the Dropoff width,
  • Change the Dropoff geometry from L-2 (Euclidean) to L-1, L-3, or L-infinity,
  • Adjust the shape of some Dropoff functions, and
  • Apply additional, non-linear distortions to the Dropoff geometry.

The Surround is a separate class. You can access the Surround for a lens with the following code:

epsLens lens;
epsSurround *surround = lens.GetSurround();

4Lens and Environment

While a lens can be used by itself, it is sometimes useful to have multiple lenses applied to a task. This may be because there are several points of interest the want to be examined simultaneously, or because different lenses can provide different value to a problem.

In order to use multiple lenses, you must put them in an environment. For example,

int main(int argc, char* argv[])
{
epsVec2 in, out;
float magnification;
epsEnvironment env;
epsLens lens1;
epsLens lens2;
env.RemoveAllLenses();
env.AddLens(lens1);
env.AddLens(lens2);
for (float x = -120; x <= 120; x += 40) {
in.Set(x, 0);
magnification = lens.Magnify2D(&in, &out);
printf("(%4.2f, 0) ->\t(%4.2f, %4.2f)\tmag = %.2fx\n",
x, out.x, out.y, magnification);
}
}

will do much the same as the previous example, but with two lenses. How the two lenses will affect the points depends on what type of blending each lens uses. Also, you can examine the sides of lenses (folding) when they are in an environment.

A lens can only be used with one environment at a time, so after you have added a lens to an environment you can't add it to another until you have removed it from the first one.

4.1Blending

Three types of blending are available for a lens:

  • None -- the lens exists on its own. It may cover other lenses or be covered by them.
  • Normal -- the lens will merge with adjacent normal lenses to smoothly form a larger lens. The magnification of this merged lens will never exceed that of the component lens with the highest magnification.
  • Additive -- the lens will magnify whatever is underneath it, even the top of another lens.

Typically, Manhattan lenses will use None blending while other lenses will use Normal blending. Occasionally, Additive blending will be used to highlight or access specific information.

4.2Folding

Occasionally it is useful to move the Focus of a lens to a place other than where it would normally appear. This might allow the Focus to be seen better, place the Focus nearer to another point of interest, or allow examination of the information in the Dropoff of a lens. Folding is accomplished by moving the Viewpoint of a lens independently of the Viewpoint of the environment. Why this works is shrouded in the 3D underpinnings of the library and fully explained in Dr. Carpendale's earlier UIST paper.

A lens used by itself has a single Viewpoint, and changing it will have not little effect on the appearance of the lens. When a lens is put it an environment, it shares the Viewpoint of the environment by default. If you change the Viewpoint of the lens while it is part of an environment, you can move the Focus of the lens independently of other lenses. That is, only points affected by the folded lens will change.

52D and 3D

The library will work in either 2D or 3D mode. In either mode the input points are given as 2D vectors (epsVec2). In 2D mode they represent points on the plane. In 3D mode they represent points on the XY-plane or a parallel plane given by the BaseplaneZ value of the environment. (There is typically no reason to change BaseplaneZ from its default value of zero.)

In 2D mode, the calculations proceed using the 3D algorithm of the library, and the results are projected back onto the original 2D plane before returning to the user. The back projection takes a small amount of additional time which is needed when working with a 2D display environment.

In 3D mode, the results are returned in 3D form, which can be used directly as display or control points in a 3D display environment such as OpenGL. As long as the EPS environment (or lens) Viewpoint matches that of the 3D environment, the lenses will appear intact. If they don't match, the effect will appear as "unexpected folding" like that described above. (Sometimes it is instructive to move the graphics viewpoint away from the EPS Viewpoint to see what is going on.)

In either 2D or 3D mode, the user can request that the magnification amount be returned for each point. This requires some additional calculation which may not be needed, so methods are provided for getting the output points both with and without the magnification value. Furthermore, sometimes only the magnification value is needed, so a null pointer to the output vector avoids returning the vector result. (This doesn't save much time, but it can simplify code.)

6Multiple Surrounds

The Surround is a separate class because you can have more than one with a single lens. A lens comes with one when it is created, but you may want to replace it with one or more others.

Each Surround covers a range of angles about the center of the lens. The Surround that comes with the lens covers angles 0 to 360, meaning it completely surrounds the lens. You specify the coverage of a Surround with a start angle (relative to the positive x-axis of the plane) and an included angle. (The default lens starts at angle 0 and includes 360 degrees.) If you have multiple Surrounds, you will probably want each one to start where the previous one left off and the total included angle to be 360 degrees. If Surrounds overlap, behavior is unpredictable.

The Focus of a lens is only defined for angles that have a Surround. If you have one Surround that includes only 180 degrees, you will have only half a lens.

A Surround can only be used with one lens, so after it has been added to a lens, it can't be added to another until it is removed from the first one.

7Miscellaneous issues

7.1Dropoff Adjustments

Some Dropoff functions can be adjusted. For the purposes of these descriptions, imagine that the dropoff function is scaled to a unit square with the part near the Focus having coordinate (0, 1) and the part near the edge of the lens having coordinate (1, 0):

  • Linear dropoff adjustment -- This value from 0 to 1 subtracts the early part of a sine curve from the dropoff function to create a more concave appearance. This effect can often be provided more effectively by the hyperbolic or power dropoffs. (Default value = 0).
  • Gaussian dropoff adjustment -- This value from 0 to 1 subtracts the first part of a sine curve from the dropoff function. It has the effect of tightening the upper shoulder of the Gaussian function, which also makes the dropoff less steep. (Default value = 0).
  • Hyperbolic dropoff adjustment -- This value adjusts the hyperbolic curve to be closer or further from the origin. A value of 10 approximates a Linear dropoff. A value of less than .01 approximates a Manhattan dropoff. Values near 1 are useful. (Default value = 1).
  • Power dropoff power -- This value is the exponent of the power function used for the dropoff. A value of 2 gives a Parabolic dropoff. A value of 1 gives a linear dropoff. A value > 500 gives a Manhattan dropoff. Values less than 1 give strange convex dropoffs that are not typically useful. (Default value = 2).
  • Gaussian threshold -- This value from 0 to 1 indicates what the width of the Gaussian dropoff means. Since the Gaussian function is asymptotic to its x-axis, it doesn't have a well defined edge like all the other dropoff functions. This constant indicates what relative height is to be considered the "edge" of the lens. The default value is .1, meaning that the Gaussian dropoff width is the width at which the Gaussian has fallen to one-tenth of its maximum value. For the regular Gaussian dropoff, the lens is calculated to twice its nominal width, at which point the function has dropped to .0001 of its original height. For the Drop Gaussian dropoff, the height of the function is always .1 at the nominal width, and the threshold tells the relative height at which the function is terminated by dropping it to the x-axis. For the default value of .1, the Drop Gaussian terminates at the nominal dropoff width. For values less than .1, it extends beyond the nominal width and converges with the regular Gaussian dropoff. Setting the threshold to .0001 makes the Drop Gaussian identical to the regular Gaussian.

7.2Performance

Performance of the lenses varies depending on what configuration and options are used. On a 1 GHz Pentium III, processing a single point takes about one millisecond, but this can vary. Here are some factors, most of which have small effects:

  • Some Dropoff functions are more expensive than others. The Gaussian dropoff is slower because it generally extends beyond the nominal width, so it affects more points than others. (The Drop Gaussian can reduce that cost.)
  • Setting non-zero values for the Linear and Gaussian adjustments reduces performance.
  • Setting a Power dropoff adjustment other than 2 reduces performance. (A value of two is handled as a simple parabola.)
  • L-3 geometry is expensive.
  • Using L-1 or L-infinity dropoff geometry is faster than the normal (Euclidean) L-2.
  • Rotating the lens base or top will reduce performance.
  • Asking for magnification values to be returned with the points reduces performance.
  • Asking for 2D output reduces performance.
  • Using multiple lenses is slower both because each each lens must be applied to each point and because the effect of the two lenses may need to be blended.
  • Small lenses are faster than large ones because they affect fewer points. Points sufficiently far from a lens are handled quite cheaply.

Note that performance is NOT affected by magnification. Any value of magnification can be used with no affect on performance.

7.3Simulating other lenses

Most known lens types can be simulated using various adjustments in the library. Here are some examples.

  • Perspective Wall -- a tall rectangular Focus with a non-zero width and linear dropoff.
  • Document Lens -- a square or rectangular Focus with linear dropoff and L-infinity dropoff geometry.
  • Sarker and Brown – a point focus with linear dropoff.

7.4Windows link issue (LNK4098)

The library is supplied as a .lib built as Single-Threaded (see Project/Settings/C++/Code Generation/Use run-time library), which should work for most purposes. When including it in your project, you may get linker warning LNK4098 about incompatible libraries. You can look up that warning in MSDN to see how to eliminate the warning. The only way eps.lib can eliminate the warning is to come in six versions, one of which would not have that problem for you.

7.5Object lifetimes

As with any C++ library, object lifetimes are ambiguous. The library follows these conventions:

  • Any call by reference (argument uses &) will be a temporary use of the argument. Its contents will be copied if necessary, and the object will no longer be used after the method returns.
  • A call by pointer (argument uses *) may create a lasting reference in the library. For example, the AddLens and AddSurround methods will keep a reference. By not copying the object, they allow you to use your pointer to make changes to the Lens or Surround while it is still part of the Environment and Lens, respectively. After you RemoveLens or RemoveSurround the Environment and Surround will no longer have a reference.
  • A Lens or Surround can only be part of one Environment or Lens, respectively, at a time. Remove a Lens from one environment before using it in another. Remove a Surround from a Lens before using it in another Lens.
  • The library never frees objects you created, whether it holds them as its own objects are destroyed or not.

7.6Using epsCOM.dll