Table of Contents

• Table of Contents
• VoucherVisionEditor
• Try our public demo!
• Installing VoucherVisionEditor
  • Prerequisites
  • Installation - Cloning the VoucherVisionEditor Repository
  • About Python Virtual Environments
  • Installation - Ubuntu 20.04
    • Virtual Environment
    • Installing Packages
  • Installation - Windows 10+

    • Virtual Environment

    • Conda Environment

    • Installing Packages

• Create a Desktop Shortcut to Launch VoucherVisionEditor GUI
• Running VoucherVisionEditor from the Terminal

---

VoucherVisionEditor: User Interface for VoucherVision

This application serves as a dedicated user interface designed to efficiently edit and manage the automatically generated label transcriptions by VoucherVision. VoucherVision, a significant module of LeafMachine2, leverages cutting-edge Natural Language Processing (NLP) technologies to transcribe labels attached to natural history collection specimens, including those found on herbarium vouchers.

Powered by Large Language Models

At its core, VoucherVision employs several Large Language Models (LLMs) such as OpenAI's ChatGPT, Google's PaLM, and other locally-hosted LLMs that have been fine-tuned on transcription groundtruth datasets and GBIF records. This selection of potent models ensures optimal transcription quality across diverse datasets and provides flexibility in terms of cost and computational requirements.

Comprehensive Error Correction

To guarantee the generation of valid responses, VoucherVision integrates robust error correction procedures that enhance the reliability of the LLMs. This way, we ensure the integrity and accuracy of the transcriptions and support high-quality data management.

Customization

Both VoucherVision and VoucherVisionEditor are built with adaptability in mind. They can be easily customized to accommodate varying digitization requirements - from basic to advanced, including full Darwin Core Archive fields. This adaptability makes our software suitable for a wide range of digitization efforts.

---

Try our public demo!

Our public demo, while lacking several quality control and reliability features found in the full VoucherVision module, provides an exciting glimpse into its capabilities. Feel free to upload your herbarium specimen and see what happens! We make frequent updates, so don't forget to revisit! VoucherVision Demo

---

Installing VoucherVisionEditor

Prerequisites

• Python 3.12 or later

Installation - Cloning the VoucherVisionEditor Repository

1. First, install Python 3.12, or greater, on your machine of choice. We have validated with Python 3.8, but some of the packages in the requirements will need to be relaxed, just remove the versions and let the package manager get the older versions that are compatible with the older Python.
   • Make sure that you can use pip to install packages on your machine, or at least inside of a virtual environment.
   • Simply type pip into your terminal or PowerShell. If you see a list of options, you are all set. Otherwise, see either this PIP Documentation or this help page
2. Open a terminal window and cd into the directory where you want to install VoucherVisionEditor.
3. In the Git BASH terminal, clone the VoucherVisionEditor repository from GitHub by running the command:

   git clone https://github.com/Gene-Weaver/VoucherVisionEditor.git

4. Move into the VoucherVisionEditor directory by running cd VoucherVisionEditor in the terminal.
5. To run VoucherVisionEditor we need to install its dependencies inside of a python virtual environmnet. Follow the instructions below for your operating system.

About Python Virtual Environments

A virtual environment is a tool to keep the dependencies required by different projects in separate places, by creating isolated python virtual environments for them. This avoids any conflicts between the packages that you have installed for different projects. It makes it easier to maintain different versions of packages for different projects.

For more information about virtual environments, please see Creation of virtual environments

---

Installation - Ubuntu and MacOS

Virtual Environment

1. Still inside the VoucherVisionEditor directory, show that a venv is currently not active

   which python

   For Mac:

   python --version

2. Then create the virtual environment (.venv_VVE is the name of our new virtual environment)

   python3 -m venv .venv_VVE

   Or...

   python -m venv .venv_VVE

3. Activate the virtual environment

   source ./.venv_VVE/bin/activate

4. Confirm that the venv is active (should be different from step 1)

   which python

   For Mac:

   python --version

5. If you want to exit the venv, deactivate the venv using

   deactivate

Installing Packages

1. Install the required libraries to use VoucherVisionEditor

   pip install -r requirements.txt

2. Upgrade Streamlit

   pip install --upgrade streamlit

---

Installation - Windows 10+

Virtual Environment

Note: we assume that you have WSL already installed. Please see the Microsoft help page if the steps below cause errors.

1. Still inside the VoucherVisionEditor directory, show that a venv is currently not active

   python --version

2. Then create the virtual environment (.venv_VVE is the name of our new virtual environment)

   python3 -m venv .venv_VVE 

   Or...

   python -m venv .venv_VVE

3. Activate the virtual environment

   .\.venv_VVE\Scripts\activate

4. Confirm that the venv is active (should be different from step 1)

   python --version

5. If you want to exit the venv, deactivate the venv using

   deactivate

Installing Packages

1. Install the required dependencies to use VoucherVisionEditor

   pip install -r requirements.txt

2. Upgrade Streamlit

   pip install --upgrade streamlit

3. Install pywin32

   pip install pywin32

---

Conda Environment

Note: We assume that you have Conda installed. If not, please follow this guide to install Conda.

Make sure that you can use conda from Windows Powershell, not just the conda terminal. Try running the following in the conda terminal: bash conda init powershell

1. First, ensure you are inside the VoucherVisionEditor directory. You can check if Conda is installed by running:

   conda --version

2. Create a new Conda environment:

   conda create --name .venv_VVE python=3.11 -y

   OR Modify this command to install the env in a public location (if multiple users want to access VV Editor)

   conda create --prefix C:\ProgramData\miniforge3\envs\.venv_VVE python=3.11 --yes

3. Activate the Conda environment:

   conda activate .venv_VVE

   OR if in shared location, modify the following (Step 2 will tell you your exact command to activate):

   conda activate C:\ProgramData\miniforge3\envs\.venv_VVE

4. Confirm that the Conda environment is active:

   python --version

5. If you want to deactivate the environment, use:

   conda deactivate

Installing Packages

1. Make sure that you cd into the VoucherVisionEditor cloned repo directory.

2. Install the required dependencies for VoucherVisionEditor:

   pip install -r requirements.txt

3. Upgrade Streamlit:

   pip install --upgrade streamlit

4. Install pywin32 (needed for Windows shortcut functionality):

   pip install pywin32

Creating a Shortcut (Optional)

If you'd like to create a desktop shortcut for launching the application:

1. Run the script to create a shortcut:

   python create_shortcut.py

2. Follow the on-screen instructions to specify the Conda environment and the location where you want the shortcut to be saved.

---

Create a Desktop Shortcut to Launch VoucherVisionEditor GUI (Windows)

We can create a desktop shortcut to launch VoucherVisionEditor. In the ../VoucherVisionEditor/ directory is a file called create_desktop_shortcut.py. In the terminal, move into the ../VoucherVisionEditor/ directory and type:

python create_desktop_shortcut.py

Or...

python3 create_desktop_shortcut.py

Follow the instructions, select where you want the shortcut to be created, then where the virtual environment is located.

Note If you ever see an error that says that a "port is not available", open run.py in a plain text editor and change the --port value to something different but close, like 8502. Sometimes the connection may not close properly. Also make sure that the previous terminal is closed before re-launching.

---

Create a Desktop Shortcut to Launch VoucherVisionEditor GUI (MacOS)

We can create a desktop shortcut to launch VoucherVisionEditor. In the ../VoucherVisionEditor/ directory is a file called create_desktop_shortcut_mac.py. In the terminal, cd into the ../VoucherVisionEditor/ directory and type:

python create_desktop_shortcut_mac.py

Or...

python3 create_desktop_shortcut_mac.py

Now go look in the ../VoucherVisionEditor/ directory. You will see a new file called VoucherVisionEditor.app. Drag this file into the Applications folder so that you can open VoucherVisionEditor just like any other app.

Note If you ever see an error that says that a "port is not available", open run.py in a plain text editor and change the --port value to something different but close, like 8502. Sometimes the connection may not close properly. Also make sure that the previous terminal is closed before re-launching.

---

Launching VoucherVisionEditor from the Terminal

cd into your VoucherVisionEditor directory.

python run.py

OR...

./run.py

OR...

python ./run.py

---

Getting started

1. VoucherVisionEditor launches projects from within the VoucherVisionEditor/projects folder. Use the file uploader to drag and drop the .zip file for the project that you want to work on.
2. This adds the project to the /projects folder. You only have to do this once. Now all material for that project is available to VV Editor.
3. In the dropdown menu, select the project that you want to edit.
4. In the second dropdown, choose the transcription file that you want to edit.
   • For new projects, select the transcribed.xlsx file.
5. As soon as you make your first edit, all changes will be saved into a new file called transcribed__edited__CURRENT_DATE_TIME.xlsx
   • For the current session, all changes will be saved here.
6. If you stop editing at the end of the day, then on your next session simply load the last transcribed__edited__CURRENT_DATE_TIME.xlsxfile and start editing
   • VVE creates a new __edited__ for each session for redundancy purposes
7. If you stopped part way through a previous project, you can click skip to last viewed image to jump ahead