MushLog - Mushroom Collection System

A comprehensive system for field mycologists to catalog mushroom specimens with QR code label generation.

Note Using the Command Line

Many of the installation and troubleshooting steps in this guide require using the command line:

• Windows: Use the Command Prompt (search for "cmd" in the Start menu) or PowerShell.
• macOS: Use the Terminal app (found in Applications > Utilities).

You should be comfortable with basic command line operations, such as navigating directories (cd), running scripts, and copying/pasting commands. If you are new to the command line, there are many beginner tutorials available online for both Windows Command Prompt and macOS Terminal.

Quick Start

Note - macOS only - run the ./set_permissions.sh shell script first. This sets the file permissions to allow the subsequent scripts to run.

1. Install: Run ./install.sh (macOS/Linux) or install.bat (Windows)
2. Run MushLog: ./launch_mushlog.sh (macOS/Linux) or python run_mushlog.py (Windows)
3. Run MushView: ./launch_mushview.sh (macOS/Linux) or python run_mushview.py (Windows)
4. Run Import Tool: ./launch_import_tool.sh (macOS/Linux) or python import_tool.py (Windows)

The launcher scripts automatically detect the correct Python command for your system!

Applications

• MushLog: Data entry application for cataloging specimens
• MushView: Browser application for viewing and printing specimen labels
• Import Tool: Tool for importing specimen data from Excel files

System Requirements

• Python 3.7 or higher
• macOS 10.14+ (for .app bundles)
• Windows 10+ (for .exe files)
• Linux (for standalone executables)

Installation Options

Option 1: Python Environment (Recommended for Development)

Prerequisites

• Python 3.7+ installed
• pip package manager

Installation Steps

1. Download and Extract

   # Download the zip file and extract to a folder
   unzip MushLog-Python-Distribution.zip
   cd MushLog-Python-Distribution

2. Install Dependencies

   macOS/Linux:

   chmod +x set_permissions.sh
   ./set_permissions.sh
   chmod +x install.sh
   ./install.sh

   Windows:

   install.bat

   Manual Installation:

   pip install -r requirements.txt

3. Run Applications

   MushLog (Data Entry):

   # macOS/Linux (recommended - automatically detects Python command)
   ./launch_mushlog.sh
   
   # Windows or direct command
   python run_mushlog.py

   MushView (Browser):

   # macOS/Linux (recommended - automatically detects Python command)
   ./launch_mushview.sh
   
   # Windows or direct command
   python run_mushview.py

   Import Tool (Import Excel Data):

   # macOS/Linux (recommended - automatically detects Python command)
   ./launch_import_tool.sh
   
   # Windows or direct command
   python import_tool.py

Creating Desktop Shortcuts

macOS/Linux:

chmod +x create_shortcuts_shell.sh
./create_shortcuts_shell.sh

After creating the desktop shortcuts (.sh) for the MushLog launch scripts, you can set custom icons for each shortcut using the provided AppleScript.

Steps:

1. Locate the Script:
   • Find the AppleScript file in your project directory, set_icon.scpt,
2. Run the Script:
   • Double-click the script to open it in the Script Editor, or run it from Terminal with:

     osascript prompt_for_icon.scpt

3. Follow the Prompts:

The script will prompt you to select the shortcut (.sh) file you want to set the icon for. Navigate in the Finder to the Desktop folder and locate the Desktop/launch_mushlog.sh.

For example:

~/Desktop/launch_mushlog.sh

• Next, it will prompt you to select the icon file.

Navigate to your project’s resources directory (e.g. MushLog-v1.3 by default), and select the appropriate .icns file, such as:

• resources/mushroom_icon.icns for MushLog
• resources/blue_mush.icns for MushView
• resources/import_tool.icns for Import Tool

Run the script again for each shortcut you want to customize.

Windows:

create_shortcuts.bat

This will create desktop shortcuts for both applications that you can double-click to run.

Option 2: Standalone Applications (Recommended for End Users)

macOS

1. Download MushLog.app and MushView.app
2. Drag to Applications folder
3. Double-click to run

Windows

1. Download MushLog.exe and MushView.exe
2. Run directly (no installation required)

Usage

MushLog - Data Entry

• Enter specimen location and details
• Generate QR-coded labels
• Export data to Excel
• Set reusable location data for batch entry

MushView - Specimen Browser

• Browse all cataloged specimens
• Search and filter specimens
• Print QR-coded labels for selected specimens
• Export database to Excel

Data Storage

For Native Python Installation (this distribution):

Windows

• Database: MushLog-v1.3\data\mycology.db
• Labels: MushLog-v1.3\data\label_pdf\ and label_image\
• QR Codes: MushLog-v1.3\data\qr_codes\

macOS/Linux

• Database: MushLog-v1.3/data/mycology.db
• Labels: MushLog-v1.3/data/label_pdf/ and label_image/
• QR Codes: MushLog-v1.3/data/qr_codes/

Documentation

The distribution includes comprehensive HTML documentation in the docs/ folder. To view the documentation:

1. Open the docs folder in your file explorer
2. Open (double click) index.html in your web browser
3. Browse the documentation for detailed usage instructions

The documentation covers:

• Installation and setup
• Application features and usage
• Troubleshooting guides

Troubleshooting

Common Issues

1. "styles.qss not found"

   • Ensure all resource files are in the resources/ folder
   • Check file permissions

2. Database not found

   • Application will create database automatically on first run
   • Check write permissions in user directory

3. Import errors

   • Verify all dependencies are installed: pip list
   • Reinstall requirements: pip install -r requirements.txt --force-reinstall

Support

For issues or questions:

• Check the troubleshooting section above
• Review application logs in the logs/ folder
• Contact support with error details

License

MIT License - See full documentation for the LICENSE.

Version

Current Version: 1.3