Install CAVE (v20 EOL)

CAVE is the Common AWIPS Visualization Environment that is used for rendering and analyzing data for AWIPS. The installer may require administrator priviledges to install and may require other system changes (environment variables, etc) as well.

Latest CAVE Versions

Note: Version 20* of CAVE and EDEX runs on CentOS7 which was End of Life (EOL) on Jun 30, 2024. Unidata is still running a public version 20.3.2 EDEX and has CAVE installers available for the time being until we can officially release version 23 in a non-beta form. This will happen once the National Weather Service (NWS) officially releases 23.4.1 to operations.

View release notes

Major versions of CAVE and EDEX are not always cross compatible. Please use the same version CAVE to connect to the same version EDEX to ensure proper functionality.

Functionality/Reporting

If you come across issues/bugs/missing functionality, we also encourage you to report it using this short form.

General Requirements

Regardless of what Operating System CAVE is running on, these general requirements are recommended in order for CAVE to perform optimally:

  • Local machine

    Running CAVE via X11 forwarding or ssh tunneling is not supported. Using a VNC connection is the only remote option, and may result in worse performance than running locally.

  • OpenGL 2.0 Compatible Devices

  • At least 4GB RAM
  • At least 2GB Disk Space for Caching
  • NVIDIA Graphics Card

  • Latest NVIDIA Driver

    While other graphics cards may work, NVIDIA Quadro graphics card is recommended for full visualization capability

Linux

Latest Version: 20.3.2-2

System Requirements

  • 64 bit CentOS/Red Hat 7
  • Bash shell environment

While CentOS8 has reach End of Life as of Dec. 31, 2021, CentOS7 End of Life isn't until June 30, 2024.

Upgrade Existing Installation

Whether you have CAVE currently installed or not, you can follow the Download and Installation Instructions below. The script will remove the old version of CAVE if needed, and install the latest version.

If you would like to completely remove CAVE, please see the uninstall instructions further down this page.

Download and Installation Instructions

  1. Download the following installer: awips_install.sh
  2. In a terminal, go to the download directory
  3. Make the installer an executable by running: chmod 755 awips_install.sh
  4. Run the installer: sudo ./awips_install.sh --cave
    • This will install the application in /awips2/cave/ and set the local cache to ~/caveData/

Run CAVE

To run CAVE either:

  • Use the terminal and type the command cave
  • Find the application in the Linux Desktop menu: Applications > Internet > AWIPS CAVE

Additionally users can choose to run a virtual machine (VM) on Linux.

Windows

Latest Version: 20.3.2-2

For Windows, we offer two installation options: a Direct Windows Installation, or a Linux Virtual Machine.

The virtual machine option won't render RGB composites of satellite imagery.

Method 1: Direct Windows Install

We offer CAVE installers at both the user-level (no administrative permissions needed), and the system-level (useful in a lab setting for instance). If you need the system-level installer, please skip to the System-Level Installation section, otherwise simply proceed with the next sections.

Upgrade Existing Installation

If you do not currently have CAVE installed, please go directly to the Download and Installation Instructions.

If you already have CAVE installed:

  1. First remove it by going to the Installed Apps settings dialog. You can access this window by: Start bar > Settings > Apps > Installed Apps.
    • Typing "remove" in the start bar should bring you to this screen as well
  2. Find AWIPS CAVE, click on it, and click Uninstall.
  3. Once the uninstall is finished, simply download and install the latest version as instructed below.

Download and Installation Instructions

  1. Download and install: awips-cave.msi

Run CAVE

To run CAVE, either:

  • Double click on the CAVE icon on your desktop
  • Type "cave" in the start bar and hit enter
  • Find and run CAVE app in the file browser: C:\Users\%USER%\AppData\Roaming\UCAR Unidata\AWIPS CAVE\CAVE.bat

System-Level Installation

If you need a system-level installation of CAVE, please fill out this brief access form for the .msi, and then proceed with installation similar to that described above.

Method 2: Linux Virtual Machine

Please note, running CAVE in a Virtual Machine does have reduced functionality than running CAVE directly on hardware (ex: rendering RGB satellite images).

System Requirements

  • VMWare Workstation Player must be installed (free software):

  • For high definition monitors (4k), you will want to enable the high DPI setting for VMWare Workstation Player

    1. Create a desktop shortcut for VMWare Workstation Player
    2. Right-click the shortcut and select Properties
    3. Open the Compatibility Tab
    4. Select the "Change high DPI settings" button
    5. Check the "High DPI scaling override" checkbox and choose "Application" in the enabled dropdown

    VMWare Workstation Player DPI Setting

Upgrade Existing Installation

If you do not currently have CAVE installed, please go directly to the Download and Installation Instructions.

If you already have CAVE installed you can either:

  • Download the new Virtual Machine (as described below) and you will see the new VM in VMware, similar to this screenshot:

  • Upgrade the version of CAVE within the Virtual Machine by following the Linux instructions

Download and Installation Instructions

  1. Download the zipped file containing the virtual machine: CentOS7-Unidata-CAVE-20.3.2-2
  2. Unzip the folder.
  3. Open VMWare Player and go to Player > File... > Open and locate the folder that was created from the downloaded zipped file. Select the file called "CentOS 7 - Unidata CAVE 20.3.2-2.vmx".
  4. Run this new VM option. If it asks if it's been moved or copied, select "I Copied It".
    • There will be a user in the Linux machine named "awips" and the password is "awips"
    • The root password is "unidataAWIPS" if ever needed

Run CAVE

Once inside the VM, to run CAVE either:

  • Use the desktop icon
  • Use the terminal and type the command cave
  • Find the application in the Linux Desktop menu: Applications > Internet > AWIPS CAVE

macOS

Latest Version: 20.3.2-2

System Requirements

  • Nvidia Graphics Card (Some Intel Graphics cards seem to work as well)

Upgrade Existing Installation

If you do not currently have CAVE installed, please go directly to the Download and Installation Instructions.

If you already have CAVE installed:

  1. Remove the existing installation by locating it (it maybe be in your Applications folder), and dragging it to the trash.
  2. Clear CAVE's cache by removing caveData (see these instructions for removal).
  3. Follow the Download and Installation Instructions from below to install the newest version of CAVE.

Download and Installation Instructions

  1. Download and install CAVE: awips-cave.dmg Cave System Install
    • You can click and drag the CAVE icon into the Applications Directory to install at the System Application level -- this may require Administrator Privileges
    • You can drag that icon to any other location (Desktop, local user's Applications directory, etc) to install CAVE at that location -- this will not require Administrator Privileges

Run CAVE

To run CAVE either:

  • Use the System Menu Go > Applications > CAVE
  • Type ⌘ + Spacebar and then type "cave", the application should appear and you can hit enter to run it

The first time CAVE is opened, it will ask you if you are sure you want to run it, because it was downloaded from the internet and not the Apple Store. This is normal, and hit Open. Your message my differ slightly but should look like the image below:

internet warning

EDEX Connection

NSF Unidata and Jetstream2 have partnered to offer a EDEX data server in the cloud, open to the public. Select the server in the Connectivity Preferences dialog, or enter edex-cloud.unidata.ucar.edu.

EDEX in the cloud

Local Cache

After connecting to an EDEX server, you will have a local directory named caveData which contains files synced from EDEX as well as a client-side cache for data and map resources.

You can reset CAVE by removing the caveData directory and reconnecting to an EDEX server. Your local files have been removed, but if you are re-connecting to an EDEX server you have used before, the remote files will sync again to your local ~/caveData (bundles, colormaps, etc.).

  • Linux: /home/<user>/caveData/
  • macOS: /Users/<user>/Library/caveData/
  • Windows: C:\Users\<user>\caveData\

Uninstalling CAVE

Linux

These are instructions to manually uninstall CAVE. However, the awips_install.sh script will do these steps for you if you are installing a newer version of CAVE.

1. Make sure you have exited out of any CAVE sessions

Check to make sure your /etc/yum.repos.d/awips2.repo file has enabled=1.

2. Remove currently installed CAVE

sudo yum clean all
sudo yum groupremove "AWIPS CAVE"

If you are having trouble removing a group, see the troubleshooting section.

3. Check to make sure all awips rpms have been removed

rpm -qa | grep awips2

If you still have rpms installed, remove them

sudo yum remove awips2-*

4. Remove the cave directory in /awips2 and caveData from your home directory

rm -rf /awips2/cave
rm -rf ~/caveData

Windows

To completely remove CAVE:

  1. Type "remove" in the search bar and select Add or remove programs. This will open the Applications settings.
  2. From here, find AWIPS CAVE and select "Uninstall".

macOS

To completely remove CAVE:

  1. Find where it is installed (might be the Applications folder) and drag into the trash.
  2. Then remove caveData.