This repo contains the source code and project support files for the interactive map of Golarion used by the PathfinderWiki. It contains:
wiki-downloader bot that routinely fetches and compiles those coordinates from PathfinderWiki articlesTo view the current map, go to https://map.pathfinderwiki.com.
This project is coordinated on the PathfinderWiki Discord server's #golarion-mapping channel.
The kart command-line tool works very similarly to git, but uses a custom index format to manage geospatial data and present it as a geopackage file instead of the normal filesystem. Kart also integrates with QGIS to create
To check out the mapping-data repository in geopackage format:
mapping-data next to the directory containing this repo: kart clone git@github.com:pf-wikis/mapping-datasources/qgis.qgs in this repository. If the mapping-data repository is in the same parent path as the mapping repository, the project should automatically find and load the GeoPackage data file and GeoJSON location files containing the project's layers.For general information about the map project, see the Map article on PathfinderWiki.
You can provide or update the coordinates of cities and points of interest by editing their corresponding PathfinderWiki articles. For locations lacking articles on PathfinderWiki, enter their coordinates on the PathfinderWiki:Map Locations Without Articles project page. A bot routinely fetches and compiles these coordinates from PathfinderWiki into GeoJSON files that are included in the generated map tiles and populate the cities and locations layers of the QGIS project file.
Do not attempt to modify these coordinates in the cities and locations GeoJSON files in this repository, which are automatically overwritten by wiki-sourced data.
For more information, see Help:Map on PathfinderWiki. To register an account on PathfinderWiki, see Special:RequestAccount.
Features that are polygonal shapes or lines, such as landmasses, bodies of water, rivers, borders, etc., are managed as geospatial data in a separate Kart repository, pf-wikis/mapping-data. We use QGIS to edit these features.
QGIS is a Geographic Information System (GIS) that allows for precise editing of geographic data. While its interface is somewhat similar to vector drawing tools such as Inkscape or Adobe Illustrator, it is fundamentally a data editing tool and follows different user interface paradaigms that might be unfamiliar if you don't have prior GIS experience. There are several tutorials that review QGIS's basic interface and usage, such as GeoDelta Labs' 1-hour beginner's guide.
To install QGIS:
The current LTS version of QGIS is sufficient for editing, and the latest stable version might also be compatible. If in doubt, check with other volunteers in the PathfinderWiki Discord server's #golarion-mapping channel. Editing the project file itself is not necessary unless you've added a georeferenced raster image; see "(Optional) Check out raster source map images".
After installing QGIS, launch it and install the Trackable QGIS Project plugins required for working on this project.
These plugins are also recommended for installation:
This project uses Kart, a git-like tool that uses a custom index format to manage and track changes to geospatial data and present it as a GeoPackage file, instead of git's use of a normal filesystem. QGIS can open this GeoPackage file to view and modify its layers.
To check out the mapping-data repository in GeoPackage format:
kart command to clone the pf-wikis/mapping-data repository into a directory called mapping-data next to the directory containing this repo: kart clone git@github.com:pf-wikis/mapping-dataThe kart command-line tool works similarly to git, including commands to fetch, pull, merge, branch, and commit changes to the repository.
To suggest changes you've made to geometry:
pf-wikis/mapping-data repository on GitHub.kart to add your fork to your local repository: kart remote add REMOTENAME git@github.com:USERNAME/mapping-data, where REMOTENAME can be any name you want to use to refer to your fork, and USERNAME is your GitHub username for your fork.kart switch -c my-changes, where my-changes can be any valid git branch name.kart commit -m "Changes to map data", where Changes to map data is your commit message.kart push -u REMOTENAME my-changes.main branch of pf-wikis/mapping-data.The Kart plugin for QGIS can visualize differences between your working changes and the branch you're working on, or between commits within the repository. Including screenshots of these differences that depict your requested changes can help illustrate them to reviewers. You can also use the plugin to manage your local clone of the repository. For details, see the plugin's documentation.
Geometry in the mapping-data repository is created by project volunteers who attempt to georeference raster maps published by Paizo and interpret features on those maps as vector layer data in QGIS. Paizo owns the copyright of these raster source map images, which cannot be publicly shared under the Community Use Policy or other licenses. The mapping project provides access to these images only to volunteers who have individually requested and been granted access.
If you have been granted permission to access these raster maps, you can download them by following these steps:
dvc remote modify --local webdav password THEPASSWORDdvc install. This sets up automatic git hooks so that DVC pushes content when you push with git.dvc pull to download the images. If this is your first time pulling images, you will have to authenticate with the account that has been granted access to the external map storage.Georeferencing these images is a complex and subjective process that requires coordination with other volunteers. To request access or coordinate georeferencing efforts, please join the PathfinderWiki Discord server's #golarion-mapping channel.
Open the QGIS project file located at sources/qgis.qgs in this repository. If everything is correct, the QGIS project should automatically locate the GeoPackage file containing feature geometry layers.
If QGIS warns about missing raster layers in a Handle Unavailable Layers dialog, click Keep Unavailable Layers; they aren't required. See "(Optional) Check out raster source map images".
The project contains separate polygon, line, and point layers for features. Labels for most features are stored in their attribute table (F6 or Layer->Open attribute table). The borders layer defines national borders, the districts layer defines sub-national regions, and the labels layer defines other types of regions that require labels, including ocean regions and island chains. The tile generation tool automatically smooths the lines or shapes for these feature types.
The rivers layer attributes table contains the width used for the feature. Rivers might be intentionally segemented into multiple connected but distinct features to apply different widths. The tile generator automatically smooths rivers and tapers their widths near their ends. As such, you should extend the lines of river features significantly into the geometry of any body of water that they empty into.
Remember to save changes to geometry layers! It is easy to lose work in QGIS if you do not save changes to layers.
If you're interested in contributing to development of the map website's user interface or tile-generation process, we recommend coordinating with other mapping project members on the PathfinderWiki Discord server's #golarion-mapping channel.
This project contains a Java tile-compiler tool that generates layered vector tiles from the mapping-data repository's data and compiles them into a single Protomaps tiles (PMTiles) file. It also contains a frontend that renders the PMTiles file using maplibre-gl-js in a TypeScript project.
The map website is built on a Debian-based Linux system. If you use Windows or macOS, building the website locally might be more complex.
To locally build the website to test changes to mapping data, you must first build the PMTiles file from the mapping data, then build the maplibre-gl-js frontend and run the local development server. This can require installing several dependencies, including Java SDK 21+, Node.js, and Tippecanoe.
See also the GitHub Actions Dockerfile, which includes the commands used to automate installing requirements on a Debian-based Linux operating system for testing and publishing the website.
openjdk-21-jdk or java-21-openjdk-devel, maven or maven-openjdk21, nodejs, and npm.libsqlite3x-devel and zlib-devel.gdal and grass.npm install mapshaper geojson-polygon-labels curve-interpolator@3.0.1 @indoorequal/spritezero-clipf-wikis/mapping repo with git: git clone https://github.com/pf-wikis/mapping.pf-wikis/mapping-data kart repository into a directory called mapping-data next to the directory containing the mapping repo: kart clone https://github.com/pf-wikis/mapping-data.Install and run the map tile compiler from the tile-compiler directory:
cd mapping/tile-compiler
./run.shIf this step fails, examine any error messages for information about potentially missing dependencies or errors in the source data.
If you have multiple versions of the JDK installed on your system, you might need to specify a compatible JDK using the JAVA_HOME environment variable. For example, when invoking the run.sh script, use:
JAVAHOME=/usr/lib/jvm/java-21-openjdk-21.0.3.0.9-1.fc40.x86_64/bin ./run.shwhere /usr/lib/jvm/java-21-openjdk-21.0.3.0.9-1.fc40.x86_64/bin is the path to a compatible JDK installation's java and javac binaries.
npm install from the frontend directory:
cd ../frontend
npm iRun the frontend from the frontend directory:
npm startThis launches a local webserver on a non-privileged port, such as http://localhost:5173/. Open this URL in a web browser to view the locally built map.
This mapping project uses trademarks and/or copyrights owned by Paizo Inc., used under Paizo's Community Use Policy (paizo.com/licenses/communityuse). We are expressly prohibited from charging you to use or access this content. This mapping project is not published, endorsed, or specifically approved by Paizo. For more information about Paizo Inc. and Paizo products, visit paizo.com.
Significant data in this project is based on GIS data first compiled by John Mechalas and contributions to that project from Oznogon, who produced and previously hosted the first interactive map from that data.
Several contributors have provided or updated coordinates and geometry in this project, as visible in the history of this repository and the pf-wikis/mapping-data repository. Others have contributed city and point-of-interest positions by editing PathfinderWiki articles, as visible in the History tab of each city and location's related articles or the PathfinderWiki:Map Locations Without Articles project page.