How to Register New Processing Algorithms in the GeoLibre Catalog

To register a new processing algorithm in GeoLibre, implement the ProcessingAlgorithm interface defined in packages/processing/src/types.ts, export your algorithm constant, and append it to the appropriate registry array (such as VECTOR_TOOLS or ALGORITHMS) so it appears automatically in the Processing menu.

The opengeos/GeoLibre repository provides a modular processing framework through the @geolibre/processing package. New algorithms become discoverable by the desktop application as soon as they are added to the correct registry arrays and the project is rebuilt. This guide explains the exact file paths and registration patterns used in the source code.

Understanding the ProcessingAlgorithm Interface

Every algorithm must conform to the ProcessingAlgorithm interface exported from packages/processing/src/types.ts. This contract defines the metadata and execution logic required by the processing engine.

Key interface properties include:

• id: A unique string identifier for the algorithm.
• name: The display name shown in the UI.
• description: A brief explanation of the algorithm's purpose.
• parameters: An array defining the inputs (type, defaults, and validation) exposed to users.
• run: An async function receiving ProcessingContext and parameters, returning the result.

Optional UI hints can also be provided to customize how the dialog renders specific inputs.

Step-by-Step Registration Process

Define the Algorithm Implementation

Create your algorithm in the relevant tool file (e.g., packages/processing/src/vector-tools.ts for vector operations). Implement the run method to handle the actual processing logic, typically delegating to DuckDB-WASM or other geometry engines available in the ProcessingContext.

Export the Algorithm Constant

Export the algorithm as a named constant so the registry can import it. The export must be typed as ProcessingAlgorithm to ensure TypeScript validates the structure at compile time.

Register in the Appropriate Catalog Array

Append your exported constant to the relevant registry array based on the algorithm's category:

• Vector tools: Add to VECTOR_TOOLS in packages/processing/src/vector-tools.ts.
• Network analysis: Add to NETWORK_TOOLS in packages/processing/src/network-tools.ts.
• H3 grid operations: Add to H3_TOOLS in packages/processing/src/h3-tools.ts.
• General purpose: Add to the top-level ALGORITHMS array in packages/processing/src/registry.ts.

Rebuild and Verify

Run npm run build or npm run dev to compile the TypeScript. The ProcessingMenu.tsx component automatically reads from these arrays, so your algorithm will appear in the UI immediately after the build completes without manual menu editing.

Complete Code Example

The following example demonstrates registering a custom buffer tool in the vector processing catalog:

// packages/processing/src/vector-tools.ts
import type { ProcessingAlgorithm, ProcessingContext } from "./types";

// 1. Define the algorithm implementation
export const myCustomBufferTool: ProcessingAlgorithm = {
  id: "my_custom_buffer",
  name: "Custom Buffer",
  description: "Buffers input geometries by a user-specified distance.",
  
  // UI parameters shown in the execution dialog
  parameters: [
    {
      id: "distance",
      name: "Distance",
      description: "Buffer distance in map units",
      kind: "number",
      default: 10,
    },
  ],
  
  // 2. Implement the execution logic
  async run(context: ProcessingContext, params) {
    const { distance } = params;
    const { duckdb } = context;
    
    const source = await duckdb.registerGeoJson(context.layer.geojson);
    const result = await duckdb.query(`
      SELECT ST_Buffer(geom, ${distance}) AS geom
      FROM ${source.sql}
    `);
    
    await source.release();
    return { geojson: result.toGeoJSON() };
  },
};

// 3. Register in the vector-tools catalog
export const VECTOR_TOOLS: ProcessingAlgorithm[] = [
  // ...existing tools
  myCustomBufferTool,
];

Algorithm Registry Locations

GeoLibre separates algorithms by domain into specific registry files:

Registry File	Export Array	Purpose
packages/processing/src/vector-tools.ts	VECTOR_TOOLS	Geometry operations like buffer, clip, and union.
packages/processing/src/network-tools.ts	NETWORK_TOOLS	Graph and routing algorithms.
packages/processing/src/h3-tools.ts	H3_TOOLS	H3 hexagonal grid utilities.
packages/processing/src/registry.ts	ALGORITHMS	General-purpose and miscellaneous algorithms.

The registry.ts file also exports helper functions like getAlgorithm that the UI uses to retrieve algorithm definitions by ID.

How the UI Discovers Algorithms

The desktop application (apps/geolibre-desktop/src/components/layout/toolbar/ProcessingMenu.tsx) imports the registry arrays directly and renders menu items dynamically. Because the menu is data-driven from the exported arrays, you do not need to modify any React components or routing configuration when adding new algorithms. The TypeScript compiler ensures that only properly implemented ProcessingAlgorithm objects can be added to these arrays, preventing runtime errors in the UI.

Summary

• Implement the ProcessingAlgorithm interface from packages/processing/src/types.ts to define your algorithm's metadata and execution logic.
• Export your algorithm as a constant from the appropriate tools file (vector, network, or H3).
• Register the algorithm by pushing it into the correct registry array (VECTOR_TOOLS, NETWORK_TOOLS, H3_TOOLS, or ALGORITHMS).
• Rebuild the project; the Processing menu automatically reflects the new entry without manual UI edits.

Frequently Asked Questions

What is the minimum required code to register a simple algorithm?

You need to create an object satisfying the ProcessingAlgorithm interface with at least an id, name, description, empty parameters array, and an async run function. Export this object and add it to VECTOR_TOOLS or ALGORITHMS in packages/processing/src/registry.ts.

Can I register algorithms in custom files outside the standard tool modules?

Yes. You can create a new file in packages/processing/src/, export your algorithm constant, and import it into registry.ts to add it to the ALGORITHMS array. The specific tool modules (vector-tools.ts, etc.) are organizational conventions, not strict requirements.

Does the processing menu update automatically when I add a new algorithm?

Yes. ProcessingMenu.tsx renders the menu dynamically from the registry arrays. After running npm run build or refreshing the dev server, the new algorithm appears immediately in the UI without editing any React components.

How do I handle complex parameter types in the algorithm definition?

The parameters array in ProcessingAlgorithm accepts objects defining kind (e.g., "number", "string", "selection"), default values, and validation rules. The UI renders appropriate input controls based on these definitions, as implemented in the processing dialog components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}