zoommap-converter 0.3.3

A Python CLI tool for converting Leaflet to Zoommap.

Leaflet-to-Zoommap Converter

This repository contains a Python CLI tool to parse Obsidian Vaults and convert Leaflet codeblocks to Zoommap (TTRPG Tools: Maps) format, supporting map scales, icons and shapes.

Overview

ZoomMap Converter is designed to facilitate the migration from the Obsidian Leaflet plugin to the ZoomMap plugin. It handles the conversion of map notes, markers, and configurations while maintaining compatibility with Obsidian vault structures.

Features

• Note Conversion: Converts Leaflet-formatted codeblocks to ZoomMap format.
• Icon Processing: Transforms custom SVG icons with color and size normalisation over to Zoommap.
• Error Handling: Validation and logging for troubleshooting.
• Path Management: Handles Obsidian vault file paths and structures.

Installation

Prerequisites

• Python 3.12+
• Obsidian vault with Leaflet plugin notes
• Leaflet Plug-In installed and enabled.
• Zoommap Plug-In installed and enabled.

Setup

1. Download the CLI tool using pip.

pip install zoommap-converter

2. Once installed, you can test the install was successful using:

zoommap-converter --version

Usage

Basic Conversion

1. Create and configure the settings.yaml file and ensure to include the vault_path and target_path:

vault_path: leaflet-vault
target_path: converted-leaflet-vault

Note: See the sample settings.yaml for more configuration options.

2. Set the path to your settings.yaml via environment variables:

export SETTINGS=path/to/settings.yaml

zoommap-converter

Or pass it as an argument to the tool:

zoommap-converter --settings path/to/settings.yaml

CLI Arguments

Argument	Description	Default Value	Type/Action
--settings	Path to the settings file.	$SETTINGS env var	Path
--version	Show the tool version and exit.	-	version
--no-backup	Do not create a backup of the original vault before conversion.	False	store_true
-v, --verbose	Increase output verbosity.	False	store_true
--in-place	Convert the vault in-place (no duplicate created).	False	store_true
--log-level	Set the logging level. Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL.	$LOG_LEVEL or INFO	str (uppercase)

Development

Project Structure

├── src
│   └── zoommap_converter
│       ├── __init__.py
│       ├── __main__.py
│       ├── app.py
│       ├── cli.py          # Command-line interface
│       ├── logs.py
│       ├── bootstrap/      # Initialisation and setup
│       ├── conf/           # Settings Config
│       ├── converter/      # Core conversion logic
│       └── models/         # Data models and schemas
tests/

Developer Setup

1. Clone the repository:

   git clone https://codeberg.org/paddyd/zoommap-converter.git
   cd zoommap-converter
   

2. Install dependencies using uv:

   uv install
   

3. Configure the vault path in settings.yaml or via environment variables

Running Tests

uv run pytest tests

Building

uv build

Contributing

Contributions are welcome. Please use the provided issue and pull request templates when contributing and follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with clear documentation
4. Include tests for new functionality

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions or feature requests, please file an issue.

Acknowledgements

• Jareika the creator of TTRPG Tools: Maps.
• Obsidian community for plugin development
• Font Awesome for icon assets
• Pydantic for data validation