The Necessary Reunions project reunites historical maps and textual sources from the Dutch East India Company (VOC) archives to reconceptualise Kerala's early modern topography. This documentation provides comprehensive guidance on using the three main tools developed for this project.

The Three Tools

Key Features

• Web-based and free to use for researchers worldwide
• IIIF manifest support for standardised image delivery
• SVG annotation capabilities for precise map markup
• Integration between annotations and historical place names
• Public API for external linking and data integration
• Open source codebase hosted on GitHub

Why This Project?

Historical maps and documents from the VOC tell richer stories when brought back together. The project reunites cartographic and textual sources that were separated by time and archival practice, enabling new insights into early modern Kerala's geography, economy, and society. By making these connections visible and searchable, researchers can trace how places were understood, named, and represented across different sources and time periods.

All three tools are accessible directly through your web browser at necessaryreunions.org. No installation or account creation is required for viewing and exploring the data.

Quick Start Guide

Accessing the Data

All data created in the scope of this project will eventually be part of the larger GLOBALISE project. The code is freely available on GitHub, and the data can be accessed via public APIs.

re:Charted is an IIIF (International Image Interoperability Framework) viewer and editor specifically designed for viewing and annotating historical Kerala maps from the VOC archives. The tool provides comprehensive functionality for browsing maps, viewing AI-generated annotations, and creating new annotations with linking to external gazetteers.

1. Info Tab: IIIF Viewer Basics

The Info tab provides the foundation for navigating historical maps using the IIIF standard. This interface is designed for researchers who need to examine high-resolution digitised maps in detail.

2. Manifest: Metadata and Map Information

Each map in re:Charted is served through an IIIF manifest containing essential metadata. The manifest panel displays comprehensive information about the historical map you are viewing.

• Title: Full title of the historical map as recorded in archival sources
• Dimensions: Physical size and digital resolution of the map
• Source: Archival institution and collection reference (e.g., Leupe collection, National Archives)
• Date: Creation date or estimated date range of the map
• Attribution: Cartographer, draughtsman, or surveyor information when available
• Rights: Usage rights and copyright information

This metadata is crucial for proper citation and understanding the historical context of each map. The manifest follows IIIF Presentation API 3.0 standards, ensuring interoperability with other IIIF-compatible tools and viewers.

3. Map Tab: Georeferencing and Modern Overlay

The Map tab provides georeferenced overlays that align historical maps with modern geographic coordinates. This powerful feature uses Allmaps and Leaflet to enable spatial comparison between historical and contemporary cartography.

Georeferencing Features

• Allmaps Integration: Uses Allmaps georeferencing engine to transform historical map coordinates to modern geographic positions
• Leaflet Base Map: Displays modern OpenStreetMap tiles as reference layer
• Adjustable Opacity: Slider control to blend historical and modern maps for visual comparison
• Control Points: View georeferencing control points that anchor the historical map to modern coordinates
• Transformation Accuracy: Visual indicators showing alignment quality and distortion

4. Annotation Tab: Viewing Mode

For users who are not signed in, the Annotation tab operates in viewing mode, providing read-only access to all annotations on the map. This mode is ideal for researchers who want to explore existing annotations without editing capabilities.

Display and Filtering

The annotation list shows all annotations for the currently displayed map canvas, organised with multiple filtering options:

• AI vs Human Verified: Toggle to filter between AI-generated annotations (from MapReader and Loghi) and human-verified annotations that have been reviewed and confirmed
• Annotation Type: Filter by type (Text Spotting, Iconography, Georeferencing, Linking)
• Source: Filter by origin (Loghi AI, Other AI, Human)
• Assessment Status: View which annotations have been checked and validated

Text Search Function

Search across all annotation text content to quickly locate specific place names, features, or terms on the map. The search function operates across all annotation types and highlights matching results in the list.

Visual Indicators

Each annotation in the list displays icons providing quick information about its properties:

• Link Icon: Indicates the annotation is part of a linking annotation connecting to geographic location
• Comment Icon: Shows annotation has associated comments or notes
• Classification Icon: Displays assigned iconography classification (fort, settlement, ship, etc.)
• Checkmark Badge: Indicates human verification and assessment status

5. Annotation Tab: Editing Mode

For authenticated users with editing permissions, the Annotation tab transforms into a comprehensive annotation workbench. This mode provides complete control over the annotation process, allowing researchers to refine AI-generated annotations, create new annotations, and establish geographic connections.

5a. Deletion: Managing Annotations

Remove incorrect or duplicate annotations to maintain data quality. The deletion function supports both individual and bulk operations for efficient curation.

• Single Deletion: Select and delete individual annotations that are incorrect or unnecessary
• Bulk Deletion: Select multiple annotations using checkboxes and delete them in a single operation
• Confirmation Dialog: Safety prompt prevents accidental deletion of annotations
• Undo Support: Recent deletions can be reversed if removed in error

Deletion is particularly useful for removing AI-generated annotations that incorrectly identified map decorations, cartouches, or other non-geographic features as text or icons.

5b. Correction: Refining Text and Geometry

Correct and refine existing annotations by editing text content and adjusting SVG polygon boundaries. This step improves the accuracy of AI-generated annotations.

• Text Field Editing: Click to edit annotation text, correcting OCR errors or incomplete transcriptions
• SVG Polygon Adjustment: Drag polygon vertices to precisely match the boundaries of text or iconography on the map
• Add/Remove Points: Add new vertices to complex shapes or remove unnecessary points for cleaner geometry
• Live Preview: See changes reflected immediately on the map as you edit

5c. Add New: Creating Text and Iconography Annotations

Create new annotations for map features that were not detected by AI systems. This includes both text spotting (place names, labels) and iconography (symbols, icons) annotations.

• Text Spotting: Draw a polygon around text on the map and transcribe the content
• Iconography: Draw a polygon around map symbols, icons, or pictorial elements
• Drawing Tools: Click to create polygon vertices, double-click to complete shape
• Metadata Entry: Add annotation body content (text transcription or description)

When drawing new polygons, follow the same coverage guidelines as for corrections: ensure all characters or icon elements are fully enclosed without cropping. Zoom in to verify that polygon boundaries are close to the edges but do not pass through the text or symbols.

Adding new annotations is essential for capturing map features that AI systems miss, such as faded text, unusual iconography, or symbols in non-standard positions. This human curation ensures comprehensive coverage of all map content.

5d. Assign Classification: Categorising Iconography

Assign semantic classifications to iconography annotations using a controlled thesaurus of map symbol types. This structured classification enables systematic analysis of map content across the collection.

• Thesaurus Selection: Choose from predefined categories (fort, settlement, ship, church, etc.)
• Hierarchical Structure: Classifications organised by type and subtype
• Multiple Classifications: Assign multiple categories when a symbol has compound meaning
• Visual Consistency: Colour-coded badges show classification in annotation list

5e. Comment and Mark: Assessment and Notes

Add comments to annotations and mark them as assessed to track verification progress. This workflow feature supports collaborative annotation projects where multiple researchers review and validate map content.

• Comment Field: Add notes about annotation quality, uncertainty, or interpretation
• Assessment Checkbox: Mark annotations as "checked" after human verification
• Annotation History: Track who made comments and when assessments occurred
• Quality Control: Filter views to show only assessed or unassessed annotations

The assessment system is crucial for distinguishing between raw AI output and human-verified data. Researchers can focus their work on unassessed annotations or prioritise reviewing AI-generated content flagged with low confidence scores.

5f. Link: Creating Geographic Connections

The linking function is the most sophisticated editing feature, creating linking annotations that connect selected text spotting and iconography annotations in a reading order, associate them with external gazetteer entries, and establish geographic positioning on the map.

Linking Annotation Components

• Reading Order: Select multiple text spotting and iconography annotations and arrange them in reading order (e.g., place name text + settlement icon). Numbered badges appear on selected annotations showing their sequence.
• Geotag from Thesaurus: Search and select a matching place from one of three external thesauri:
  • GAVOC: Historical place names database specific to Kerala region
  • GLOBALISE Places: Broader VOC-era place name dataset
  • Nominatim/OpenStreetMap: Modern place names and coordinates
• Point Placement: Click on the map image to add an x/y coordinate point showing the geographic centre of the place. This point serves multiple purposes:
  • Visual marker of the place location on the map
  • Data for improving georeferencing accuracy in future iterations
  • Reference point for spatial analysis of place distribution

Interface Elements

• Left Panel: Map collection browser with thumbnails and search
• Centre Viewport: Main map viewing area with annotation overlays
• Right Panel: Tabbed interface (Info, Manifest, Map, Annotations)
• Top Navigation: Project links and user authentication

GAVOC (Grote Atlas van de Verenigde Oost-Indische Compagnie) is a comprehensive database of historical place names from early modern Kerala, containing over 11,000 standardised entries linking historical and modern toponyms with geographic coordinates and semantic categories.

The GAVOC database is based on the comprehensive index in: Schilder, Gunter, Jacques Moerman, Ferjan Ormeling, Paul van den Brink and Hans Ferwerda. Grote atlas van de Verenigde Oost-Indische Compagnie. Volume I: Atlas Isaak de Graaf. Voorburg: Asia Maior, 2006. ISBN 9789074861137. [National Archives, The Hague: 2.14.97, inv.nr. 11.1]

Database Structure

Interface Overview

GAVOC provides two complementary views for exploring the database: a map-based geographical browser and a table-based detailed view. Both interfaces support full-text search and category filtering.

Step-by-Step Workflows

Map View Features

Integration with Other Tools

GAVOC serves as the reference dataset for the entire Necessary Reunions project, providing authoritative place name data for:

• re:Charted Linking Annotations: When creating geotagging annotations in the map viewer, GAVOC provides the target locations with persistent identifiers.
• Gazetteer Search: The Gazetteer tool queries GAVOC data to show which historical maps contain specific places.
• External Research Projects: The public API enables integration with digital editions, databases, and web applications beyond this project.

The Gazetteer provides a streamlined search interface for exploring places located on the 30 maps available in re:Charted. It collects linked and geotagged places from map annotations, building comprehensive place biographies that show the history and transitions of locations in Kerala across different sources and time periods.

Core Concept

The Gazetteer aggregates all geotagged annotations from the 30 historical maps in re:Charted, creating a searchable database of places that appear across the collection. Unlike GAVOC, which provides comprehensive historical place name data for the entire Kerala region, the Gazetteer focuses specifically on places that have been annotated and linked on the maps in this project.

Browsing and Search

List View

The default list view displays all places in the Gazetteer as a searchable table. Each entry shows:

• Place Name: The standardised modern name of the location
• Historical Variants: Alternative names found on the historical maps
• Map Count: Number of maps in the collection where this place appears
• Classification: Category or type of place (settlement, fort, port, etc.)

Map View

Switch to map view to see all Gazetteer places plotted on a modern base map. This geographic visualisation helps you:

• Understand the spatial distribution of annotated places
• Identify clusters of frequently mapped locations along the coast or inland
• Explore geographic relationships between places in the collection
• Click on map markers to view place details and linked maps

Search Functionality

The Gazetteer supports flexible search across both modern and historical place names:

Detailed Place Pages

Click on any place in the Gazetteer to view its detailed page, which aggregates information from all maps where the place appears.

Place Overview

The top section of each place page provides essential information:

• Primary Name: The standardised modern name used as the main identifier
• Geographic Coordinates: Latitude and longitude of the location
• Modern Map: Interactive map showing the present-day location
• Quick Stats: Number of maps featuring this place and total annotations

Name Variants and Classifications

The Gazetteer displays all name variations found across the map annotations, showing:

• Historical Spellings: Different orthographic variants used in VOC-era maps
• Language Variations: Names in Dutch, Portuguese, and local languages
• Classifications: Categories assigned to the place (settlement, fort, port, river, etc.)
• Source Attribution: Which maps contain each name variant

Links to Maps and Annotations

Each place page shows all maps where the location appears, providing direct navigation to view the place in its historical cartographic context:

• Map Thumbnails: Visual previews of each map featuring the place
• Map Metadata: Title, date, and source information for each map
• Direct Links: Click to open the map in re:Charted with the place annotation highlighted
• Annotation Details: View the specific iconography or text annotations linked to this place

Frequency and Context

The Gazetteer analyses how often and in what contexts each place appears across the map collection:

• Temporal Distribution: Timeline showing when the place appears on maps across different decades
• Map Coverage: Percentage of the collection that includes this place
• Annotation Types: Breakdown of how the place is represented (iconography, text labels, fortification symbols)
• Cartographic Prominence: Analysis of how prominently the place is featured on different maps

Building Place Biographies

By aggregating information across multiple maps and time periods, the Gazetteer constructs a "biography" for each place showing:

• Name Evolution: How the place name changed or was standardised over time
• Functional Changes: Shifts in classification (e.g., from settlement to fortified port)
• Cartographic Attention: Periods when the place received more or less detailed representation
• Geographic Context: How the place's relationship to nearby features was depicted across different maps

Integration with Other Tools

The Gazetteer acts as a bridge between GAVOC's comprehensive historical database and re:Charted's visual map interface:

• GAVOC Connection: Places in the Gazetteer link to their GAVOC entries for additional historical and geographic context
• re:Charted Integration: Click through from Gazetteer to view any place on its original historical map with full annotation context
• Cross-Reference: Use the Gazetteer to discover which GAVOC places appear on which maps, and which maps contain annotations for specific locations

The Necessary Reunions project provides public APIs for accessing place name data and integrating with external research projects and datasets.

GAVOC API

The GAVOC API provides programmatic access to the historical place name database, allowing you to query locations and retrieve their historical and modern names, coordinates, and categories.

Query Parameters

Example Request

GET https://necessaryreunions.org/api/gavoc?search=Cochin&category=settlement&limit=10

Example Response

{
  "places": [
    {
      "id": 7954,
      "originalName": "Cochin",
      "presentName": "Kochi",
      "category": "stad, settlement",
      "coordinates": "9.9667° N, 76.2833° E",
      "mapGridSquare": "B3",
      "mapReference": "II-28",
      "pageReference": "p. 338"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Gazetteer API

Access places from the Gazetteer database, which contains all locations annotated on the 30 maps in re:Charted.

IIIF Manifests

All maps are served using the IIIF (International Image Interoperability Framework) protocol, allowing integration with any IIIF-compatible viewer or application.

The Necessary Reunions codebase is open source and available on GitHub. This section provides technical details for developers who want to run the project locally, contribute, or adapt it for their own research.

Technology Stack

• Framework: Next.js 14 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• Map Viewer: OpenSeadragon (IIIF)
• Modern Maps: Leaflet with OpenStreetMap
• Annotations: W3C Web Annotations (AnnoRepo)
• Package Manager: pnpm
• Deployment: Netlify

Local Development Setup

Prerequisites

• Node.js 22 or higher
• pnpm package manager
• Git

Installation Steps

git clone https://github.com/globalise-huygens/necessary-reunions.git
cd necessary-reunions

pnpm install

cp .env.example .env.local
# Edit .env.local with your configuration

pnpm dev

The application will be available at http://localhost:3001

Environment Variables

Project Structure

necessary-reunions/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── viewer/            # re:Charted viewer pages
│   ├── gavoc/             # GAVOC tool pages
│   └── gazetteer/         # Gazetteer pages
├── components/            # React components
│   ├── viewer/           # re:Charted components
│   ├── gavoc/            # GAVOC components
│   ├── gazetteer/        # Gazetteer components
│   └── shared/           # Shared UI components
├── hooks/                 # Custom React hooks
├── lib/                   # Utility functions and types
│   ├── viewer/           # IIIF and annotation utilities
│   ├── gavoc/            # GAVOC data processing
│   └── gazetteer/        # Gazetteer utilities
├── data/                  # Static data and scripts
│   ├── scripts/          # Python processing scripts
│   └── manifest.json     # IIIF collection manifest
└── public/               # Static assets

Key Architectural Patterns

IIIF-First Design

The application is built around the International Image Interoperability Framework (IIIF) for handling historical maps and manuscripts. All images are served via IIIF Image API, and metadata follows the IIIF Presentation API specification.

Multi-Layer Annotation System

Four distinct annotation types with different data sources:

• Local: User-created annotations with full CRUD operations
• External: AI-generated annotations from AnnoRepo service
• Linking: Relationship annotations between targets
• Georeferencing: Generated during manifest creation for map overlay

Service Resilience Patterns

Critical anti-pattern prevention for external service failures. All external API calls use timeout controllers with graceful fallbacks to prevent UI crashes.

Python Scripts for Data Processing

The data/scripts/ directory contains Python pipelines for:

• make_manifest.py: Generate IIIF manifests from CSV data
• download_images.py: Batch download using dezoomify-rs tool
• textspotting/spot_text.py: AI text recognition pipeline
• segmentation/segment_icons.py: Icon detection with SAM model

Adapting for Your Own Project

To adapt this codebase for your own historical map project:

1. Prepare your images: Convert your historical maps to IIIF-compatible format
2. Create manifests: Use the make_manifest.py script as a template
3. Set up AnnoRepo: Configure your own AnnoRepo container for annotations
4. Customise the UI: Update branding, colours, and text in the components
5. Deploy: Use Netlify, Vercel, or your preferred hosting platform

Contributions to the Necessary Reunions project are welcome. Whether you're fixing bugs, improving documentation, or proposing new features, your input helps advance digital humanities research.

Opening Issues

If you encounter bugs or have feature requests, open an issue on GitHub. Include:

• Clear description of the problem or suggestion
• Steps to reproduce (for bugs)
• Expected vs actual behaviour
• Screenshots if applicable
• Browser and device information

Pull Requests

To contribute code changes, fork the repository, create a branch, make your changes, and submit a pull request. The project uses automated linting and formatting (ESLint and Prettier).

Contact the Team

For questions about the project or collaboration opportunities, contact:

• Dr Manjusha Kuruppath - Project Lead (Huygens Institute)
• Leon van Wissen - Technical Lead (University of Amsterdam)
• Jona Schlegel - Developer (Huygens Institute / archaeoINK)