Custom Maps - banisterious/obsidian-charted-roots GitHub Wiki

Custom Maps

Charted Roots allows you to create custom map images for fictional worlds, historical maps, or any other specialized geographic visualization. This page covers the complete workflow from creation to alignment.

Overview
Creating a Custom Map
Editing Map Properties
Aligning a Map Image
Using Your Custom Map
Working with Place Markers
Map Actions
Coordinate Systems
- Adding Places to Pixel-Based Maps
Linked Maps (Drill-Down Navigation)
Frontmatter Reference

Overview

Custom maps let you visualize people and places on your own map images rather than OpenStreetMap. Common use cases include:

Fictional worlds: Westeros, Middle-earth, your own fantasy setting
Historical maps: Period-accurate maps showing boundaries as they were
Regional focus: Detailed local maps for specific research areas
Thematic maps: Migration routes, land ownership, parish boundaries

Each custom map is stored as a note with cr_type: map frontmatter, containing the map configuration and a reference to the image file.

Creating a Custom Map

Map Creation Wizard

The Map Creation Wizard provides a guided 4-step workflow for creating custom maps with interactive place marker placement.

Open Control Center → Maps tab
Click Create Custom Map button
Follow the wizard steps:

Step 1: Select Image

Browse your vault for a map image (PNG, JPG, WebP, etc.)
A preview of the selected image is shown

Step 2: Configure Map

Enter a map name
Select or create a universe (optional, for grouping related maps)
Choose coordinate system (Geographic or Pixel)
Set bounds/dimensions for the coordinate space

Step 3: Place Markers

Click on the map image to add place markers
Each click opens the Create Place modal to define the place
Markers appear with the place name; drag to reposition
Right-click markers to edit or remove them
This step is optional — you can add places later

Step 4: Review & Create

Review your configuration summary
See a list of places that will be created
Click Create Map to finalize

The wizard creates the map note and any place notes you added, then optionally opens the map in Map View.

Resuming a Wizard Session: If you close the wizard before completing, your progress is saved. When you reopen the wizard, you'll be prompted to resume where you left off or start fresh.

From the Control Center

For a simpler creation flow without the wizard:

Open Control Center → Maps tab
In the Custom Maps card, click the overflow menu (⋮) → Create map (simple)
Fill in the map details:

Field	Required	Description
Map name	Yes	Display name (e.g., "Middle-earth", "Colonial Virginia")
Map image	Yes	Click "Browse" to select an image from your vault. Stored as a wikilink so Obsidian auto-updates the path if you move the image.
Universe	No	Group related maps (e.g., "tolkien", "got", "colonial-america")
Coordinate system	Yes	Geographic (lat/lng) or Pixel — see Coordinate Systems
Bounds/Dimensions	Yes	Define the coordinate space for your map

Click Create

The map note is created in your configured map notes folder (Settings → Charted Roots → Folders → Entity folders → Map notes folder).

From JSON Import

If you have a map configuration exported from another vault:

In the Custom Maps card, click Import JSON
Select a JSON file from your computer
If a map with the same ID already exists, you'll be warned
The imported map note is created in your map notes folder

Editing Map Properties

To modify an existing custom map:

In the Maps tab, hover over the map thumbnail
Click the Edit button (pencil icon)
Modify any properties:
- Change the name, image, or universe
- Adjust coordinate bounds or dimensions
- Switch coordinate systems
Click Save changes

You can also edit the map note directly in the editor — the frontmatter follows the format described in Frontmatter Reference.

Aligning a Map Image

Historical and hand-drawn maps often need adjustment to align properly with your coordinate system. The alignment feature lets you interactively position, scale, rotate, and distort your map image.

When You Need Alignment

Historical maps: Old maps have different projections or orientations
Fantasy maps: Hand-drawn maps rarely align with a coordinate grid
Scanned images: Scanning can introduce skew or distortion
Composite images: Maps assembled from multiple sources

Entering Edit Mode

Open Map View (from the Maps tab or Command Palette)
Select your custom map from the Map dropdown (not OpenStreetMap)
Click the Edit button in the toolbar
The edit banner appears with alignment controls

Using Corner Handles

When edit mode is active, four corner handles appear around your map image:

Drag any corner to reposition that corner independently
Drag opposite corners apart to scale the image
Drag adjacent corners to rotate or skew the image
The image updates in real-time as you drag

Tip: Start with small adjustments. It's easier to fine-tune incrementally than to fix large distortions.

Edit Banner Controls

Button	Function
Save alignment	Save corner positions to the map note's frontmatter
Undo changes	Revert to the last saved position (discards unsaved edits)
Reset to default	Clear all alignment and return to rectangular bounds
Cancel	Exit edit mode without saving

Alignment Workflow

Identify reference points on your map (cities, coastlines, rivers, landmarks)
Know target coordinates for those reference points
Start with rough positioning of one corner
Work around the map adjusting each corner
Verify with markers — add a test place and check its position
Save frequently as you refine the alignment

How Alignment is Stored

Corner positions are saved as flat properties in your map note's frontmatter:

---
cr_type: map
map_id: middle-earth
name: Middle-earth
image: "[assets/maps/middle-earth.jpg](/banisterious/obsidian-charted-roots/wiki/assets/maps/middle-earth.jpg)"
bounds:
  north: 50
  south: -50
  west: -100
  east: 100
# Saved alignment corners
corner_nw_lat: 48.5
corner_nw_lng: -95.2
corner_ne_lat: 49.1
corner_ne_lng: -58.3
corner_sw_lat: -45.8
corner_sw_lng: -98.1
corner_se_lat: -44.2
corner_se_lng: -55.7
---

When corner properties are present, the map loads with that alignment. When absent, the map displays with default rectangular bounds.

Using Your Custom Map

Once created, your custom map is available in several places:

Map View Dropdown

Open Map View (ribbon icon, Command Palette, or Maps tab)
Click the Map button in the toolbar
Select your custom map from the dropdown
All places with matching coordinates (or matching universe) appear on the map

Maps Tab Gallery

Click any map thumbnail to open it directly in Map View
Thumbnails show a preview of the map image with the name overlay

Split View Comparison

In Map View, click Split in the toolbar
Choose horizontal or vertical split
Select different maps in each pane to compare:
- Your custom map vs OpenStreetMap
- Two different historical periods
- Two fictional regions

Filtering by Universe

Places automatically appear on maps when:

The place has coordinates within the map's bounds, OR
The place's universe property matches the map's universe

This lets you create separate coordinate spaces for each fictional world without conflicts.

Working with Place Markers

Once your custom map is open in Map View, you can interact with place markers directly.

Dragging Markers

Reposition any place marker by dragging:

Click and hold on a place marker
Drag to the new position
Release to drop — coordinates are saved automatically to the place note

This works with both geographic (lat/lng) and pixel coordinate systems. The place note's frontmatter is updated immediately.

Right-Click Context Menu

Right-click any place marker to access quick actions:

Action	Description
Open place note	Navigate to the place's markdown note in the editor
Edit place	Open the Edit Place modal to modify name, category, parent, etc.
Remove from map	Clear the coordinates from the place note (marker disappears)

Adding New Places

To add a new place to an existing custom map:

Option 1: Right-click on the map

Right-click anywhere on the map image
Select Create place here
Fill in the Create Place modal — coordinates are pre-filled

Option 2: Create from Control Center

Open Control Center → Places → Create place note
Set the universe to match your map
Add coordinates manually (see Adding Places to Pixel-Based Maps)

Map Actions

Right-click a map thumbnail (or click the three-dot menu button) to access:

Action	Description
Open in Map View	View the map with all your places and people
Edit map	Open the Edit Map modal to modify properties
Duplicate map	Create a copy with a unique ID (useful for variations)
Export to JSON	Download map configuration for backup or sharing
Open note	View the raw map note in the editor
Delete map	Remove the map note (with confirmation)

Coordinate Systems

Charted Roots supports two coordinate systems for custom maps:

Geographic (Default)

Uses standard latitude/longitude coordinates. Best for:

Historical maps of real places
Maps that should align with OpenStreetMap
Places with known geographic coordinates

coordinate_system: geographic
bounds:
  north: 50    # Top edge latitude
  south: -50   # Bottom edge latitude
  west: -100   # Left edge longitude
  east: 100    # Right edge longitude

Pixel

Uses direct pixel coordinates with the origin at top-left. Best for:

Hand-drawn fantasy maps
Maps with arbitrary coordinate systems
Images where geographic coordinates don't apply

coordinate_system: pixel
image_width: 2048
image_height: 3072
center_x: 1024   # Optional: default center
center_y: 1536

Adding Places to Pixel-Based Maps

When using pixel coordinates, places need pixel_x and pixel_y properties instead of geographic coordinates. Currently, the Create Place modal doesn't have fields for pixel coordinates, so you'll need to add them manually:

Create the place note using Control Center → Places → Create place note
- Set the category to "Fictional" or "Mythological"
- Set the universe to match your map's universe
Open the place note in the editor
Add pixel coordinates to the frontmatter:

---
cr_type: place
name: Winterfell
place_category: fictional
universe: got
pixel_x: 450
pixel_y: 780
---

Finding pixel coordinates:

To determine the pixel coordinates for a location on your map image:

Open the map image in an image editor (or use your OS image viewer)
Hover over the desired location to see the pixel coordinates
Note the X (horizontal) and Y (vertical) values
The origin (0, 0) is at the top-left corner of the image

Tip: If your image editor shows coordinates from the bottom-left, subtract the Y value from the image height to convert to top-left origin.

Linked Maps (Drill-Down Navigation)

You can link related maps together so that clicking a place marker on one map navigates to another. This is useful for multi-scale maps — for example, a continental overview map with a detailed regional map for a specific area.

Setting Up a Linked Map

Create both maps (e.g., "The Dying Earth" continent map and "River Scaum" regional map)
Create a place note at the location where the maps connect (e.g., "Scaum")
Place the marker on the parent map with coordinates
Add linked_map to the place note's frontmatter, using the map_id of the target map:

---
cr_type: place
name: Scaum
universe: The Dying Earth
custom_coordinates_x: 5200
custom_coordinates_y: 2400
maps:
  - the-dying-earth
linked_map: river-scaum-and-its-major-tributaries
---

How It Works

When you click the place marker on the parent map, the popup shows an additional button: "Open River Scaum and its Major Tributaries ↗"
Clicking the button switches the Map View to the linked map
The regular "Open place" button still works to open the place note

Tips

The linked_map value must match the map_id field on the target map note
Use the maps array on the place note to ensure the marker only appears on the relevant parent map
You can link maps in both directions — add linked_map on a place in the child map pointing back to the parent map's map_id

Map Hierarchy and Breadcrumbs

You can establish parent-child relationships between maps using the parent_map property on the child map note:

---
cr_type: map
map_id: river-scaum-and-its-major-tributaries
name: River Scaum and its Major Tributaries
parent_map: the-dying-earth
---

When viewing a child map, a breadcrumb appears in the toolbar: The Dying Earth → River Scaum and its Major Tributaries. Clicking the parent name navigates back to the parent map.

The Map Creation Wizard includes a "Parent map" dropdown in Step 2 to set this automatically.

Overlay Regions

Child maps can define where they sit on the parent map using region coordinates:

---
cr_type: map
map_id: river-scaum-and-its-major-tributaries
parent_map: the-dying-earth
parent_region_x: 4700
parent_region_y: 1300
parent_region_w: 1500
parent_region_h: 1200
---

When the parent map is viewed, child maps with overlay regions are rendered as clickable dashed blue rectangles. Hovering shows the child map name as a tooltip, and clicking drills down to the child map.

parent_region_x, parent_region_y — top-left corner position in the parent map's coordinate system
parent_region_w, parent_region_h — width and height of the region

Child Map Markers

Every child map with parent_map set gets a gold map-icon marker on the parent map, regardless of whether parent_region coordinates are defined. This ensures child maps are always discoverable.

Markers are positioned at the center of the parent_region if defined, or at the parent map center as a fallback
Clicking a marker opens a popup with the child map name, an Open map button, and an Edit region (or Draw region) button
Use the Child maps toggle in the Layers menu to show or hide all child map markers and overlay rectangles

Configuration	What appears on parent map
`parent_map` only	Gold marker at map center + breadcrumb
`parent_map` + `parent_region`	Gold marker + overlay rectangle + breadcrumb
`parent_map` + `parent_region` + `linked_map` on place	Place marker + gold marker + overlay rectangle + breadcrumb

Editing Regions on the Map

The most precise way to define a child map's region is directly on the parent map:

Open the parent map in Map View
Zoom and pan to where the child map should sit
Click a child map marker to open its popup
Click Edit region (or Draw region if no region exists yet)
A dashed blue rectangle appears with four corner handles:
- Drag the rectangle to reposition it
- Drag any corner handle to resize it
A floating toolbar at the top shows the child map name with Save and Cancel buttons
Click Save region to write the coordinates to the child map's frontmatter

You can also set the region during map creation using the Draw region button in the Map Creation Wizard (Step 2), or via the right-click context menu on a child map note (Draw/Edit parent region).

Frontmatter Reference

Complete map note frontmatter:

---
cr_type: map
map_id: my-custom-map          # Unique identifier
name: My Custom Map            # Display name
universe: my-world             # Optional: group with places
image: "[path/to/map-image.jpg](/banisterious/obsidian-charted-roots/wiki/path/to/map-image.jpg)"   # Wikilink to image (auto-updates if moved)

# Geographic coordinate system
coordinate_system: geographic
bounds:
  north: 50
  south: -50
  west: -100
  east: 100

# OR Pixel coordinate system
coordinate_system: pixel
image_width: 2048
image_height: 3072
center_x: 1024
center_y: 1536

# Optional: saved alignment corners
corner_nw_lat: 48.5
corner_nw_lng: -95.2
corner_ne_lat: 49.1
corner_ne_lng: -58.3
corner_sw_lat: -45.8
corner_sw_lng: -98.1
corner_se_lat: -44.2
corner_se_lng: -55.7

# Optional: map hierarchy (#361)
parent_map: parent-map-id         # map_id of the parent map
parent_region_x: 4700             # Overlay region on parent map
parent_region_y: 1300
parent_region_w: 1500
parent_region_h: 1200
---

# My Custom Map

Optional notes about the map...