zoommap-converter 0.4.1
A Python CLI tool for converting Leaflet to Zoommap.
Requires Python: <4.0,>=3.12

### Leaflet-to-Zoommap Converter

This repository contains a Python CLI tool to parse Obsidian Vaults and convert Leaflet codeblocks to Zoommap ([TTRPG Tools: Maps](https://github.com/Jareika/zoom-map)) 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`.

```bash
pip install zoommap-converter
```

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

```bash
zoommap-converter --version
```


## Usage

### Pre-flight Checklist

Before running the converter, please ensure you have satisfied the [Prerequisites](#prerequisites).

In addition, you should ensure the following conditions are met:

- If you wish to have your markers converted across to Zoommap, you should make sure you have the SVG icons downloaded and extracted/unzipped in the vault. They must be stored in the same location as defined in the TTRPG Tools: Maps settings (e.g. default folder is `ZoomMap/SVGs`). Without this, your markers will not be migrated across and the default pin will be used. Note: Custom Images/SVGs are not supported at this time.
![Settings to download SVGs](resources/zoommap-svg.jpg)

### Basic Conversion

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

```yaml
vault_path: leaflet-vault
target_path: converted-leaflet-vault
```

**Note:** See the sample [`settings.yaml`](settings.yaml) for more configuration options.

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

```bash
export SETTINGS=path/to/settings.yaml

zoommap-converter
```

Or pass it as an argument to the tool:

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

### Settings

Conversion settings are stored in YAML format. In this vault, we use [`settings.yaml`](settings.yaml). We pass this file to the converter process using the `--settings` flag, or by exporting the following environment variable:

```bash
export SETTINGS=/path/to/settings.yaml
```

### CLI Arguments

The following table contains the list of CLI arguments that are used for the tool. Similar functionality can be used in the [`settings.yaml`](settings.yaml) file.

| 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`        |
| `--merge-by-image`     | Merge Zoommap `markers.json` files by images, rather than image + ids or image + marker_tags| `False`                | `store_true`        |
| `--ignore-marker-tags` | Ignore merging by image + marker_tags, instead only merging by id. Note: this only affects the outputted Zoommap JSON file, notes with marker tags in the frontmatter will still be parsed for markers. | `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:
   ```bash
   git clone https://codeberg.org/paddyd/zoommap-converter.git
   cd zoommap-converter
   ```

2. Install dependencies using `uv`:
   ```bash
   uv install
   ```

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

### Running Tests

```bash
uv run pytest tests
```

### Building

```bash
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.

## Roadmap

Current items on the roadmap:

- Migrating Custom SVGs/Icons
- Overlays

If you have any other features you'd like me to include, please write a [Feature Request](https://codeberg.org/paddyd/zoommap-converter/issues/new?template=.forgejo%2fISSUE_TEMPLATE%2ffeature.md).

## Support

For issues, questions or feature requests, please file an [issue](https://codeberg.org/paddyd/zoommap-converter/issues/new).

## Acknowledgements

- [Jareika](https://github.com/Jareika) the creator of [TTRPG Tools: Maps](https://github.com/Jareika/zoom-map).
- Obsidian community for plugin development
- Font Awesome for icon assets
- Pydantic for data validation