# X_STYLES - QGIS Plugin

Version 1.0.0

## Overview

X_STYLES is a QGIS plugin for automatic assignment of standardized styles to XPlanGML files. The plugin enables immediate, standards-compliant display of spatial planning data directly after import into QGIS.

### Main Features

- Automatic assignment of QML styles for XPlanGML layers
- Support for building plans (BP), land use plans (FP), and regional spatial planning programs (RP)
- Intelligent detection of point, line, and polygon geometries
- Configurable display order (z-index) for optimal readability
- YAML-based configuration for easy customization without code changes
- Optional sorting of layer tree
- Automatic layer renaming with geometry suffix

## Installation

### Installation via QGIS Plugin Manager

1. Open QGIS
2. Go to `Plugins → Manage and Install Plugins...`
3. Search for "X_STYLES"
4. Click "Install"

### Manual Installation

1. Download the plugin archive
2. Extract the archive to your QGIS plugin directory:
   - Windows: `C:\Users\[Username]\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\` or `C:\Users\[Username]\AppData\Roaming\QGIS\QGIS4\profiles\default\python\plugins\`
   - macOS: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/` or `~/Library/Application Support/QGIS/QGIS4/profiles/default/python/plugins/`
   - Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/` or `~/.local/share/QGIS/QGIS4/profiles/default/python/plugins/`
3. Restart QGIS
4. Enable the plugin under `Plugins → Manage and Install Plugins...`

## Usage

### Basic Usage

1. Load one or more XPlanGML files into QGIS (via `Layer → Add Layer → Add Vector Layer...`)
2. Click the X_STYLES icon in the toolbar
3. The plugin automatically applies the appropriate styles to all recognized XPlan layers
4. A success message shows which layers were styled

Tip: The plugin automatically detects the layer type (BP, FP, RP) based on the layer name and applies the appropriate styles.

### Configure Settings

Via the dropdown menu of the X_STYLES icon, you can open the settings:

1. Click the arrow next to the X_STYLES icon
2. Select `Settings`
3. Configure the following options:

#### Available Settings

Option | Description
--- | ---
FP Style | Enables special styles for land use plans from the FP directory
RP Style | Enables special styles for regional spatial planning programs from the RP directory
Custom Layer Order | Applies a custom display order based on z-index
Sort Layer Tree | Sorts the layers in the layer tree according to display order
Rename Layers | Adds geometry suffix to layer names (_p for point, _l for line, _a for area)
Base Style Directory | Directory with base QML files and manifest.yaml
FP Style Directory | Optional directory with specific FP styles (overrides base styles)
RP Style Directory | Optional directory with specific RP styles (overrides base styles)

## Advanced Configuration

### The manifest.yaml File

The heart of style management is the `manifest.yaml` file in the base style directory. This file defines the mapping between layer names and QML files.

#### Structure of manifest.yaml

    bp_anpflanzungbindungerhaltung:
        PointGeometry:
            path: BP_AnpflanzungBindungErhaltung_p.qml
            zIndex: 115
        LineGeometry:
            path: BP_AnpflanzungBindungErhaltung_l.qml
            zIndex: 120
        PolygonGeometry:
            path: BP_AnpflanzungBindungErhaltung_f.qml
            zIndex: 131

#### Parameter Explanation

- Layer Key (e.g., `bp_anpflanzungbindungerhaltung`): Substring of the layer name (case-insensitive)
- Geometry Type: `PointGeometry`, `LineGeometry`, or `PolygonGeometry`
- path: Relative path to the QML file
- zIndex: Display order (low values = foreground, high values = background)

### z-Index Conventions

Recommended z-Index Ranges:

- 0-99: Reserved for future use
- 100-199: Building plans (BP)
- 200-299: Land use plans (FP)
- 300-399: Regional spatial planning programs (RP)
- 400-499: Landscape planning
- 9999: No display

## Troubleshooting

### Plugin Does Not Apply Styles

- Check if the layers are actually XPlan layers
- Verify layer names contain keywords from manifest.yaml
- Check if manifest.yaml exists in the base style directory
- Open the log messages (View → Panels → Log Messages) and search for "X_STYLES"

### Wrong Styles Are Applied

- Check the order of entries in manifest.yaml - the first match is used
- Ensure geometry types are correctly assigned
- Check paths to QML files for typos

YAML is indentation-sensitive! Use spaces (not tabs) and ensure consistent indentation (4 spaces per level recommended).

## License

This plugin is released under the GNU General Public License Version 2. You are free to use, modify, and distribute it.

## Support and Contact

- Email: plandigitaloss@proton.me
- GitHub: https://github.com/PlanDigitalOSS/x_styles
- Issue Tracker: https://github.com/PlanDigitalOSS/x_styles/issues

© 2024 PlanDigitalOSS | X_STYLES v1.0.0