Under Construction!
If you are a new user, you may prefer to start with the tutorial
HyperLens is written in JAVA, for maximum cross-platform portability and to enable its use as an Applet with a web browser. In order to work on as many platforms as possible, it is implemented to a 'lowest common denominator'. Several useful features - such as the use of multiple mouse buttons or shift-click idions - have been avoided, because they are known to be too buggy on some JAVA implementations. The baseline requirement for HyperLens is a JAVA 1.1 runtime environment, such as Sun's JRE, or recent versions of Web browsers from Netscape, Microsoft or Sun.
THe following are workarounds for known bugs in one or more JAVA platform:
In order to start, HyperLens needs to open a project - which you give it as an argument. This can be a project definition file, or a file of any image type allowed as a Base Image (see below).
jre -cp HyperLens.jar HyperLens [filename]or, if you have the Viewer
jre -cp HyperLens.jar HyperLensViewer [filename]or equivalent. Note that "filename" may be a local file, a URL, or a location in a JAVA Archive (.jar) file.
<applet code="webthing.hyperlens.HyperLensApplet" width=0 height=0 name="HyperLensApplet" archive="HyperLens.jar" > <param name=defn value=[filename]> </applet>
Note that the license on free HyperLens distributions (such as the one you can download from this website) do not permit you to run HyperLens as an applet. If you wish to do so, please contact WebÞing to discuss it.
Each HyperLens project has its own main window, containing all the main HyperLens controls for the project. The window is essentially similar for every project, except in that it is always scaled to the size of the base image that is being viewed.
There is no limit to the number of HyperLens projects you can run, although you should avoid keeping too many windows open unless your computer has ample memory.
The Window menu permits you to close (dismiss) any main window, or quit altogether. Note: it is not possible for an applet to quit altogether, so this option is not available to an applet.
HyperLens windows can be moved and resized using the normal controls provided by your window manager.
HyperLens is not responsible for a window manager's controls. If your window manager inserts its own widgets - such as buttons to maximise, iconise or close a window - these are outside the control of HyperLens.
The Menubar contains the main controls:
Some of these may be unavailable or empty. The Server and Edit functions may not be supported by all versions of HyperLens, while Layers and Plugins must be explicitly declared in a Project Definition File to become active.
The main display, occupying most of the project window, comprises the image you are viewing together with scrollbars to enable you to move around it if the image is larger than the screen space available for it.
The main window is the focal point for other controls and displays.
The Information Display is below the main display, and tracks the mouse within the main display. By default is shows pixel (X/Y) coordinates and distances. It can also show geographical position (Lat/Long) and distances, if this information is declared in the definition file. A plugin may use it to display other information (when activated).
The Lens Buttons are to the left of the main display, and toggle any installed Lenses on/off. When a lens first appears, it is given a rather arbitrary position in the main display; thereafter it only changes when you move or resize it. Whenever a lens is open, its button is 'lit' to the colour of the lens.
Above the main display are two or three general controls:
HyperLens uses a number of popup windows for messages, dialogues and controls. Most of these are self-explanatory; the exceptions are described below.
Note that all Message windows include a dismiss button labelled "OK".
HyperLens works together with a Web browser, which is used to display document types not supported internally such as HTML pages:
These currently only work in Applet mode: in standalone you will see a popup window advising you to open your browser at the URL concerned instead. This should be fixed in a future upgrade.
A HyperLens Project comprises
In the case of a project using WebÞing server software to permit editing via the Web, also
A Project Definition File is a text file in which the above information is defined. The format is somewhat based on the RFC822 style.
The format is subject to change, and will be published at a later date. Back-compatibility for all elements supported by the current HyperLens Editor is guaranteed, but experimental elements may be dropped.
To load a project, use any of the "Open" options in the File menu:
The New option in the File menu offers a file dialogue. Load an image, which then becomes the base image of your project.
The Save As option in the File menu saves your current project, either to a file on your disc or to a URL on the 'net. In the latter case, you will need to identify yourself to the remote server before saving.
The real-time status display at the bottom of a HyperLens viewer tracks the mouse whenever it is over the main image, and displays its position. To measure distance, hold a mouse button and drag. In the case of a geographical image, position and distance on Earth's surface is displayed (provided such information is available). Otherwise pixel coordinates are shown.
Note that a plugin may display other information here (please refer to the plugin's documentation) but this area is always used to track the mouse whilst over the main image.
Use the lens buttons to the left of the display to toggle the lenses. Note that the buttons are 'lit' when a lens is displayed.
When first opened, the lenses will always be positioned within about 200 pixels (diagonally) of the upper left corner of the image (at scale 1.0 - i.e. unzoomed). When you close and re-open a lens, it will always reappear where you last left it. An exception to this is when you edit a lens, when a lens editor may maximise it to cover the entire main image.
Each lens when displayed has two small tabs, top-left and bottom-right. The first moves the lens (maintaining the size and shape unchanged), while the second resizes it (leaving the opposite corner fixed). Simply drag with the mouse: the display is updated in real time.
Where two or more lenses overlap, they have a deterministic order. When you manipulate a lens (open, move or resize it), HyperLens brings it to the top, while maintaining the order of the other lenses unchanged. So an easy way to re-stack the lenses is to toggle each one off and on again in the order you want.
In addition to the above, there are two generic controls: Scale permits you to zoom in and out, while Transparency permits you to make a lens part-transparent (for certain lens types). Scaling affects everything within the display, whilst transparency only applied to the current top lens.
Layers (like lenses) must be defined in the HyperLens Project Definition File, and will appear in the Layers menu. A layer is loaded by selecting it from the menu, and will install itself as a lens when loaded. Normally this is automatic, and can only be done once for any given layer.
Note that loading a layer will often involve loading a new image, which may take some time over a slow Internet connection.
All Editor functions are provisional and subject to change. Back-compatibility will be maintaned for Project Definition Files created using any distributed editor.
The usual way to create a new project is using New in the File menu to load an image file, which HyperLens then loads as your project's Base Image.
(base image metadata not yet supported by the editor)
Use the New option in the Edit menu to add a new lens or layer. This opens a dialogue window, in which you must select a name for your lens (which will appear on its control button). You will also need to choose the lens type (the name of a JAVA class that implements the lens: see the API) and select a colour for it, using the RGB colour chooser - unless of course you want a lens in the default white.
Some lens/layer types require additional input. This currently uses a generic "Parameters" field, but will be updated.
The Edit option of the Edit menu offers a list of lenses and layers defined by your project. Selecting any of these loads the layer into a lens editor, if one is available for this lens.
Note that you cannot have more than one lens editor concurrently active within a Project. So long as you have an editor open, the New and Edit options in the Edit menu are disabled. The Save Layer option closes the lens editor.
The ObjectLens is suitable for simple object data, including hyperlinks. When you open an ObjectLens, a toolpanel window for a typical (though rudimentary) editor is displayed. If you have more than one Project open, the toolpanel is common to all of them, and it may be toggled from within the Edit menu of any Project where it is active.
Clicking within the tool panel selects (and highlights) a tool, which will then activate to create a new object when you click within the main window of a project being edited.
Shape objects supported are Lines, PolyLines, Rectangles, Circles/Ovals and Polygons. These may be shown as outline or filled, and each is available directly from the tool panel.
Icon and Image objects display a graphical object (e.g. a GIF file) at the position you define. You will need to import the graphic, using the file dialogue box (if you want to repeat an object in many places, use clone).
The difference between Icons and Images in HyperLens is that Icons are always shown at their natural size, whereas Images are scaled when a reader zooms or pans using the scale control.
The "T" in the tool panel specifies a text object. Creating a text object opens a dialogue box in which you specify the text, together with any link information.
Any object may be a hyperlink, that opens any one of:
The link editor is (currently) the same as the Text Object dialogue window, but any text label you enter in it will be ignored when editing links.
In addition to the various objects, an Adjust button is also provided. When the selected tool is Adjust, clicking an object will highlight it and open a popup menu: