HamLogMap is a web application for visualizing amateur radio QSO (contact) logs on an interactive map. It allows users to upload ADIF log files and view their radio contacts geographically.
- Upload and parse ADIF log files
- Interactive map visualization
- Mode filter panel for selective QSO viewing
- Statistics view (DXCC and Band statistics)
- Display QSO locations with customizable markers
- Draw lines between QSO points
- Band-based color coding for markers
- Night mode toggle
- Automatic location lookup - If the log file doesn't contain locator information, the application automatically looks up the DXCC entity and estimates grid square coordinates based on the call sign using country file data from country-files.com
- Download map as image
- Import QSOs from other formats (Cabrillo, etc.)
- QSO filtering by date range
- Performance optimizations for large log files (10,000+ QSOs)
The easiest way to get started is using Docker and Docker Compose. This method handles all dependencies automatically.
- Docker and Docker Compose installed on your system
- Clone the repository:
git clone https://github.com/quamilek/hamlogmap.git
cd hamlogmap- Build and start the application:
docker-compose up --build- Open your web browser and navigate to:
http://localhost:5050
- Stop the application:
docker-compose down- View logs:
docker-compose logs -f- Restart containers:
docker-compose up --buildThe first time you run the application, it may take a bit longer to start (1-2 minutes) because:
- The application downloads the
countryfiledatabase - this is used to lookup DXCC entity information from radio call signs - The application estimates GRIDSQUARE coordinates if they were not provided in the uploaded log file
Subsequent startups will be much faster as these data are cached.
If you prefer to run the application locally without Docker:
- Python 3.7+
- pip package manager
- Clone the repository:
git clone https://github.com/yourusername/hamlogmap.git
cd hamlogmap- Create and activate a virtual environment (recommended):
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Start the Flask application:
python app.py- Open your web browser and navigate to:
http://localhost:5050
- Navigate to the upload page
- Enter your callsign and locator (Maidenhead grid square)
- Select your ADIF log file
- Click upload
Once your log is uploaded, you can:
- View the map - See all your QSO locations plotted on an interactive map
- Toggle night mode - Click the "Toggle Night Mode" button for dark map view
- Color by band - Check "Color Pins Band" to color markers by frequency band instead of location
- Filter by mode - Use the Mode Filter panel to show/hide specific transmission modes (CW, SSB, FT8, etc.)
- View statistics - Click "Show Statistics" to see:
- DXCC (country) statistics
- Band statistics
- Complete QSO list with all details
HamLogMap includes a comprehensive test suite to ensure code quality and functionality.
make test-standalone# Install dependencies first
make install
# Run all tests
make test
# Run specific test types
make test-unit # Unit tests only
make test-integration # Integration tests only
make test-coverage # With coverage reportmake test-dockermake test- Run all testsmake test-unit- Run only unit tests (fast)make test-integration- Run integration tests (may require internet)make test-coverage- Run tests with HTML coverage reportmake test-standalone- Run basic tests without any dependenciesmake lint- Code style checking with flake8
Tests are automatically run on GitHub Actions for every push and pull request, including:
- Unit and integration tests
- Code linting
- Docker build verification
- Coverage reporting
- Python 3.14+
- Flask 3.1+
- All dependencies listed in
requirements.txt - Docker and Docker Compose (for containerized deployment)
Contributions are welcome! Please feel free to submit a Pull Request or create an issue.
This project is licensed under the MIT License - see the LICENSE file for details.
