Make sure you have the latest version of VIP installed, which can be downloaded from the Account Portal. The Virtualitics API is only supported in VIP version 1.2.0 and later (see Version Compatibility for full compatibility details).
pyVIP is the Python package that houses the Virtualitics API and was developed for Python 3. We recommend that you use pyVIP with the latest Anaconda distribution of Python 3. Please refer to Anaconda’s instructions if you need any help installing Anaconda.
When you’ve completed the installation of Anaconda, launch Anaconda Prompt (which should be accessible through the Start Menu). From the Anaconda Prompt, run the following line to install the prerequisite ‘websocket-client’ package:
$> pip install websocket-client
Installation of pyVIP
Now you are ready to install pyVIP, which will give you access to Virtualitics API for Python. From an Anaconda Prompt, run the following line to install pyVIP:
$> pip install pyVIP
Upgrading your pyVIP version
It is recommended that you regularly update your pyVIP version so that you can use the latest functionalities that we’ve built into the package. To update your pyVIP package, run the following line from an Anaconda Prompt:
$> pip install —upgrade pyVIP
Checking your pyVIP version
To verify that you have the correct version of pyVIP, run the following command from an Anaconda Prompt:
$> python -c “import virtualitics; print(virtualitics.__version__);”
You should see the version number printed to the prompt. For example, you may see “1.2.0”.
Installing from Wheel
You can download the package wheel directly from here.
VIP Authentication Token
Open a new browser tab, navigate to the Virtualitics Account Portal and sign in. Select Account Settings on the left and scroll down to the Generate Token section. Click on Generate Your Api Token!
You will now need to set an environment variable called “VIP_AUTH_TOKEN” with the token generated from the Virtualitics Account Portal. To do this, follow these steps:
- Open Control Panel from the Start Menu.
- Click on “System and Security” and then “System”.
- Click on “Advanced system settings” from the list on the left and then click on the “Environment Variables…” button in the window that appears. You will then see a list of your “User variables” and “System variables”.
- Click on “New…” under the “User variables” section. Fill in the information as seen below.
Optional: Encryption Key
We strongly recommend using an encryption key! We use this key to encrypt all data passed through the API. Using the instructions above, set an additional user-level environment variable called “VIP_ENCRYPTION_KEY” and specify a strong alphanumeric key. If you are unsure whether this applies to you, please consult your IT department.
After setting your new environment variables, please close your Anaconda prompt and open a new prompt to pull the variables into context.
Updating VIP Settings
Open VIP and sign-in with the same credentials you used when using the Virtualitics Account Portal. Open the Preferences window and navigate to the API section.
- Port Configuration: This is where you specify the port number you would like VIP’s API WebSocket-Server to utilize. The default Port Configuration is set to use 12345; if you are unsure what to specify, we recommend you speak with your IT department or consult with email@example.com.
- Encryption Key: Set this to the same key you saved as an environment variable. If you did not specify the environment variable for “VIP_ENCRYPTION_KEY” then you can leave this cell blank.
- If you would like the VIP API WebSocket-Server to launch every time you sign into VIP, please select the “Launch server on login” checkbox.
After you’ve set up the API Configurations appropriately, click “Launch”!
When calling the
api.VIP() constructor successfully for the first time, the user must go to VIP and verify the API connection:
Open a new Anaconda Prompt window and run the the following command to open a new Jupyter Notebook:
$> jupyter notebook
Create a new Python notebook to begin your data analysis and exploration. An example of how to use the API to connect, load a dataset, and generate a plot is below. Please see our complete set of Example Notebooks for more in-depth examples, and refer to our Technical Documentation to learn more about the functionalities of the API.
Note: The API cannot be used while in an active VR session or SVO session.