# How to Register New Processing Algorithms in the GeoLibre Catalog

> Learn to register new processing algorithms in the GeoLibre catalog. Implement the ProcessingAlgorithm interface, export your algorithm, and add it to the registry for automatic menu display.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To register a new processing algorithm in GeoLibre, implement the `ProcessingAlgorithm` interface defined in [`packages/processing/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/vector-tools.ts).
- **Network analysis**: Add to `NETWORK_TOOLS` in [`packages/processing/src/network-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/network-tools.ts).
- **H3 grid operations**: Add to `H3_TOOLS` in [`packages/processing/src/h3-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/h3-tools.ts).
- **General purpose**: Add to the top-level `ALGORITHMS` array in [`packages/processing/src/registry.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/registry.ts).

### Rebuild and Verify

Run `npm run build` or `npm run dev` to compile the TypeScript. The [`ProcessingMenu.tsx`](https://github.com/opengeos/GeoLibre/blob/main/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:

```typescript
// 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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/vector-tools.ts) | `VECTOR_TOOLS` | Geometry operations like buffer, clip, and union. |
| [`packages/processing/src/network-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/network-tools.ts) | `NETWORK_TOOLS` | Graph and routing algorithms. |
| [`packages/processing/src/h3-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/h3-tools.ts) | `H3_TOOLS` | H3 hexagonal grid utilities. |
| [`packages/processing/src/registry.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/registry.ts) | `ALGORITHMS` | General-purpose and miscellaneous algorithms. |

The [`registry.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/registry.ts) to add it to the `ALGORITHMS` array. The specific tool modules ([`vector-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.