diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..9d0e5c7f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,29 @@ +name: Documentation +on: + push: + branches: + - master + - main +permissions: + contents: read + pages: write + id-token: write +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/configure-pages@v5 + - uses: actions/checkout@v5 + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: pip install zensical + - run: zensical build --clean + - uses: actions/upload-pages-artifact@v4 + with: + path: site + - uses: actions/deploy-pages@v4 + id: deployment diff --git a/.gitignore b/.gitignore index 724b7995..07dbfd06 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +site + tests/root .ohmg_api_key diff --git a/README.md b/README.md index c794b594..e3aa3d6a 100644 --- a/README.md +++ b/README.md @@ -12,283 +12,5 @@ Please don't hesitate to [open a ticket](https://github.com/ohmg-dev/OldInsuranc --- -## Software Details +## Contributing -OHMG uses the [Django](https://www.djangoproject.com/) web framework for URL routing, auth, and the ORM, and [Django Ninja](https://django-ninja.dev) to create an API. - -The frontend is built (mostly) with [Svelte](https://svelte.dev), using [OpenLayers](https://openlayers.org) for all map interfaces. [OpenStreetMap](https://openstreetmap.org) and [Mapbox](https://www.mapbox.com) are the basemap sources. - -Other components include: - -- [Postgres + PostGIS](https://postgis.net/) - - Database -- [GDAL](https://gdal.org/en/stable/) - - A dependency of PostGIS, and also used directly for all warping/mosaicking operations. -- [Celery + RabbitMQ](https://docs.celeryq.dev/en/stable/getting-started/backends-and-brokers/rabbitmq.html) - - Background task management (a handful of loading/splitting/warping processes run in the background) -- [TiTiler](https://developmentseed.org/titiler) - - Tileserver for COGs (Cloud Optimized GeoTIFFs) - -## Installation - -Running the application requires a number of components to be installed and configured properly. The following commands assume a Debian-based Linux distribution. - -### Install system dependencies - -You will need a few system packages. - -```bash -sudo apt install build-essential gdal-bin python3-gdal libgeos-dev libgdal-dev -``` - -Extra dependencies helpful during development: - -```bash -sudo apt install graphviz graphviz-dev pre-commit -``` - -> [!NOTE] -> 3.5 is the minimum GDAL version that the app requires, so the system gdal installation must be >= or higher than that, however, the version of the Python bindings must be <= to the system version. While pinning a specific Python version is easy, anticipating the exact system gdal across distros is trickier (Debian 13: 3.10.3, Debian 12: 3.6.2, Ubuntu 24: 3.8.4, [etc.](https://pkgs.org/download/gdal)). The solution here is to install whatever GDAL comes with the distro, and pin the Python bindings in `pyproject.toml` very low (between 3.5 and 3.6), to ensure maximum liklihood of a smooth installation. - -### Get the source code - -Clone the repo and enter the local directory - -```bash -git clone https://github.com/ohmg-dev/OldInsuranceMaps && cd OldInsuranceMaps -``` - -### Install with `uv` - -First, [install `uv`](https://docs.astral.sh/uv/getting-started/installation/), an all-in-one Python version and package manager. - -With `uv` installed, run this command inside the cloned repo: - -```bash -uv sync --extra dev -``` - -This will: - -1. Install the proper version of Python -2. Create a new virtual environment in `.venv` -3. Install all Python dependencies into that environment. - -Next, install pre-commit hook (if you will be writing code) - -```bash -pre-commit install -``` - -Use the `.env.example` to create your `.env` file - -```bash -cp .env.example .env -``` - -See [environment variables](#environment-variables) for more information. - -### Initialize database - -In your running Postgres instance, create a database like this - -```bash -psql -U postgres -c "CREATE USER ohmg WITH ENCRYPTED PASSWORD '$DB_PASSWORD'" -psql -U postgres -c "CREATE DATABASE oldinsurancemaps WITH OWNER ohmg;" -psql -U postgres -d oldinsurancemaps -c "CREATE EXTENSION PostGIS;" -``` - -Run migrations and create admin user to access the Django admin panel (and login to the site once it's running) - -```bash -python manage.py migrate -python manage.py createsuperuser -``` - -Load a few other fixtures with some default objects: - -```bash -python manage.py loaddata default-region-categories -python manage.py loaddata default-layerset-categories -python manage.py loaddata default-navbar -``` - -Alternatively, if you have set all of the `DATABASE_*` variables in `.env`, you can use the included script to perform all of the actions described above: - -```bash -source ./scripts/setup_database.sh -``` - -The superuser created by this script is username: `admin`, password: `admin`. - -Load test data into database (optional) - -```bash -source ./scripts/load_dev_data.sh -``` - -### Build frontend - -There are a few js and css plugins that must be downloaded to the local static directory: - -```bash -python manage.py get-plugins -``` - -The frontend uses a suite of independently built svelte components. First install `pnpm`: https://pnpm.io/installation. Then: - -```bash -cd ohmg/frontend/svelte_components -pnpm install -``` - -During development use the following command to auto-build the components and reload your browser. - -```bash -pnpm run dev -``` - -In production, use the `build` command instead, and then Django's `collectstatic` to consolidate all static assets. - -```bash -pnpm run build -cd ../../.. -python manage.py collectstatic --noinput -``` - -This bash script combines all steps into one: - -```bash -source ./scripts/deploy_frontend.sh -``` - -### Run Django dev server - -You can now activate the virtual environment and then run the django dev server: - -```bash -source .venv/bin/activate -python manage.py runserver -``` - -and view the site at `http://localhost:8000`. - -However, a few more pieces need to be set up independently before the app will be fully functional. Complete the following sections and then restart the dev server so that any new `.env` values will be properly acquired. - -> [!NOTE] -> You can also skip the virtualenv activation and use uv to run management commands like this: -> -> ```bash -> uv run manage.py runserver -> ``` - -### Rabbit + Celery - -In development, RabbitMQ can be run via Docker like so: - -```bash -docker run --name rabbitmq --hostname my-rabbit \ - -p 5672:5672 \ - -p 15672:15672 \ - -e RABBITMQ_DEFAULT_USER=username \ - -e RABBITMQ_DEFAULT_PASS=password \ - --rm \ - rabbitmq:3-alpine -``` - -For convenience, this command is in the following script: - -```bash -source ./scripts/rabbit_dev.sh -``` - -Once RabbitMQ is running, update `.env` with the `RABBITMQ_DEFAULT_USER` and `RABBITMQ_DEFAULT_PASS` credentials you used above when creating the container. - -Now you are ready to run Celery in development with: - -```bash -source ./scripts/celery_dev.sh -``` - -### TiTiler - -TiTiler can also be run via Docker, using a slightly modified version of the official container (it is only modified to include the WMS endpoint extension): - -```bash -docker run --name titiler \ - -p 8008:8000 \ - -e PORT=8000 \ - -e MOSAIC_STRICT_ZOOM=False \ - -e WORKERS_PER_CORE=1 \ - --rm \ - -it \ - ghcr.io/mradamcox/titiler:0.26.0-ohmg -``` - -Or the same command is wrapped in: - -```bash -source ./scripts/titiler_dev.sh -``` - -This will start a container running TiTiler and expose it to `localhost:8008`. - -Make sure you have `TITILER_HOST=http://localhost:8008` in `.env` (see [environment variables](#environment-variables)). - -### Static file server - -During development, a separate HTTP server must be used to supply TiTiler with COG endpoints, because the Django dev server does not serve HTTP range requests (more on this [here](https://code.djangoproject.com/ticket/22479) and [here](https://github.com/python/cpython/issues/86809)). The easiest workaround is to use node's [http-server](https://www.npmjs.com/package/http-server). - -From within the repository root (alongside the `uploaded` directory) run: - -```bash -npx http-server . -``` - -All COGs will now be accessible at `http://localhost:8080/uploaded/`. - ---- - -Make sure you have `LOCAL_MEDIA_HOST=http://localhost:8080` in `.env`. `LOCAL_MEDIA_HOST` is a prefix that will be prepended to any uploaded media paths that are passed to TiTiler. - -In production, you will already be using a webserver for static files so you will not need to use `http-server`. In this case, remove `LOCAL_MEDIA_HOST` from `.env` or set it to `''`. - -## Running tests - -All tests are stored in `ohmg/tests`. Make sure you have installed dev requirements, then run: - -```bash -python manage.py test -``` - -To skip the tests that make external calls to the LOC API, use the following command. Keep in mind that coverage numbers will be lower when you skip tests. - -```bash -python manage.py test --exclude-tag=loc -``` - -## Install the Place scaffolding - -Load all the place objects to create geography scaffolding (this will take a minute or two) - -```bash -python manage.py place import-all -``` - -## Environment variables - -_section in progress_ - - diff --git a/docs/_assets/stylesheets/extra.css b/docs/_assets/stylesheets/extra.css new file mode 100644 index 00000000..cb792557 --- /dev/null +++ b/docs/_assets/stylesheets/extra.css @@ -0,0 +1,42 @@ +:root { + --md-primary-fg-color: #123B4F; + --md-primary-fg-color--light: #F7F1E1; + --md-primary-fg-color--dark: #90030C; + --md-text-font-family: 'Josefin Sans'; +} + +body { + font-size: 1.1em; +} + +a { + text-decoration: underline; +} + +/* Light mode */ +[data-md-color-scheme="default"] { + --md-default-bg-color: #F7F1E1; +} + +/* Dark mode */ +[data-md-color-scheme="slate"] { + --md-default-bg-color: #F7F1E1; +} + + +figcaption { + font-style: italic; + font-size: .85em; +} + +/* override glightbox caption font family */ +.glightbox-clean .gslide-title { + font-family: 'Josefin Sans' !important; +} + +/* .md-main > .md-grid { + margin-top: 0; + padding-top: 1em; + box-shadow: gray 0px 0px 5px; + background-color: #eae0c1 +} */ \ No newline at end of file diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 00000000..bc842919 --- /dev/null +++ b/docs/contact.md @@ -0,0 +1,17 @@ +# Contact + +## Forum + +[OpenHistoricalMap Forum → OldInsuranceMaps.net](https://forum.openhistoricalmap.org/c/oldinsurancemaps/13) + +We have a dedicated category in the OpenHistoricalMap forum just for OldInsuranceMaps.net! Drop by and introduce yourself there, and feel free to ask questions about the project and how people are using it. + +## News + +Newsletter archives (and signup) can be found at [oldinsurancemaps.net/news](https://oldinsurancemaps.net/news). + +## Contact + +Questions, concerns, or feedback: [hello@oldinsurancemaps.net](mailto:hello@oldinsurancemaps.net) + +Bugs and technical discussion: [github.com/ohmg-dev/OldInsuranceMaps](https://github.com/ohmg-dev/OldInsuranceMaps) diff --git a/docs/developers/data-model.md b/docs/developers/data-model.md new file mode 100644 index 00000000..d8e37507 --- /dev/null +++ b/docs/developers/data-model.md @@ -0,0 +1,21 @@ +# Data model & concepts (in progress) + +!!! note + + This section still in progress. See [ohmg.dev](https://www.ohmg.dev/concepts) for more information about the structure of the database. + +!!! note + + This section mentions `TrimSession`, which is a model that was deprecated a long time ago when multimask was introduced, but should be reintroduced eventually. + +All georeferencing activity is stored in `SessionBase` objects, as implemented through the proxy models `PrepSession`, `GeorefSession`, and `TrimSession`. Each proxy model has its own implementation of a `run()` method which uses the information in the `data` field to perform the appropriate actions. + +![Data model for the georeference app.](../images/georeference-data-model-sans-links.png) + +#### Narrative Explanation + +When a user begins preparing a Document, a new `PrepSession` is created. If the user creates cutlines to split the document, this information is saved in the session's `data` field as JSON and then used to run the splitting action that creates new child documents (the original document is not altered). + +When a user begins georeferencing a Document, a new `GeorefSession` is created. When the ground control points have been created and submitted through the interface, they are stored as GeoJSON in the session's `data` field and then used to warp the Document and create a Layer. Finally, they are saved separately as `GCP` objects and aggregated into 1 `GCPGroup` per Document. This facilitates iterative editing of the Document's "canonical" GCPs, while also allowing for the reversion to a past set of GCPs if necessary. + +Similarly, a user creates a `TrimSession` when they begin trimming a Layer. The mask polygon is stored in the session's `data` and then pushed to the Layer's canonical `LayerMask` object, and applied as a cropped style in Geoserver. diff --git a/docs/developers/install.md b/docs/developers/install.md new file mode 100644 index 00000000..e12dc00f --- /dev/null +++ b/docs/developers/install.md @@ -0,0 +1,292 @@ + +# Creating a development installation + +Running the application requires a number of components to be installed and configured properly. The following commands assume a Debian-based Linux distribution. + +## Stack overview + +OHMG uses the [Django](https://www.djangoproject.com/) web framework for URL routing, auth, and the ORM, and [Django Ninja](https://django-ninja.dev) to create an API. + +The frontend incorporates many independently built [Svelte](https://svelte.dev) components, using [OpenLayers](https://openlayers.org) for all map interfaces. [OpenStreetMap](https://openstreetmap.org) and [Mapbox](https://www.mapbox.com) are the basemap sources. + +Other components include: + +- [Postgres + PostGIS](https://postgis.net/) + - Database +- [GDAL](https://gdal.org/en/stable/) + - A dependency of PostGIS, and also used directly for all warping/mosaicking operations. +- [Celery + RabbitMQ](https://docs.celeryq.dev/en/stable/getting-started/backends-and-brokers/rabbitmq.html) + - Background task management (a handful of loading/splitting/warping processes run in the background) +- [TiTiler](https://developmentseed.org/titiler) + - Tileserver for COGs (Cloud Optimized GeoTIFFs) + +## System dependencies + +You will need a few system packages. + +```bash +sudo apt install build-essential gdal-bin python3-gdal libgeos-dev libgdal-dev +``` + +Extra dependencies helpful during development: + +```bash +sudo apt install graphviz graphviz-dev pre-commit +``` + +!!! note + + 3.5 is the minimum GDAL version that the app requires, so the system gdal installation must be >= or higher than that, however, the version of the Python bindings must be <= to the system version. While pinning a specific Python version is easy, anticipating the exact system gdal across distros is trickier (Debian 13: 3.10.3, Debian 12: 3.6.2, Ubuntu 24: 3.8.4, [etc.](https://pkgs.org/download/gdal)). The solution here is to install whatever GDAL comes with the distro, and pin the Python bindings in `pyproject.toml` very low (between 3.5 and 3.6), to ensure maximum liklihood of a smooth installation. + +## Install the Django app + +### Get the source code + +Clone the repo and enter the local directory + +```bash +git clone https://github.com/ohmg-dev/OldInsuranceMaps && cd OldInsuranceMaps +``` + +### Install with `uv` + +First, [install `uv`](https://docs.astral.sh/uv/getting-started/installation/), an all-in-one Python version and package manager. + +With `uv` installed, run this command inside the cloned repo: + +```bash +uv sync --extra dev +``` + +This will: + +1. Install the proper version of Python +2. Create a new virtual environment in `.venv` +3. Install all Python dependencies into that environment. + +Next, install pre-commit hook (if you will be writing code) + +```bash +pre-commit install +``` + +Use the `.env.example` to create your `.env` file + +```bash +cp .env.example .env +``` + +See [environment variables](#environment-variables) for more information. + +### Initialize database + +In your running Postgres instance, create a database like this + +```bash +psql -U postgres -c "CREATE USER ohmg WITH ENCRYPTED PASSWORD '$DB_PASSWORD'" +psql -U postgres -c "CREATE DATABASE oldinsurancemaps WITH OWNER ohmg;" +psql -U postgres -d oldinsurancemaps -c "CREATE EXTENSION PostGIS;" +``` + +Run migrations and create admin user to access the Django admin panel (and login to the site once it's running) + +```bash +python manage.py migrate +python manage.py createsuperuser +``` + +Load a few other fixtures with some default objects: + +```bash +python manage.py loaddata default-region-categories +python manage.py loaddata default-layerset-categories +python manage.py loaddata default-navbar +``` + +Alternatively, if you have set all of the `DATABASE_*` variables in `.env`, you can use the included script to perform all of the actions described above: + +```bash +source ./scripts/setup_database.sh +``` + +The superuser created by this script is username: `admin`, password: `admin`. + +Load test data into database (optional) + +```bash +source ./scripts/load_dev_data.sh +``` + +### Frontend assets + +There are a few js and css plugins that must be downloaded to the local static directory: + +```bash +python manage.py get-plugins +``` + +The frontend uses a suite of independently built svelte components. First install `pnpm`: https://pnpm.io/installation. Then: + +```bash +cd ohmg/frontend/svelte_components +pnpm install +``` + +During development use the following command to auto-build the components and reload your browser. + +```bash +pnpm run dev +``` + +You can also use the `--configComponent` argument to only build the specific component(s) that you are working on, which greatly improve the development experience. You can pass that argument a comma-separated list of component names as well: + +```bash +pnpm run dev --configComponent Georeference,Split +``` + + +In production, use the `build` command instead, and then Django's `collectstatic` to consolidate all static assets. + +```bash +pnpm run build +cd ../../.. +python manage.py collectstatic --noinput +``` + +This bash script combines all steps into one: + +```bash +source ./scripts/deploy_frontend.sh +``` + +### Run Django dev server + +You can now activate the virtual environment and then run the django dev server: + +```bash +source .venv/bin/activate +python manage.py runserver +``` + +and view the site at `http://localhost:8000`. + +However, a few more pieces need to be set up independently before the app will be fully functional. Complete the following sections and then restart the dev server so that any new `.env` values will be properly acquired. + +!!! note + + You can also skip the virtualenv activation and use uv to run management commands like this: + + ```bash + uv run manage.py runserver + ``` + +## Rabbit + Celery + +In development, RabbitMQ can be run via Docker like so: + +```bash +docker run --name rabbitmq --hostname my-rabbit \ + -p 5672:5672 \ + -p 15672:15672 \ + -e RABBITMQ_DEFAULT_USER=username \ + -e RABBITMQ_DEFAULT_PASS=password \ + --rm \ + rabbitmq:3-alpine +``` + +For convenience, this command is in the following script: + +```bash +source ./scripts/rabbit_dev.sh +``` + +Once RabbitMQ is running, update `.env` with the `RABBITMQ_DEFAULT_USER` and `RABBITMQ_DEFAULT_PASS` credentials you used above when creating the container. + +Now you are ready to run Celery in development with: + +```bash +source ./scripts/celery_dev.sh +``` + +## TiTiler + +TiTiler can also be run via Docker, using a slightly modified version of the official container (it is only modified to include the WMS endpoint extension): + +```bash +docker run --name titiler \ + -p 8008:8000 \ + -e PORT=8000 \ + -e MOSAIC_STRICT_ZOOM=False \ + -e WORKERS_PER_CORE=1 \ + --rm \ + -it \ + ghcr.io/mradamcox/titiler:0.26.0-ohmg +``` + +Or the same command is wrapped in: + +```bash +source ./scripts/titiler_dev.sh +``` + +This will start a container running TiTiler and expose it to `localhost:8008`. + +Make sure you have `TITILER_HOST=http://localhost:8008` in `.env` (see [environment variables](#environment-variables)). + +### You need a atatic file server + +During development, a separate HTTP server must be used to supply TiTiler with COG endpoints, because the Django dev server does not serve HTTP range requests (more on this [here](https://code.djangoproject.com/ticket/22479) and [here](https://github.com/python/cpython/issues/86809)). The easiest workaround is to use node's [http-server](https://www.npmjs.com/package/http-server). + +From within the repository root (alongside the `uploaded` directory) run: + +```bash +npx http-server . +``` + +All COGs will now be accessible at `http://localhost:8080/uploaded/`. + +--- + +Make sure you have `LOCAL_MEDIA_HOST=http://localhost:8080` in `.env`. `LOCAL_MEDIA_HOST` is a prefix that will be prepended to any uploaded media paths that are passed to TiTiler. + +In production, you will already be using a webserver for static files so you will not need to use `http-server`. In this case, remove `LOCAL_MEDIA_HOST` from `.env` or set it to `''`. + +## Running tests + +All tests are stored in `ohmg/tests`. Make sure you have installed dev requirements, then run: + +```bash +python manage.py test +``` + +To skip the tests that make external calls to the LOC API, use the following command. Keep in mind that coverage numbers will be lower when you skip tests. + +```bash +python manage.py test --exclude-tag=loc +``` + +## Load the Place scaffolding + +Load all the place objects to create geography scaffolding (this will take a minute or two) + +```bash +python manage.py place import-all +``` + +## Environment variables + +_section in progress_ + + diff --git a/docs/developers/loading-maps.md b/docs/developers/loading-maps.md new file mode 100644 index 00000000..bde915e8 --- /dev/null +++ b/docs/developers/loading-maps.md @@ -0,0 +1,25 @@ +# Loading maps + +Currently, maps are loaded only through the command line. The application can be extended with multiple import modules and one of these modules must be specified in the load command with the `-c` parameter. + +Each import module has its own set of required extra options, and these are provided through the `--opts` parameter. + +The most common load pattern is to use the importer for items from the LOC Sanborn map collection (`-c loc-sanborn`), which requires two extra options (`--opts identifier= locale=`). The New Iberia, La., 1892 map would be loaded like this: + +``` +uv run manage.py map add -c loc-sanborn --opts identifier=sanborn03375_002 locale=new-iberia-la +``` + +To see all available import configurations run: + +``` +uv run manage.py map list-importers +``` + +!!! note + + Only the `loc-sanborn` importer is regularly used, so there is no guarantee the others will work right now. + +## Bulk loading + +You can bulk load maps by specifying a configuration (`-c`) and then passing the `--bulk-file ` instead of `--opts`. In this case, the provided CSV file must have columns for each required `--opts` entry for a specified configuration, and one row per map to load. diff --git a/docs/getting-started/finding-maps.md b/docs/getting-started/finding-maps.md new file mode 100644 index 00000000..68a0227f --- /dev/null +++ b/docs/getting-started/finding-maps.md @@ -0,0 +1,41 @@ +# Finding maps + +You can search for map content in three different ways, all of which are accessible in the main [Browse](https://oldinsurancemaps.net/browse) page. + +1. [Browse by Map](#browse-by-map) +2. [Browse by Place](#browse-by-place) +3. [Browse by Volume](#browse-by-volume) + +Generally, each method can be used to find any map in the system, but there are a few subtleties to be aware of. + +## Browse by Map + +Click a point on the map to view its georeferenced Sanborn Maps. Click **view →** to open the [viewer](./viewer.md) for all volumes at once, or choose a volume/edition to go to its detailed summary. + +![Browse by map interface](../images/browse-by-map.png) + +Points on the map represent "places" (generally, cities, towns, or villages) with at least one volume that has at least one georeferenced document (the point is the centroid of all layer extents). This means that if volumes have been loaded for a place but none of their sheets have been georeferenced, there will be no way to find that content through this search method. + +## Browse by Place + +Find a place by name. Click the place name to open it in the main viewer, or choose a year to go directly to that volume summary. + +![Browse by map interface](../images/browse-by-place.png) + +## Browse by Volume + +Search volumes by name, and click the title to go to the volume summary. You can sort the table by any column. + +![Browse by volume interface]../images/browse-by-volume.png) + +On the right, you'll see abbreviated columns holding more detailed information about the volume: + +| | | +|-------------------------|-----------| +| **U** | Number of unprepared sheets | +| **P** | Number of prepared prepared documents (i.e. ready to be georeferenced) | +| **G** | Number of georeferenced documents | +| **%** | Overall percentage of georeferenced documents from the volume | +| **MM** | Number of georeferenced layers that are included in the volume's "multimask". Typically the denominator will be one less than the number of georeferenced layers because the multimask will not include the volume's key map. | + +Power users can sort on these columns to see where their work can be the most effective. \ No newline at end of file diff --git a/docs/getting-started/georeferencing.md b/docs/getting-started/georeferencing.md new file mode 100644 index 00000000..a739f6cb --- /dev/null +++ b/docs/getting-started/georeferencing.md @@ -0,0 +1,4 @@ +# Becoming a georeferencer + +All you need to do to begin georeferencing content on _OldInsuranceMaps.net_ is create an account. You must agree that any contributions you make will be licensed [CC0](https://creativecommons.org/public-domain/cc0/) ("No Rights Reserved"), meaning that your work is effectively in the public domain. See the [Data Agreement](https://oldinsurancemaps.net/data-agreement) for more details about this. + diff --git a/docs/getting-started/viewer.md b/docs/getting-started/viewer.md new file mode 100644 index 00000000..bc490bd7 --- /dev/null +++ b/docs/getting-started/viewer.md @@ -0,0 +1,15 @@ +# Using the viewer + +!!! warning + + **It is easy to over-interpret georeferenced historical maps**, because they may contain factual mistakes (yes, even the Sanborn Map Company isn't perfect) or they may be distorted or misaligned when compared to aerial imagery. Please keep this in mind when using this site! + +The viewer aggregates all content for a given place, presenting each volume's content in a single mosaicked layer. You can turn on each layer by clicking the year (or circle by the year) and you can fine-tune each layer's opacity with the slider. + +[![Viewer for Alexandria, LA](../images/viewer-alexandria.png)](https://oldinsurancemaps.net/viewer/alexandria-la) + +As you pan the map and adjust layers, your browser URL will be updated to reflect your current view. This means that if you copy the URL at any point, whoever you share it with will see exactly what you are seeing. This allows you to share very specific parts of history, like the [Winter Quarters of M.L. Clark's Circus in 1900](https://oldinsurancemaps.net/viewer/alexandria-la/?sanborn03267_006=0&sanborn03267_005=0&sanborn03267_004=100&sanborn03267_003=0&sanborn03267_002=0&sanborn03267_001=0#/center/-92.45465,31.31151/zoom/20.5). + +Use the "locate me" button ![location button](../images/location-btn.png) to place your current position on the map (best to do this on a mobile device while you are walking though a town in Louisiana!). + +Click the **•••** by any year to see the percentage of its content that has been georeferenced, or head to the more detailed summary of its progress. This percentage is presented here primarily to make clear when a mosaicked layer is incomplete; generally there will be at least a few pieces of a Sanborn map that are too difficult to locate and will likely never be georeferenced. You can still view these piece in the volume summary, however. \ No newline at end of file diff --git a/docs/guides/georeferencing.md b/docs/guides/georeferencing.md new file mode 100644 index 00000000..a041c64c --- /dev/null +++ b/docs/guides/georeferencing.md @@ -0,0 +1,69 @@ +# Georeferencing layers + +## Background + +"Georeferencing" is the process that embeds geospatial metadata into a historical map, allowing it to be integrated into modern web maps or other GIS software. To complete this task you will create ground control points, or "GCPs", that link features on the old map with latitude/longitude coordinates was represented on the web map. + +![The georeferencing interface, with 3 control points added and the preview visible.](../images/alex-georef.gif) + +Creating a ground control point requires two clicks—one in the left panel and one in the right. This records a linkage between a spot on the original map document and the real-world latitude/longitude coordinates for that location. + +![Once 3 control points are present, a semi-transparent preview will appear.](../images/alex-3-georeference.jpg) + +In the example image above, 3 control points have been made using street intersections. You can make as many control points as you want (the more the better!) but often 3-6 are enough. If 3 or more are present, a semi-transparent live preview will be added to the right panel. Use the w key to toggle preview transparency. + +## Using the Interface + +_Before starting, it can be helpful to pan and zoom around to become familiar with the document and the area._ + +Creating a control point: + +- Start a control point by clicking on the map document (left). +- Finish it by clicking on a corresponding location in the web map (right). +- You can pan and zoom in both panels during this process. +- You can add a note to a control point. This is helpful if you are not 100% confident in your placement, or just want to point something out to future users. +- You can modify a control point at any time by clicking and dragging it. + +Deleting a control point: + +- Select an existing control point via the list in the bottom left, or by clicking on it in the panels. +- Click or type d to delete. + +!!! warning + + There is currently an error that causes ground control points to get scrambled when is deleted. + + +Saving Control Points: + +- You can only save the control points once you have 3 or more. +- Click Save Control Points when you are satisfied. This will start the warping process, which may take a few minutes to complete. You will be redirected back to the Document detail page in the meantime. +- Click to reset the interface. This will remove all changes you have made. + +Editing existing control points: + +- If someone else has already georeferenced this document, feel free to modify their control points (or add more), to improve the georeferencing—this is meant to be an iterative process. +- Click to discard your changes and restore the original control points. + +Managing layers: + +- You can change the opacity of the preview layer by typing w. +- You can switch to an aerial imagery basemap with the Basemap dropdown menu. + +Managing the panels: + +- You can increase the size of the left or right panel with the menu in the top left. +- Checking the autosize box will cause the panels sizes to dynamically update based on whether your next click should be in the left or right panel. + +Transformations: + +- It is recommended that you use the default transformation, Polynomial. +- Switching to Thin Plate Spline will allow the image to distort and warp to fit all control points exactly, which _could_ be necessary in rare circumstances. +- You can read more about GDAL transformation algorithms in the QGIS documentation (note: we are only using the Polynomial 1 transformation here). + +## Georeferencing Tips + +- Prioritize finding control points that are widely spread across the map. +- Look for locations that have changed the least over time. For example, the center of street intersections, railroad crossings, or, in some cases, the corners or centers of old buildings. +- Locations to avoid using are the edges of city blocks, sidewalks, or street intersections of which you can only see a portion. +- Historical maps may have mistakes, or street names may have changed over time. diff --git a/docs/guides/preparation.md b/docs/guides/preparation.md new file mode 100644 index 00000000..d9f25a91 --- /dev/null +++ b/docs/guides/preparation.md @@ -0,0 +1,60 @@ +# Preparing documents + +## Background + +Sometimes an old map document will cover discontiguous areas, especially when the mapmakers were trying to +fit a lot of content into a single page. In these cases, each separate area in the original document must be split into +its own new region, so that each area can be georeferenced separately. Typically, you'll find +**strong black lines** delineating different parts of the map. The document must be split along those lines. + +
+
+ ![This map must be split into four new documents.](../images/split-example-p1-anno.jpg) +
This map must be split into four new documents.
+
+
+ ![This map must be split into two new documents.](../images/split-example-p2-anno.jpg) +
This map must be split into two new documents.
+
+
+ ![This map shows only one part of town, so it should not be split.](../images/split-example-p3-anno.jpg) +
This map shows only one part of town, so it should not be split.
+
+
+ +The examples above show two documents that need to be split, and one that contains only one map and does not need to be split. + +## No split needed + +For documents that do not need to be split, you need only click the **no split needed** button, and the document will be prepared. If there are many documents like this within the map you are working on, you can click the **Bulk prepare documents** button, check the box for each document you want to process, and click submit. + +![Three documents to be prepared, showing the buttons for marking "no split" and "split" actions](../images/new-iberia-to-prepare.png) + +## Using the splitting interface + +If a document needs to be in order to be prepared, then click the **split this document** button, and you'll be taken to the splitting interface. + +Here is an example of what it looks like to use the splitting interface to cut a document into three separate regions. *It is kind of a sloppy example, please be a bit more exact that this if you can!* + +![The splitting interface, ready to split this document into three new documents.](../images/alex-split.gif) + +### Defining the split regions + +- Use the interface to create as many cut-lines as are needed to fully split this document. +- Once you have one or more valid cut-lines, a preview will appear showing how the image will be split. +- Click the scissors icon when you are ready. +- You will be redirected to the map overview page, while the split process runs in the background. +- If you split the document incorrectly, you can undo the process from the map summary page. + +### Creating cut-lines + +- In **Draw** mode, click once to start or continue a line, and double-click to finish it. +- Press **Esc** to cancel an in-progress drawing. +- Switch to **Modify** mode to change a cut-line. +- Click the "refresh" button to erase all lines and start over. + +Understanding cut-lines: + +- Once you have a valid cut-line, a preview will appear showing you how the document will be split. +- Only cut-lines that fully cross a segment of the document will be used—all others will safely be ignored. +- Cut-lines can intersect or extend from each other to handle complex shapes. diff --git a/docs/guides/trimming.md b/docs/guides/trimming.md new file mode 100644 index 00000000..8d9e9643 --- /dev/null +++ b/docs/guides/trimming.md @@ -0,0 +1,5 @@ +# Creating a MultiMask + +Overlapping edges of layers cause messy mosaics, so a mask must be added to each layer to remove its margins. These masks should all be contiguous (sharing adjacent borders and vertices) so it is best to handle them at the map-level, not by masking each layer individually. This is the idea behind a **MultiMask**, which is a unified collection of masks for all layers within a map. + +![The multitrim interface.](../images/multitrim.gif) \ No newline at end of file diff --git a/docs/guides/workflow-overview.md b/docs/guides/workflow-overview.md new file mode 100644 index 00000000..d5e0d8a0 --- /dev/null +++ b/docs/guides/workflow-overview.md @@ -0,0 +1,39 @@ +# Understanding the georeferencing workflow + +The georeferencing process generally consists of three operations, each with their own browser interface. + +## The steps at a glance + +### Preparation + +Document preparation (sometimes they must be split into multiple pieces): + +![Splitting interface](../images/example-split-alex-1900.jpg) + +Learn more in [this guide](../guides/preparation.md). + +### Georeferencing + +Ground control point creation (these are used to warp the document into a geotiff): + +![Georeferencing interface](../images/example-georef-alex-1900.jpg) + +Learn more in [this guide](../guides/georeferencing.md). + +### Trimming + +And a "multimask" that allows a volume's sheets to be trimmed *en masse*, a quick way to create a seamless mosaic from overlapping sheets: + +![Trimming interface](../images/example-multimask-alex-1900.jpg) + +Learn more in [this guide](../guides/trimming.md). + +## Full walkthrough + +For a full illustrated demonstration of how these steps fit together across a whole multi-page Sanborn atlas, checkout the [New Iberia, La. 1885 walthrough](../walkthroughs/new-iberia-la-1885.md). + +## Work Sessions + +All user input is tracked through registered accounts, which allows for a comprehensive understanding of user engagement and participation, as well as a complete database of all input georeferencing information, like ground control points, masks, etc. + +You can always see the most recent sessions on the [activity page](https://oldinsurancemaps.net/activity). diff --git a/docs/icons/colored-full-linework.png b/docs/icons/colored-full-linework.png new file mode 100644 index 00000000..3259f1f9 Binary files /dev/null and b/docs/icons/colored-full-linework.png differ diff --git a/docs/icons/favicon.ico b/docs/icons/favicon.ico new file mode 100644 index 00000000..f3918b8a Binary files /dev/null and b/docs/icons/favicon.ico differ diff --git a/docs/icons/noun_Map_2592596-edit.svg b/docs/icons/noun_Map_2592596-edit.svg new file mode 100755 index 00000000..ff3a891d --- /dev/null +++ b/docs/icons/noun_Map_2592596-edit.svg @@ -0,0 +1,161 @@ + +Map-01-01Map-01-01 diff --git a/docs/images/alex-1900-1-2-prepared.png b/docs/images/alex-1900-1-2-prepared.png new file mode 100644 index 00000000..c680ecb3 Binary files /dev/null and b/docs/images/alex-1900-1-2-prepared.png differ diff --git a/docs/images/alex-1900-before-load.png b/docs/images/alex-1900-before-load.png new file mode 100644 index 00000000..988c0254 Binary files /dev/null and b/docs/images/alex-1900-before-load.png differ diff --git a/docs/images/alex-1900-full-loaded.png b/docs/images/alex-1900-full-loaded.png new file mode 100644 index 00000000..f9efa840 Binary files /dev/null and b/docs/images/alex-1900-full-loaded.png differ diff --git a/docs/images/alex-1900-sheet-1-doc-detail-after-georeference.png b/docs/images/alex-1900-sheet-1-doc-detail-after-georeference.png new file mode 100644 index 00000000..2fac4c4b Binary files /dev/null and b/docs/images/alex-1900-sheet-1-doc-detail-after-georeference.png differ diff --git a/docs/images/alex-1900-sheet-1-doc-detail-after-split.png b/docs/images/alex-1900-sheet-1-doc-detail-after-split.png new file mode 100644 index 00000000..b3936b78 Binary files /dev/null and b/docs/images/alex-1900-sheet-1-doc-detail-after-split.png differ diff --git a/docs/images/alex-1900-sheet-1-doc-detail-during-georeference.png b/docs/images/alex-1900-sheet-1-doc-detail-during-georeference.png new file mode 100644 index 00000000..fef790d3 Binary files /dev/null and b/docs/images/alex-1900-sheet-1-doc-detail-during-georeference.png differ diff --git a/docs/images/alex-1900-sheet-1-doc-detail-during-split.png b/docs/images/alex-1900-sheet-1-doc-detail-during-split.png new file mode 100644 index 00000000..ed454bd6 Binary files /dev/null and b/docs/images/alex-1900-sheet-1-doc-detail-during-split.png differ diff --git a/docs/images/alex-1900-sheet-1-prepare-cutlines.png b/docs/images/alex-1900-sheet-1-prepare-cutlines.png new file mode 100644 index 00000000..de18d6dd Binary files /dev/null and b/docs/images/alex-1900-sheet-1-prepare-cutlines.png differ diff --git a/docs/images/alex-1900-sheet-1-prepare.png b/docs/images/alex-1900-sheet-1-prepare.png new file mode 100644 index 00000000..92247b12 Binary files /dev/null and b/docs/images/alex-1900-sheet-1-prepare.png differ diff --git a/docs/images/alex-1900-sheet-2-georeference-4-gcps.png b/docs/images/alex-1900-sheet-2-georeference-4-gcps.png new file mode 100644 index 00000000..9cb1242d Binary files /dev/null and b/docs/images/alex-1900-sheet-2-georeference-4-gcps.png differ diff --git a/docs/images/alex-1900-sheet-2-georeference-gcp-detail.png b/docs/images/alex-1900-sheet-2-georeference-gcp-detail.png new file mode 100644 index 00000000..8f02b0ed Binary files /dev/null and b/docs/images/alex-1900-sheet-2-georeference-gcp-detail.png differ diff --git a/docs/images/alex-1900-sheet-2-georeference.png b/docs/images/alex-1900-sheet-2-georeference.png new file mode 100644 index 00000000..b4e92af7 Binary files /dev/null and b/docs/images/alex-1900-sheet-2-georeference.png differ diff --git a/docs/images/alex-1900-sheet-2-prepare.png b/docs/images/alex-1900-sheet-2-prepare.png new file mode 100644 index 00000000..3f962d21 Binary files /dev/null and b/docs/images/alex-1900-sheet-2-prepare.png differ diff --git a/docs/images/alex-1900-two-loaded.png b/docs/images/alex-1900-two-loaded.png new file mode 100644 index 00000000..63c47ff3 Binary files /dev/null and b/docs/images/alex-1900-two-loaded.png differ diff --git a/docs/images/alex-3-georeference.jpg b/docs/images/alex-3-georeference.jpg new file mode 100644 index 00000000..ff90463f Binary files /dev/null and b/docs/images/alex-3-georeference.jpg differ diff --git a/docs/images/alex-georef.gif b/docs/images/alex-georef.gif new file mode 100644 index 00000000..a06a6053 Binary files /dev/null and b/docs/images/alex-georef.gif differ diff --git a/docs/images/alex-search-volumes.png b/docs/images/alex-search-volumes.png new file mode 100644 index 00000000..442725b6 Binary files /dev/null and b/docs/images/alex-search-volumes.png differ diff --git a/docs/images/alex-split.gif b/docs/images/alex-split.gif new file mode 100644 index 00000000..364f39ac Binary files /dev/null and b/docs/images/alex-split.gif differ diff --git a/docs/images/browse-by-map.png b/docs/images/browse-by-map.png new file mode 100644 index 00000000..42cefbce Binary files /dev/null and b/docs/images/browse-by-map.png differ diff --git a/docs/images/browse-by-place.png b/docs/images/browse-by-place.png new file mode 100644 index 00000000..e8c49239 Binary files /dev/null and b/docs/images/browse-by-place.png differ diff --git a/docs/images/browse-by-volume.png b/docs/images/browse-by-volume.png new file mode 100644 index 00000000..ea3c0427 Binary files /dev/null and b/docs/images/browse-by-volume.png differ diff --git a/docs/images/browse.jpg b/docs/images/browse.jpg new file mode 100644 index 00000000..af927424 Binary files /dev/null and b/docs/images/browse.jpg differ diff --git a/docs/images/colored-full-linework.png b/docs/images/colored-full-linework.png new file mode 100644 index 00000000..3259f1f9 Binary files /dev/null and b/docs/images/colored-full-linework.png differ diff --git a/docs/images/example-georef-alex-1900.jpg b/docs/images/example-georef-alex-1900.jpg new file mode 100644 index 00000000..c32bb4e6 Binary files /dev/null and b/docs/images/example-georef-alex-1900.jpg differ diff --git a/docs/images/example-multimask-alex-1900.jpg b/docs/images/example-multimask-alex-1900.jpg new file mode 100644 index 00000000..5b89fa8c Binary files /dev/null and b/docs/images/example-multimask-alex-1900.jpg differ diff --git a/docs/images/example-resource-alex-1900.jpg b/docs/images/example-resource-alex-1900.jpg new file mode 100644 index 00000000..86e2d68c Binary files /dev/null and b/docs/images/example-resource-alex-1900.jpg differ diff --git a/docs/images/example-split-alex-1900.jpg b/docs/images/example-split-alex-1900.jpg new file mode 100644 index 00000000..d22e5f0d Binary files /dev/null and b/docs/images/example-split-alex-1900.jpg differ diff --git a/docs/images/georeference-data-model-sans-links.png b/docs/images/georeference-data-model-sans-links.png new file mode 100644 index 00000000..e15225c8 Binary files /dev/null and b/docs/images/georeference-data-model-sans-links.png differ diff --git a/docs/images/georeference-interface.png b/docs/images/georeference-interface.png new file mode 100644 index 00000000..49084ccb Binary files /dev/null and b/docs/images/georeference-interface.png differ diff --git a/docs/images/georeference-tab.png b/docs/images/georeference-tab.png new file mode 100644 index 00000000..68670f5b Binary files /dev/null and b/docs/images/georeference-tab.png differ diff --git a/docs/images/lineage.png b/docs/images/lineage.png new file mode 100644 index 00000000..0d21ff64 Binary files /dev/null and b/docs/images/lineage.png differ diff --git a/docs/images/location-btn.png b/docs/images/location-btn.png new file mode 100644 index 00000000..bf57c651 Binary files /dev/null and b/docs/images/location-btn.png differ diff --git a/docs/images/multitrim.gif b/docs/images/multitrim.gif new file mode 100644 index 00000000..ce5e977d Binary files /dev/null and b/docs/images/multitrim.gif differ diff --git a/docs/images/new-iberia-to-prepare.png b/docs/images/new-iberia-to-prepare.png new file mode 100644 index 00000000..7e1a8325 Binary files /dev/null and b/docs/images/new-iberia-to-prepare.png differ diff --git a/docs/images/new_iberia_la_1885_p1-1000w.jpg b/docs/images/new_iberia_la_1885_p1-1000w.jpg new file mode 100644 index 00000000..787118e0 Binary files /dev/null and b/docs/images/new_iberia_la_1885_p1-1000w.jpg differ diff --git a/docs/images/new_iberia_la_1885_p2-1000w.jpg b/docs/images/new_iberia_la_1885_p2-1000w.jpg new file mode 100644 index 00000000..f5181295 Binary files /dev/null and b/docs/images/new_iberia_la_1885_p2-1000w.jpg differ diff --git a/docs/images/new_iberia_la_1885_p3-1000w.jpg b/docs/images/new_iberia_la_1885_p3-1000w.jpg new file mode 100644 index 00000000..a7add09d Binary files /dev/null and b/docs/images/new_iberia_la_1885_p3-1000w.jpg differ diff --git a/docs/images/search-item.png b/docs/images/search-item.png new file mode 100644 index 00000000..079d8254 Binary files /dev/null and b/docs/images/search-item.png differ diff --git a/docs/images/split-example-p1-anno.jpg b/docs/images/split-example-p1-anno.jpg new file mode 100644 index 00000000..765172b8 Binary files /dev/null and b/docs/images/split-example-p1-anno.jpg differ diff --git a/docs/images/split-example-p2-anno.jpg b/docs/images/split-example-p2-anno.jpg new file mode 100644 index 00000000..40a6da00 Binary files /dev/null and b/docs/images/split-example-p2-anno.jpg differ diff --git a/docs/images/split-example-p3-anno.jpg b/docs/images/split-example-p3-anno.jpg new file mode 100644 index 00000000..a0000f98 Binary files /dev/null and b/docs/images/split-example-p3-anno.jpg differ diff --git a/docs/images/split-interface.png b/docs/images/split-interface.png new file mode 100644 index 00000000..a0e7c3e6 Binary files /dev/null and b/docs/images/split-interface.png differ diff --git a/docs/images/tutorial-new-iberia-all-prepared.png b/docs/images/tutorial-new-iberia-all-prepared.png new file mode 100644 index 00000000..dd570986 Binary files /dev/null and b/docs/images/tutorial-new-iberia-all-prepared.png differ diff --git a/docs/images/tutorial-new-iberia-classify.png b/docs/images/tutorial-new-iberia-classify.png new file mode 100644 index 00000000..456a114b Binary files /dev/null and b/docs/images/tutorial-new-iberia-classify.png differ diff --git a/docs/images/tutorial-new-iberia-empty-summary.png b/docs/images/tutorial-new-iberia-empty-summary.png new file mode 100644 index 00000000..16dc43df Binary files /dev/null and b/docs/images/tutorial-new-iberia-empty-summary.png differ diff --git a/docs/images/tutorial-new-iberia-georef-key-map.png b/docs/images/tutorial-new-iberia-georef-key-map.png new file mode 100644 index 00000000..9a60092c Binary files /dev/null and b/docs/images/tutorial-new-iberia-georef-key-map.png differ diff --git a/docs/images/tutorial-new-iberia-georef-page-2.png b/docs/images/tutorial-new-iberia-georef-page-2.png new file mode 100644 index 00000000..518827c7 Binary files /dev/null and b/docs/images/tutorial-new-iberia-georef-page-2.png differ diff --git a/docs/images/tutorial-new-iberia-load-docs.png b/docs/images/tutorial-new-iberia-load-docs.png new file mode 100644 index 00000000..6e274119 Binary files /dev/null and b/docs/images/tutorial-new-iberia-load-docs.png differ diff --git a/docs/images/tutorial-new-iberia-loc-gallery.png b/docs/images/tutorial-new-iberia-loc-gallery.png new file mode 100644 index 00000000..6df50ad7 Binary files /dev/null and b/docs/images/tutorial-new-iberia-loc-gallery.png differ diff --git a/docs/images/tutorial-new-iberia-locale.png b/docs/images/tutorial-new-iberia-locale.png new file mode 100644 index 00000000..da4f58d5 Binary files /dev/null and b/docs/images/tutorial-new-iberia-locale.png differ diff --git a/docs/images/tutorial-new-iberia-one-georeferenced.png b/docs/images/tutorial-new-iberia-one-georeferenced.png new file mode 100644 index 00000000..09e39fd6 Binary files /dev/null and b/docs/images/tutorial-new-iberia-one-georeferenced.png differ diff --git a/docs/images/tutorial-new-iberia-one-loaded.png b/docs/images/tutorial-new-iberia-one-loaded.png new file mode 100644 index 00000000..ce0ea6cc Binary files /dev/null and b/docs/images/tutorial-new-iberia-one-loaded.png differ diff --git a/docs/images/tutorial-new-iberia-one-split.png b/docs/images/tutorial-new-iberia-one-split.png new file mode 100644 index 00000000..83d03faa Binary files /dev/null and b/docs/images/tutorial-new-iberia-one-split.png differ diff --git a/docs/images/tutorial-new-iberia-prep-page-1.png b/docs/images/tutorial-new-iberia-prep-page-1.png new file mode 100644 index 00000000..3fa49a32 Binary files /dev/null and b/docs/images/tutorial-new-iberia-prep-page-1.png differ diff --git a/docs/images/tutorial-new-iberia-splitting.png b/docs/images/tutorial-new-iberia-splitting.png new file mode 100644 index 00000000..107f628b Binary files /dev/null and b/docs/images/tutorial-new-iberia-splitting.png differ diff --git a/docs/images/viewer-alexandria.png b/docs/images/viewer-alexandria.png new file mode 100644 index 00000000..1da303ac Binary files /dev/null and b/docs/images/viewer-alexandria.png differ diff --git a/docs/images/vsummary-031922.jpg b/docs/images/vsummary-031922.jpg new file mode 100644 index 00000000..b549dbfb Binary files /dev/null and b/docs/images/vsummary-031922.jpg differ diff --git a/docs/images/vsummary2-031922.jpg b/docs/images/vsummary2-031922.jpg new file mode 100644 index 00000000..232d235e Binary files /dev/null and b/docs/images/vsummary2-031922.jpg differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..cf680eef --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +# Welcome! + +This documentation site will help you understand [OldInsuranceMaps.net](https://oldinsurancemaps.net), crowdsourcing platform for creating and viewing georeferenced mosaics of historical fire insurance maps, primarily from the Library of Congress [Sanborn Maps collection](https://loc.gov/collections/sanborn-maps). + +## Quick links + +- [OldInsuranceMaps.net](https://oldinsurancemaps.net) - The main platform and georeferencing application. +- [Online Historical Map Georeferencer (OHMG)](https://ohmg.dev) - Information about the concepts and open source software behind this project, including architecture and installation docs. +- [OpenHistoricalMap Forum → OldInsuranceMaps.net](https://forum.openhistoricalmap.org/c/oldinsurancemaps/13) - Drop by to introduce yourself, and feel free to ask questions about the project and how people are using it. + +## Site Overview + +You can browse content in the platform by map, by place name, or by map name. To learn more about these search methods, see [Finding maps](./guides/finding-maps.md). + +![Homepage](images/browse.jpg) + +Each volume's summary page has an interactive Map Overview showing all of the sheets that have been georeferenced so far. + +![Volume Summary - Map Overview](images/vsummary-031922.jpg) + +Each volume's summary page also lists the progress and georeferencing stage of each sheet. + +![Volume Summary - Georeferencing Overview](images/vsummary2-031922.jpg) + +Finally, each resource itself has its own page, showing a complete lineage of the work that has been performed on it by various users. + +![Alexandria, La, 1900, p1 [2]](images/example-resource-alex-1900.jpg) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..380c1173 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,5 @@ +[data-md-color-scheme="default"] { + --md-primary-fg-color: #123b4f; + --md-primary-fg-color--light: #eae0c1; + --md-primary-fg-color--dark: #123b4f; +} \ No newline at end of file diff --git a/docs/walkthroughs/alexandria-la-1900.md b/docs/walkthroughs/alexandria-la-1900.md new file mode 100644 index 00000000..05fb7ccb --- /dev/null +++ b/docs/walkthroughs/alexandria-la-1900.md @@ -0,0 +1,118 @@ +--- +sidebar_position: 4 +--- + +# Alexandria, La., 1900 (old tutorial for multi-page Sanborn map) + +!!! Warning + + Some changes have been made throughout the site since this tutorial was first created. Some of the screenshots and navigation paths are out-of-date, and the "Load the Volume" step is no longer supported. Otherwise, the gist of the workflow is the same. + +This tutorial covers the entire process using the [Alexandria, La. | 1900](https://www.loc.gov/resource/g4014am.g032671900/?st=gallery) volume as an example. + +The complete workflow is: + +1. [Load the Volume](#load-the-volume) +2. [Prepare the Documents](#prepare-the-documents) +3. [Georeference the prepared Documents](#georeference-the-prepared-documents) + +Keep in mind that these steps are designed to facilitate a collaborative environment. While you *could* complete an entire volume in one session, you can also just do individual steps here and there, allowing others to fill in around. Georeferencing (3 above) is an iterative process, so you can come back later to improve upon your own work, or someone else's. + +The end result is a web map which can be viewed in the site or embedded with an `