GIGAmacro Magnify2 and Control Box

GIGAmacro Viewer: User Guide and Administration

Published by: GIGAmacro, 455 Technology Way, Napa, CA 94558, USA +1 415 841 3322 (Pacific time zone)

Author: Graham Bird
Suggestions, improvements and updates to: <[email protected]>
Version: 0.6, Version Date: 2017-10-19

Tips and hints are indicated like this.
Warnings are indicated like this.
Critical or important items are indicated like this.

GIGAmacro Viewer

The GIGAmacro Viewer is a full-featured, web-based viewer for viewing, sharing, comparing, annotating, and measuring gigapixel scale images.

The examples here will use the public version (except for the Admin section) of the GIGAmacro Viewer: it is also possible to run your own implementation of the GIGAmacro Viewer on a notebook, desktop, local network server or cloud server.

GIGAmacro uses what is called 'agile development' so the GIGAmacro Viewer is updated on a frequent basis, sometimes as often as weekly. This means that you may see subtle difference in functionality and/or the way a screen looks when compared to a screenshot in the document. Fortunately, the documentation is updated in the same way, so usually catches up very quickly. You will always find the latest documentation at

The Viewer

You may use the GIGAmacro Viewer to browse images without being logged in - or even having an account. However, some functionality such as Notes, measurements etc., are only available when logged in to your account.

The GIGAmacro Viewer works on all modern browsers on tablets, mobile devices and desktop systems. The format and layout will respond to the screen size and resolution of your device.

If your device is touch sensitive, you can use the gestures to zoom in or out, to pan and to rotate images.

On small screens the Menu bar may appear slightly differently:

Viewer 0

The menu is located under the dropdown (marked (1)) and in some views there may not be a menu bar at all:

Viewer 0 2

In that case, the >> arrows will open (or close if you want to clean up the screen) the appropriate panel.

Viewer 0 1

Throughout this guide the words 'click' and 'tap' are synonymous. Also 'press & hold' on mobile should be read as 'right-click', or 'control-click' on a desktop browser.

There is a contextual menu available by pressing and holding (right-click, or CTRL-click) anywhere on the Image view screens:

Compare 5

This is a contextual menu, so try at at different stages during your use of the GIGAmacro Viewer to experiment with the options available.

The Home Screen

The public version of GIGAmacro Viewer is always available at Just open that link in any modern browser on your desktop or on your mobile device.

If you have a LOCAL or private version of the GIGAmacro Viewer your system administrator will tell you how to access that.

This is what you will see when you go to the home page:

Viewer 1 Home

Marked (1) in the image above. This is where you will create an account, or login if you already have an account. You may have had an email invite to an account that was created for you.

You do not need an account to view images, but without one you will only be able to browse and not be able to make Notes, measurements, etc.

To Create an account, tap (or click) 'Log In' and choose 'Sign up here'. You must have a valid email address and you will need access to that email account to confirm account creation before you can login.

On a LOCAL or private installation of the GIGAmacro Viewer you do not need to confirm by email link before using the system.

Collections (marked (3) in the image above) are ways to group images together. You must be logged in to create a COLLECTION or to add an image to an existing COLLECTION.

You may browse any publicly viewable collection without an account, but you cannot add Notes.

Marked as (2) in the image above; all the available (see the TIP below for more) images can be accessed here, by tap (or click)-ing 'IMAGES' in the Menu.

The images (and collections) you can see change depending on your status. If you are NOT logged in, you can only see images designated as 'Public'. Once you are logged in, you will see 'Public' images, any images you have added (that you 'own'), and any images shared by members of the Group(s) you belong to.

The IMAGES and COLLECTIONS screens display a similar layout, the IMAGES screen is shown below.
New on this screen are the SORT dropdown (Marked as (1)); this is where you can choose the order in which all available images are displayed. You may sort alphabetically, most popular, oldest and newest.

Viewer 2 Images

On each image thumbnail there are a series of icons (Marked as (3)); from the left, the (i) button - when tapped (or click)ed - toggles information, the metadata, about the image. The small boxes with mountains place the image in the left or right COMPARE location (marked '2') at the top right of the screen. Comparison functionality is described later in this guide.

Viewing an Image

To view an image, simply tap (or click) anywhere on the image and you will see a screen like this:

Viewer 3 Images

There are three main groups of controls on this screen: in the menu bar at the top, in the information, or metadata, panel on the right, and the toolbar, lower right.

On the Menu bar, top left, are the buttons to return to the last screen (marked (1)) and the Home button (marked (2)) that takes you to the GIGAmacro Viewer home page. At the top right, the icon of a pair of feet (marked (3)) is a guided tour - a great way to get familiar with key aspects of the GIGAmacro Viewer. Give it a try!
Finally, on the extreme right of the menu bar (marked (4)) is the Share icon. This is how you would share the image you are viewing to social media sites. There is also what is called an 'embed link': this is an easy way to incorporate an image into, for example, a web page or a live document; simply copy the link and paste it to your web or document.

Next, the panel on the right side of the image is ALWAYS open when the image loads. Marked as (5) is the double arrow that will close the panel.

Double arrows are used throughout the GIGAmacro Viewer to make your view 'cleaner'. If you see double arrows on their own, there is a panel there to be exposed by tap (or click)-ing the double arrow.

This tab (marked (6)) shows the detailed information about the image. If you see an orange square, that is a tap (or click)able link, for instance to the source of the specimen in the image.

You must be logged in to your account to add a Note to an image. Even an image you own!

On the tab (marked(7)) are any Notes (see Tip, below) that are associated with this image. If you are not logged in, you can see the list of (public) notes made by other users. You can also select each Note to show it or hide it. When logged in, you may add notes to your own, or other images for which you have privileges.

Viewer 4 Notes

NOTES is the name used in the GIGAmacro Viewer for various types of annotations that can be made on an image. There are six types of Note: Point, Line, Rectangle, Circle, Shape and Freehand. Each has a title and description and may be private or public.

When you tap (or click) on the type of Note you want, you will be asked to set a point where the Note is to be anchored on the image. The number of steps to complete a Note will vary depending on the type of Note. For example, with a Point Note, there is a single tap (or click) to place the Note on the image, but with a Rectangle you will define the top left and bottom right locations. To set multiple points, tap (or click) the first point release and then move to the next location and tap (or click) again to set the second point. For multi-point Notes (such as Shape) follow the on-screen instructions; double tap (or click) to end.

Do NOT click and drag to set consecutive points. Tap and release for EACH point needed. Double tap to complete the figure.

Viewer 4 Details

You can give the Note a meaningful title, a long description, choose the color, select a different icon, and also choose the visibility (Private, Group or Public) of the Note.

All your Images and Notes default to being Private. If you want a Note to be viewable by a Group or by all users you MUST choose that setting explicitly.

Measure and Rotate.

At the lower right (marked 8)) are the zoom controls (which are alternatives to pinching or dragging an image to scale it). The circular arrow rotates the image, which is the same as a 'two-finger' rotate on a touch sensitive device. When you click on the circular arrow, a bar appears above the controls and dragging the orange ball rotates the image; the rotation, in degrees, shows as the ball is dragged. Click again to disengage Rotation mode: the image will remain at the rotated position.

The scale bar changes to show the scale for the current zoom level of the image. The scale is set when the image is imported (if the scale information is included in the metadata) or manually by setting the scale against a known reference (see below).

To measure a line or an area, select the Measure Tool icon (the crossed rulers) and select either line or area. You can also recalibrate the scale for the image if you have a known reference such as a scale bar or a rule in the image.

Compare Mode.

Compare mode allows the user to view, and compare, two images simultaneously in the GIGAmacro Viewer.

These images can be side by side or one on top of the other so that, by varying the opacity of the top layer, it is possible to compare features on each image.

To enter Compare mode, select the two images that you want to compare by tapping the left or right 'mountain' icon on any image thumbnail (marked (2) and (3) below). The image thumbnail will appear in the appropriate boxes at the top right of the screen (marked (1)).

Compare 1

You may reverse the left and right selections by using the arrows between the thumbnails (marked (2), below). To cancel Compare mode, select the X (marked (3)). To enter Compare mode, choose 'Start' (4).

Compare 2

Compare mode opens with the information panel for each image exposed, close them to simplify the viewer with the >> arrows, as shown below.

Compare 3

This looks similar to the regular Image View, with the same tools available, but now with two images. By default the GIGAmacro Viewer is split vertically in the center. Dragging or zooming either image moves it independently in its own window until you 'Sync' them (see below).

There are two new controls at the bottom center; on the left is the icon (marked(1)) with all the options for Compare mode screen layout. On the center right (marked (2)) are the options to synchronize (or not!) the two images.

In addition to these controls, there is an additional contextual menu available by pressing and holding (right-click, or CTRL-click) anywhere on the main Viewer screen:

Compare 4

This is a contextual menu, so try at at different stages during your use of the GIGAmacro Viewer to experiment with the options available.

Compare Viewing Modes.

On the Screen Layout button (center bottom, left), the initial view is side by side images. You may change the layout to:

  • Swipe - vertical and horizontal. This allows you to slide the split point to expose more of one image than the other. Drag the arrows on the split to move the split point.

  • Side by Side - vertical and horizontal. Similar to above, but with a fixed split point.

  • Layered, where the two images are aligned one above the other. Note that the opacity slider, which appears when this mode is selected, above the lower center icons and can be adjusted to see 'through' the top image to the image below.

  • X-Ray view with either a square or a circular viewport. This allows you to show the lower image within the viewport. The Viewport is moved around by dragging the pointed arrow icon on the edge of the viewport - you may drag and zoom the image. You may vary the size of the Viewport with the slider that appears on the lower part of the screen.

Synchronizing Compare Images.

The center bottom right button allows you to Synchronize (Sync) or Unsynchronize (Unsync) the two images in the Compare View. When Synchronized, the two images will zoom, pan, scroll and rotate in unison.

If both images have a scale set, there will be an option on this sub-menu to 'Synchronize Scale'. This will reset both images to their native scale.

Adding Images.

Once you are logged in you may add images to the GIGAmacro Viewer.
To add an image, login and then choose the '+' (top right of the screen) and 'Add Image'.

Add 01

You may drag and drop an image, or browse your local storage and select the image to be uploaded.

You can add images in a number of formats:

  • Tiled image format, contained in a single zip file per image. This requires a defined format for the Folder and file structure. Full details are here.

  • A single image in the following formats: .psb, .psd, .tif and .jpg; in this case the GIGAmacro Viewer will automatically process the image to produce a tile set.
    KRPano must be enabled by the Superadmin role (see below) to convert .psb and .psd into tile sets.

  • Add a link to a Gigapan image; in this case, a link established to an extant image on the Gigapan site, where the image remains. The image can then be viewed in the GIGAmacro Viewer, and measurements, Notes, etc., can be made even though the image is NOT on the GIGAmacro Viewer server. All the Notes, etc. ARE saved on the GIGAmacro Viewer and can only be viewed there; they will NOT be viewable on the Gigapan site.

You must be online to use the Gigapan functionality

Deleting Images.

To delete an image (you must be the owner of the image), open the image in the GIGAmacro Viewer and select 'Edit Image Metadata' from the Information Panel. Scroll to the end of the metadata panel and select 'Delete'.

Deletion is PERMANENT. There is no 'undo' command for deletion of images. Be sure that you have a current backup before deleting images.


Users & Roles

This is where users with appropriate privileges can setup and administer the site.

There are THREE 'levels' of user in the GIGAmacro Viewer.

User: The User level has the minimum set of privileges, and all new users are set at this level by default.
When using the GIGAmacro Viewer in LOCAL mode, Users cannot be invited by email: to add a User go to Login and then choose 'Sign up here'.

Users (when logged in) can upload a zipped image file and set the viewing privileges for that image.

Admin: The Admin level has all the privileges of a user, PLUS the ability to create users, add users to groups (including giving Admin privileges), create groups, and customize the GIGAmacro Viewer Home page by adding Featured Images and Featured Collections.
SuperAdmin: In addition to the Admin privileges above, SuperAdmin can configure and setup the entire GIGAmacro Viewer installation.  This includes activities such as site administration, configuring for local system installation, database editing, etc.
WE STRONGLY (we mean, really, really STRONGLY) advocate that you use Admin and SuperAdmin accounts ONLY to do necessary administration tasks and that you have a regular username that you use for everything except tasks that require explicit admin privileges. ALWAYS logout of Admin or Superadmin accounts as soon as you have finished tasks that require privileges.

Running GIGAmacro Viewer in LOCAL Mode

The GIGAmacro Viewer is designed to run on a modest notebook, a desktop, to an internal departmental or corporate server, or in a private or public cloud. In all of these cases, we use the term LOCAL to distinguish between the GIGAmacro public server and a privately hosted and managed GIGAmacro Viewer under your explicit control.

You may license the GIGAmacro Viewer for your own private use in any of these situations. Email us for details of license and cost details.

To deploy the GIGAmacro Viewer on a wide variety of platforms we use a technology called Docker. Installing Docker is beyond the scope of this Guide, go to for the list of supported platforms and servers. In general, support is good for MacOS, current versions of Windows 10 (Pro and above) & Windows Server, many Linux distributions, or cloud providers such as AWS and Azure. Whilst it is possible to run previous versions of Docker on other platforms (such as Windows7 or Windows10 Home), setting Docker up in such environments requires significant technical expertise.

The installation and use of the GIGAmacro Viewer described below all assume an installed, functioning and tested installation of Docker on the system in question. And familiarity with Command Line (CLI) control of Docker.

Start Docker and wait until it says it’s running. (You do not need to Sign in / Create a Docker ID)
In In Docker Preferences > Advanced, set CPUs to 4 (if you can) and Memory to 4.0 GB, click ''Apply & Restart'' and wait for Docker to restart.

Installing a LOCAL version of the GIGAmacro Viewer

When setting up for the first time or when updating the GIGAmacro Viewer to the latest version, it is necessary to load the Docker Image to make it available to Docker.

We distribute this image as a .tar file which is downloadable from GIGAmacro servers.

If the downloaded file is in .zip format, simply unarchive it and then locate the tar file in the archive

If you do not have the information to access the download location, contact GIGAmacro support for details.

Download the image and then open your Terminal of choice (in administrator mode) and type:

docker load --input 0.n.n.tar

The command assumes that the .tar file is in the folder from which you issue the load command, and the version number (n.n) is changed to reflect the filename.

If you experience problems with any Docker commands, ensure that you are running your terminal with Administrator priviliges.

Running the GIGAmacro Viewer Container

The GIGAmacro Viewer will run automatically each time Docker is started, once the docker run command (below) has been successfully executed (see note below for Win10).

To start the container for MacOS, type the following:

docker run --detach --restart=always \
  --name gigamacro_viewer \
    -v gigamacro_viewer:/data \
    -v "$HOME/gigamacro_viewer":/shared \
    -p 5050:80 \
    -e LOCALHOST=1 \

For Windows 10 Pro, type the following:

In the current releases of 'Docker for Windows' there is a bug that prevents the ''--restart=always'' option from working correctly. See the Troubleshooting section for a temporary resolution.
docker run --detach  ^
  --name gigamacro_viewer ^
    -v gigamacro_viewer:/data ^
    -v "%USERPROFILE%/gigamacro_viewer":/shared ^
    -p 5050:80 ^
    -e LOCALHOST=1 ^

For Linux (Ubuntu), type the following:

docker run --detach --restart=always \
  --name gigamacro_viewer_app \
  -v /data/gigamacro_viewer_app/data:/data \
  -v /data/gigamacro_viewer_app/shared:/shared \
  -p 80:80 \
  -v /proc/sys/net/core:/host-net-core \

The GIGAmacro Viewer will be available shortly. Start a web browser and enter the following url: http://localhost:5050/

Your SuperAdmin, Admin and User username and password will have been supplied to you. Contact [email protected] if you have not received that information.

Your data is stored the 'gigamacro_viewer` folder of your home folder/directory.
Please ensure that the above data folder is included in your regular backup process.

Site Configuration & Administration.

You must be logged in as 'Superadmin' to configure and administer the site settings.

Login and choose 'Admin' to go to the Administration Menu.

Site 01

Choose 'Site Configuration' from the side menu.

Site 02


There are many fields that may be completed for Site Configuration. If you are behind a firewall or do not wish to allow external links and email user invites, tick the 'Local Mode' box and then scroll to the bottom of the page and choose 'OK'.
For most organizations wishing to run an internal or private version of the GIGAmacro Viewer, this is usually the most appropriate option.

The list of options is now reduced to that seen in the image above. You may complete (or leave blank) any of the visible fields. If you have a KRPano license, copy and paste the license code into the appropriate field, tick the Enable KRPano box and click OK.

Please ensure that you have a secure backup before changing GIGAmacro Viewer settings. Your data is stored the 'gigamacro_viewer` folder of your home folder/directory.

Full Mode.

In 'Full' Mode additional options are available of the Site Administration screen. These settings are not covered in detail here, but comprise:

  • Email server configuration

  • Google Analytics configuration

  • Amazon (AWS) backup configuration

  • Social Media sharing settings

  • Sentry configuration.

In short, to use any of these options you must have already setup other components and applications, and in doing so will have the information to complete each field - and understand its use.

Home Page Configuration.

You must be logged in as 'Superadmin' or 'Admin' to configure and administer the Home Page settings.

Login and choose 'Admin' from your login options to go to the Administration Menu.