BlueSpray - Help
© SchoonerTurtles, Inc. 2012-2015

Getting Started

Installing and Running BlueSpray

Installing BlueSpray is as easy as downloading a folder to your computer. Since BlueSpray uses Java you'll also need to install the Java Virtual Machine from Oracle (who purchased Sun, the creators of Java). Follow the steps below to install Java and BlueSpray. If you are new to GIS or BlueSpray we recommend you check out our tutorials. The tutorials will walk you through using BlueSpray for basic GIS tasks and then set you free to master the problems you are working on.

Manual Installation


1. Java Runtime Engine and Libraries

Java is used by a number of desktop and web applications and you may already have it installed on your system.

1.1 Checking for Java on MS-Windows Operating System

The easiest way to see if you have a JVM running on your computer is to open the control panel (Start -> Control Panel or Start -> Settings -> Control Panel) and double click on "Add or Remove Programs". In a few moments you will see a list of the programs you have installed on your computer. Scroll down until you see an entry like "Java (TM) 6".

1.2 Checking for Java on Mac OS X (TBD)

Open your "System Preferences" and see if there is a "Java" icon available.

1.3 Installing Java

If you don't have Java 6 installed, please follow these instructions:

  1. Download and install correct 64-bit version for your operating system of Java from this web site.

If you want to explore the 3D features in BlueSpray (which are in alpha) . Follow the instructions below:

  1. Browse to the Java 3D downloads web page
  2. Go to the first link that matches your platform and run the installer

Note: If you do not download and install the Java 3D libraries, BlueSpray will work but will not display 3D data.

2. BlueSpray

While you can put BlueSpray just about anywhere on your computer we recommend putting it in a folder on your main drive (usually "C"). Just go to the "BlueSpray" page on the SchoonerTurtles web site ( and click to save the "zip" file on your local computer. Then, uncompress the file and double-click on one of the "bat" files, the "jar" file, or the "Launcher" to run BlueSpray. For novice users, we recommend running the launcher.

If you do not have decompression software you can purchase a software package like "WinZip" or use one of the free packages like "7-Zip". These packages and other options can be found by searching for them by name on the Internet.

3. Setting the Path Variable

Note: The instructions below are for MS-Windows based computers.

BlueSpray includes DLLs that are required to access certain file formats. You can run BlueSpray without these but you may recieve a message that certain libraries will be unavailable. Otherwise, you'll need to set the "PATH" variable in your environmental variables to point to this folder.

  1. Right click on "Commuter" or "My Computer" on your desktop or in the "Start" menu.
  2. Select "Properties"
  3. Depending on the version of Windows, you may need to click on "Advanced System Settings"
  4. Select the "Advanced" tab
  5. Click on "Environmental Variables"
  6. Under "System Variables", find "Path" and click "Edit"
  7. Add a semicolon and then a path to the folder "STLibraries32" if you are running a 32-bit operating system and "STLibraries64" if you are running a 64-bit operating system. The "STLibraries32" and "STLibraries64" are both in the BlueSpray folder. An example would be "C:\Users\Jim\Desktop\BlueSpray\STLibraries32"

4. Setting the PROJ_LIB Variable

Note: The instructions below are for MS-Windows based computers.

If you're going to be projecting between different datums, you'll need to set the "PROJ_LIB" environmental variable so GDAL can see the "proj_lib" folder.

  1. Right click on "Commuter" or "My Computer" on your desktop or in the "Start" menu.
  2. Select "Properties"
  3. Select the "Advanced" tab
  4. Click on "Environmental Variables"
  5. Under "System Variables", click "New"
  6. Enter "PROJ_LIB" for the "Varaible name" and the complete path to the proj_lib folder (e.g. "C:\BlueSpray\STLibraries64\proj_lib") as the "Variable value".

Launching BlueSpray

The easiest way to launch BlueSpray is to double-click on the "BlueSprayLauncher.jar" file in the BlueSpray folder. This is a mini-application that will allow you to set the minimum and maximum memory for the application. It is best to keep the maximum amount of memory below your total system memory. Otherwise, the operating system will begin swapping large GIS data sets to and from disk, greatly slowing BlueSpray's performance.

BlueSpray is provided as a Java "jar" file. On some computers you can just double-click on the jar file and it will run BlueSpray. The problem with this approach is that it will give you the default amount of memory and since GIS tends to use a lot of memory, you'll want to change this amount. The "1024" in the line below tells the computer to allocate about 1 Gig of memory for BlueSpray. You can increase this amount if your computer has more free space and you need a lot of memory. Usually only users with large photographic images such as aerial photos or satellite images will need to increase this value beyond 1 Gig.

You can also launch BlueSpray by double-clicking on the "BlueSpray64.bat" file for 64-bit java. You can edit this file to change the amount of memory available to BlueSpray. The value 6144 in the parameter "-Xmx6144m" sets the maximum amount of RAM for BlueSpray in megabytes so 6144 is about 6Gig of RAM. You can change this value but please leave at least 2Gig for the MS-Windows operating system or you may crash your computer.

Start Up

When BlueSpray launches it will present you with an agreement dialog and currently this requires a "passcode". Please contact Jim Graham at to find out what the current pass code is. Then you will see a preferences dialog. This dialog can be turned off and is always available in the Edit menu under Preferences. If you click "OK" in the preferences dialog you'll then see BlueSpray open.

At this point you can start right-clicking on items and playing with the tools or continue to the Navigating page for a more detailed introduction.