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

The instructions below will help you install Java. If you think you might already have it install or are not sure, you can jump to "Launching BlueSpray" . If BlueSpray runs fine, you are good to go! Otherwise, you may need to install Java and take other steps.

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 search for "Add or Remove Programs" and look for a version of "Java". BlueSpray runs on a wide variety of versions of Java.

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 20 (9) or higher installed, please follow these instructions:

1. We are curently using Coretto from Amazon for BlueSpray development and recommend it.
2. 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 "Download" page on the web site and click on the latest release of BlueSpray and download save the "zip" file to your local computer. Then, uncompress the folder and double-click on one of the "bat" file to run BlueSpray.

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 using the "bat" file without these but you may receive 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. Search for "Edit the System Environmental Variables" and click on the result.
2. Under "System Variables", find "Path" and click "Edit"
3. If you do not see an entry that ends in "STLibraries64" you will need to add an entry for the STLibraries 64 folder which is in the BlueSpray folder. An example would be "C:\Users\Jim\Desktop\BlueSpray\STLibraries64"

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 may need to set the "PROJ_LIB" environmental variable so GDAL can see the "proj_lib" folder.

1. Search for "Edit the System Environmental Variables" and click on the result.
2. If you do not see an entry for "PROJ_LIB", under "System Variables", click "New"
3. Enter "PROJ_LIB" for the "Variable name" and the complete path to the proj_lib folder (e.g. "C:\BlueSpray\STLibraries64\proj_lib") as the "Variable value".

5. "Windows protected your PC" error.

If there is a problem with the security certificate matching what MS-Windows, expects, you may recieve a blue dialog box titled "Windows protected your PC". You may be able to click on the "More Info" button and then click on "Run Anyway". If this option does not appear, you may be able to right click on the "BlueSpray64.bat" file and check the "Unblock" checkbox.

Launching BlueSpray

You can launch BlueSpray by double-clicking on the "BlueSpray64.bat" file. 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.

You can also launch BlueSpray by double-clicking on the "BlueSprayLaunher.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 and select a specific version of Java if you have multiple versions installed. 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.

Start Up

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.