# Invite to Team
Source: https://docs.nikaplanet.com/guides/access-control/invite-to-team

Learn how to invite users to your team and manage team access permissions

# Invite to Team

Inviting users to your team allows you to collaborate on projects, share resources, and manage access permissions collectively. This guide will walk you through the step-by-step process of inviting new team members using the NikaPlanet interface.

## Overview

Team invitations enable you to:

* Add new collaborators to your workspace
* Assign appropriate permission levels
* Manage team access centrally
* Streamline collaboration workflows

## How to Invite Users to Your Team

### Step 1: Navigate to Settings

From your main workspace view, click on **Settings** in the left navigation sidebar.

<img alt="Navigate to Settings from Workspaces view" />

### Step 2: Access Team Members

In the Settings section, you'll see your team information in the left sidebar. Make sure you select the right team before clicking on **Members** under your team name to access the team members page.

<img alt="Access Team Members section" />

### Step 3: Invite New Members

On the Members page, you'll see a list of current team members. To add someone new, click the **"Invite people"** button below the member list.

### Step 4: Send Invitation

A dialog will open where you can enter the email address of the person you want to invite. Enter their email and click **"Send request"** to send the invitation.

<img alt="Invite people dialog" />

## What Happens Next

### Invitation Sent

Once you send the invitation:

* The new member will appear in your Members list with a "Pending" status
* An email invitation will be sent to the invitee's email address
* The invitation will expire in 7 days if not accepted

### Invitee Receives Email

The person you invited will receive an email that looks like this:

<img alt="Email invitation received" />

The email contains:

* A personalized invitation message
* A **"Join Team"** button to accept the invitation
* Information about the team they're being invited to join
* Expiration details (7 days)

### Invitation Acceptance

When the invitee clicks the **"Join Team"** button in their email:

* They'll be redirected to create or sign into their NikaPlanet account
* Once accepted, their status will change from "Pending" to "Active" in your Members list
* They'll have immediate access to the team resources based on their assigned role

## Managing Team Members

### Current Members

Your Members page shows all team members with their:

* Email address
* Username
* Role (Owner, Member, etc.)
* Actions available (delete, change role, etc.)

### Pending Invitations

Track the status of sent invitations:

* **Pending**: Invitation sent but not yet accepted
* **Active**: User has joined the team
* **Expired**: Invitation has expired and needs to be resent

### Resending Invitations

If an invitation expires or the user doesn't respond, you can resend the invitation from the Members management interface.

## Permission Levels

Team members typically have these access levels:

* **Owner**: Full access to team settings and member management
* **Member**: Can access team resources and collaborate on projects
* **Custom**: Tailored permissions based on specific needs only for **Enterprise License** users

## Best Practices

1. **Clear Communication**: The invitation email automatically includes context about your team
2. **Appropriate Permissions**: Start with standard member access and adjust as needed
3. **Regular Review**: Periodically review team member access and permissions
4. **Follow Up**: Check with invitees if they haven't accepted within a few days

## Workspace Access and Team Permissions

### Creating Workspaces Under Teams

When you create a new workspace using the "Create New Workspace" dialog, it will automatically be associated with the selected team and default to giving **"Can edit"** access to all team members.

<img alt="Create New Workspace dialog" />

**Before Creation**: You can configure the default team access level:

* **Can edit**: Team members can modify and manage the workspace
* **Can comment**: Team members can view and add comments
* **Can view**: Team members have read-only access
* **Not shared**: Other members of the team will not be able to access this workspace

### Managing Workspace Access After Creation

Once a workspace is created, you can modify team access permissions by:

1. **Opening the Share Dialog**: Click the share button in the top right corner of any workspace
2. **Accessing "People with access"**: Navigate to the "People with access" section
3. **Modifying Team Permissions**: Change the access level for "Nika's Team" or individual team members

<img alt="Share dialog with team access management" />

**Available Permission Levels**:

* **Can edit**: Full editing and management capabilities
* **Can comment**: Ability to view and add comments
* **Can view**: Read-only access to workspace content
* **Not shared**: No access to the workspace

**Additional Options**:

* **Send invite email**: Automatically notify team members of access changes
* **Individual member management**: Set different permissions for specific team members vs. the entire team

## Troubleshooting

### Common Issues

* **Invitation Not Received**: Ask the invitee to check their spam/junk folder
* **Permission Errors**: Ensure the user has the correct role assignments
* **Team Access**: Verify the user is assigned to the correct team(s)

### Getting Help

If you encounter issues with team invitations, contact your team administrator or reach out to NikaPlanet support for assistance.

## Next Steps

After successfully inviting team members:

* [Invite to Workspace](/guides/access-control/invite-to-workspace) - Learn how to invite users to specific workspaces


# Invite to Workspace
Source: https://docs.nikaplanet.com/guides/access-control/invite-to-workspace

Learn how to invite users to specific workspaces and manage workspace-level access permissions

# Invite to Workspace

Inviting users to specific workspaces allows you to grant access to particular projects, datasets, or collaborative environments while maintaining security boundaries. This guide covers the process of inviting users to individual workspaces.

## Overview

Workspace invitations provide:

* Granular access control to specific projects
* Secure collaboration on sensitive data
* Project-specific permission management
* Temporary or permanent access options

## How to Invite Users to a Workspace

### Step 1: Access the Share Dialog

From your workspace dashboard, locate and click the **Share** button in the top navigation bar. This button is prominently displayed and will open the sharing interface.

<img alt="Workspace Dashboard with Share Button" />

### Step 2: Navigate to the Share Tab

In the sharing dialog, you can see a dropdown to select the current workspace's sharing mode, which includes:

* *Anyone with link can edit* - least secure but public access for anyone with a Nika account
* *Anyone with link can comment* - same as above, but public users can not edit assets in this workspace
* *Anyone with link can view* - same as above, but public users can not edit nor comment on assets in this workspace
* *Only people added can access* - workspace is not open to public, but only people or teams listed in the `People with access` section above

<img alt="Share Dialog with Share Tab Selected" />

<img alt="Share Dialog sharing options" />

### Step 3: Add People or Team to Your Workspace

In the **"People with access"** section, click on the input field labeled **"Add people or groups"**. This field allows you to search for and add new collaborators to your workspace.

<img alt="Email Input and Role Selection" />

### Step 4: Enter Email and Select Role

Type the email address of the person you want to invite (e.g., "[david@nikaplanet.com](mailto:david@nikaplanet.com)"). After entering the email, you'll see a dropdown menu appear where you can select the appropriate role:

* **Editor**: Can create, modify, and delete assets within the workspace
* **Commentator**: Can view content and add comments
* **Viewer**: Read-only access to workspace resources

<img alt="Invitation Settings Configuration" />

Review all the invitation details including the email address, selected role, and email notification setting. Once satisfied, click the **"Share"** button at the bottom of the dialog to send the invitation.

### Step 5: Complete the Sharing Process

The invited user will receive an email invitation and can accept it to join your workspace with the specified permissions.

<img alt="Email Invitation Sent" />

## Workspace Access Levels

Different permission levels are available for workspace access:

* **Owner**: Full control over the workspace, including deletion and member management (shown as "Owner" in the interface)
* **Editor**: Can create, modify, and delete content within the workspace
* **Commentator**: Can view content and add comments to workspace resources
* **Viewer**: Read-only access to workspace resources and content

## Workspace-Specific Permissions

### Content Access

* **Files**: in Nika's data lake for this workspace
* **Notebook instances**: in [Nika Notebook](/guides/data-analysis/create-your-first-notebook) which is a Jupyter-compatible collaborative python notebook for data science analysis
* **Map instances**: in [Nika Map](/guides/become-map-expert/create-your-first-map)which uses Nika's collaborative map engine that handles geospatial analysis for GB sized vector and raster data sources

### Collaboration Features

* **Comments**: Enable or disable commenting capabilities
* **Sharing**: Control whether users can share workspace content externally
* **Export**: Manage data export and download permissions

## Managing Workspace Invitations

### Invitation Status Tracking

Monitor the status of workspace invitations:

* **Pending**: Invitation sent but not yet accepted
* **Accepted**: User has joined the workspace
* **Expired**: Invitation has expired and needs renewal

## Security Considerations

### Access Control Best Practices

1. **Principle of Least Privilege**: Grant only the minimum access necessary
2. **Regular Audits**: Periodically review workspace access and permissions
3. **Temporary Access**: Use time-limited access for external collaborators
4. **Activity Monitoring**: Track user actions within sensitive workspaces

### Data Protection

* Ensure invited users understand data handling requirements
* Implement appropriate data classification and access controls
* Monitor for unusual access patterns or unauthorized sharing

## Troubleshooting

### Common Workspace Invitation Issues

* **Permission Denied**: Verify you have edit rights to the workspace to be able to invite others into this workspace
* **User Not Found**: Check email address accuracy and user account status
* **Invitation Limits**: Check if you've reached workspace invitation limits

### Getting Support

For workspace access issues:

* Contact your team/org administrator
* Review workspace settings and permissions
* Reach out to support for technical assistance

## Next Steps

After setting up workspace invitations:

* [Invite to Team](/guides/access-control/invite-to-team) - Learn about team-level invitations


# Add Layers to Map
Source: https://docs.nikaplanet.com/guides/become-map-expert/add-layers-to-map

Learn how to add data layers to your map using drag and drop, right-click, and file upload methods

Learn how to add data layers to your NikaMap using multiple methods. You can drag files from the Files panel, upload from your desktop, or use the right-click context menu.

## Step 1: Prepare Your Data

Before adding layers, make sure your data is ready:

### Supported File Formats

#### Vector Data Formats

* **Shapefile Components**: .shp, .shx, .dbf, .prj, .cpg, .fix, .sbn, .sbx, .fbn, .fbx, .ain, .aih, .atx, .qix, .qmd
* **GeoPackage**: .gpkg (modern, efficient vector format)
* **FlatGeobuf**: .fgb (fast, compressed vector format)
* **GeoJSON**: .geojson, .json (web-friendly vector format)
* **KML/KMZ**: .kml, .kmz (Google Earth format)
* **GML**: .gml (Geography Markup Language)
* **GeoParquet**: .gpq, .parquet, .geoparquet (columnar format)
* **CSV**: .csv (with coordinate columns)
* **Parquet**: .parquet (efficient columnar storage)
* **GeoParquet**: .geoparquet (spatial extension of Parquet)

#### Raster Data Formats

* **GeoTIFF**: .tif, .tiff, .TIF, .TIFF (high-quality raster format)
* **JPEG**: .jpg, .jpeg, .JPG, .JPEG (compressed image format)

### File Requirements

* **Size Limits**: Files up to several GBs for raster and up to 500 MBs for vector are supported
* **Coordinate System**: Data should have proper spatial reference that can be converted to ESPG:3857 Mercator that NikaMap uses
* **File Structure**: Ensure files are not corrupted or lack of georeferencing (i.e. no lon lat coordinates at all)

## Step 2: Upload Files to Your Opened NikaMap

### Method 1: Upload via Existing Files in NikaWorkspace

1. **Open Files Panel**: Click "Files" in the left sidebar
2. **Multiselect Files**: Hold Shift/Cmd/Ctrl on your keyboard while selecting multiple files
3. **Right Click**: Right click on one of the selections and click Add to Map with the correct destination map selected
4. **Wait for Processing**: Files will be processed before adding to the map automatically. Larger files will take longer to come back because of network transimission despite encrypted

<img alt="Upload Files" />

### Method 2: Drag and Drop Files from NikaWorkspace

Same as **Method 1**, just via dragging

**Note**: Make sure you drop to the centered section of the map, if not it will be treated as opening it as a text file

<img alt="Drag from Files Panel" />

### Method 3: Drag from Desktop

1. **Drag Files**: Drag files directly from your desktop to the map
2. **Auto-upload**: Files will be uploaded and preprocessed before adding to the map automatically

<img alt="Drag from Desktop" />

### Method 4: Choose Desktop Files Using Upload Button

1. **Click Upload**: Left-click on Upload button from NikaMap's top bar
2. **Select Files**: Choose the relevant files from your local file system to upload as layers

<img alt="Right-Click Add to Map" />

## Step 3 Context Menu Options

* **Add to Current Map**: Add to the currently active map
* **Add to Specific Map**: Choose from a list of your maps
* **Add as New Layer**: Create a new layer (default behavior)
* **Replace Existing**: Replace an existing layer with the same name

## Step 4: Layer Reordering

### Sort Added Layers

1. **Layers Panel**: Look for the layers panel on the left side. If you dont see it, make sure a map panel is selected in the middle with left sidebar opening for list of maps
2. **Layer List**: All added layers will appear in the list at bottom left
3. **Layer Reordering**: Drag and drop a layer to make them appear on top or below. The ones at bottom will show up on top in the map

<img alt="Layers Panel" />

## Step 5: Layer Attribute Table

### View Layer Properties

1. **Right-click Layer**: Right-click on a vector layer to open `attributes` in a table format
2. **Select features**: As each row of entry in the table represents one geometry feature on map, selecting it in table will also select it on map
3. **Update Information**: Data field update in the table will immediately be saved as well, just like the geometry features on map

<img alt="Layer Properties" />

### Layer Controls

* **Visibility Toggle**: Click the eye icon on a single layer to show/hide layers
* **Group Visibility**: Click the same eye icon on a group of layer with folder icon to show/hide all descendent layers
* **Layer Properties**: Right-click on a layer to access styling options
* **Vector Functions**: Right-click on a vector layer to access function options
* **Delete Layer/Group**: Right-click on a layer or group node to delete them instantly from the map

## Step 6: Copy Features to a New Layer

You can copy features from one vector layer into a brand-new layer — either all features at once, or only a selected subset.

### Copy All Features

1. **Right-click** on a vector layer in the layers panel
2. Select **"Copy all features to new layer"**
3. A new layer named **"Copy of \[original name]"** appears in the layer list with all features duplicated

### Copy Selected Features

1. **Select the vector layer** by clicking on it in the layers panel
2. **Select features** on the map by clicking individual features, or multi-select from the attribute table
3. **Right-click** on the layer in the layers panel
4. The menu item now shows **"Copy N feature(s) to new layer"** where N is the number of selected features
5. Click it to create a new layer containing only the selected features
6. Your selection is automatically cleared after the copy completes

<Tip>
  This is useful for splitting a large dataset into smaller layers based on specific features of interest, or for isolating a subset of features to style or export independently.
</Tip>

## Step 7: Customize Layer Appearance

### Access Layer Styling

1. **Vector Layer**: Go to [Vector Layer Stylings](/guides/become-map-expert/vector-styling) to view all styles currently supported
2. **Raster Layer**: Go to [Raster Layer Stylings](/guides/become-map-expert/raster-styling) to view all visualizations currently supported

## Step 8: Export Layers from Map

### Different Export options

1. **Single Vector Layer**: Right-click to export as GeoJson from map. Choose whether to desktop or to NikaWorkspace file storage
2. **Group of Layers**: Right-click to export as GeoPackage from map. Choose whether to desktop or to NikaWorkspace file storage

<img alt="Layer Properties" />

## Step 9: Troubleshooting Common Issues

### Layer Not Appearing

* **Check Visibility**: Ensure the layer is visible (eye icon)
* **Zoom to Layer**: Double-click to zoom to layer from the layer list at bottom left
* **Coordinate System**: Verify the data has proper spatial reference
* **File Format**: Confirm the file format is supported and its layer appears in the layer list at bottom left after dragged to map

### Performance Issues

* **Large Files**: Consider simplifying large datasets
* **Too Many Layers**: Remove unnecessary layers
* **Browser Cache**: Refresh the page if needed
* **Network**: Check your internet connection

### Styling Problems

* **Reset Styling**: Use the reset button in styling panel
* **Default Colors**: Apply default color schemes
* **Layer Order**: Ensure layers are in the correct order

## Tips and Best Practices

### Layer Management

* **Logical Ordering**: Arrange layers in logical order (background to foreground)
* **Naming Convention**: Use consistent naming for layers
* **Grouping**: Consider grouping related layers
* **Cleanup**: Remove unused layers regularly

### Performance Optimization

* **File Size**: Keep individual files under reasonable size limits
* **Simplification**: Simplify complex geometries when possible
* **Caching**: Allow time for layers to cache properly
* **Browser**: Use a modern browser for best performance

## Next Steps

Now that you've added layers to your map:

1. **Style Your Layers**: Customize the appearance of your data
2. **Work with Vector Layers**: Learn about [Vector Layer in NikaMap](/guides/become-map-expert/vector-styling)
3. **Collaborate**: Explore [Collaborative Mapping](/guides/become-map-expert/collaborative-mapping)
4. **Publish**: Learn how to [Publish Your Map](/guides/become-map-expert/publish-map)

Happy mapping!


# Switch Base Map
Source: https://docs.nikaplanet.com/guides/become-map-expert/change-base-map

Base map is the styled map that your layers will be displayed on. Sometimes changing it can give you more contrast and comparison with your own layer data

Switch between the three supported base map types to provide the best background for your data visualization.

<img alt="Switch Base Map" />

## Available Base Maps

### 1. **DataViz**

* Clean, minimal background optimized for data visualization
* Best for: Charts, graphs, and data-focused presentations

### 2. **OpenStreetMap**

* Detailed street maps with roads, buildings, and place names
* Best for: Urban analysis, navigation, and location-based data

### 3. **Satellite**

* High-resolution satellite imagery showing natural landscape
* Best for: Environmental analysis, land use studies, and remote sensing

## How to Change Base Map

1. **Right-click** on your map area
2. **Select "Change Base Map"** from the context menu
3. **Choose** your preferred base map type
4. **Changes are auto-saved** immediately

## Custom Base Maps

Need a different base map? You can:

* **Request new base maps** via our [community forum](https://github.com/orgs/NikaEco/discussions)
* **Contact support** for custom base map URLs
* **Send feedback** about base map options

## Next Steps

* **Set Initial View**: Optimize your map display
* **Sync Multiple Map Views**: Coordinate multiple map views
* **Publish Your Map**: Share with others


# Multi-user Edits on the Same Map
Source: https://docs.nikaplanet.com/guides/become-map-expert/collaborative-mapping

Learn how to collaborate with team members on maps with real-time editing and auto-saving features

NikaMap natively supports multi-user editing and auto-saving, allowing your team to work together on the same map in real-time. Changes are synced to other users with low latency, and the system prevents race conditions by blocking layers when they're being edited.

## Step 1: Understanding Collaborative Mapping

### What is Collaborative Mapping?

* **Real-time Collaboration**: Multiple users can edit the same map simultaneously
* **Auto-saving**: All changes are automatically saved and synced
* **Conflict Prevention**: Layer blocking prevents race conditions
* **Low Latency**: Changes appear to other users almost instantly with the exception of large dataset initial load

### Collaboration Features

* **Live Cursors**: See where other users are working on in the same map
* **Edit History**: Track who made what changes in the edit log (to be built soon)

<img alt="Collaborative Mapping" />

## Step 2: Share Your Map for Collaboration

### Enable Collaboration

* **Through NikaWorkspace**: As NikaMap is created under NikaWorkspace, simply invite others (same org or external) to the same worksapce to have immediate access
* **Share Static Version in NikaHub**: The other option is to share the view-only snapshot of your map created by publishing it to NikaHub with various permission levels. See [Publish a Map (with Access Control)](/guides/become-map-expert/publish-map) for more details

### Permission Levels

* **View Only**: Users can view but not edit
* **Commentator**: Users can view and comment but not edit
* **Edit**: Users can make changes to the map
* **Admin**: Users can manage the map and permissions
* **Owner**: Full control over the map

## Step 3: Real-time Editing

### Start Editing

1. **Enter Edit Mode**: Right click on a layer to find edit option or double click the layer on map to enter edit mode
2. **Make Changes**: Edit features, drag the handle around or use draw tools to add new data to the same layer
3. **Save Changes**: Click the tick in the layer list, or click empty spaces on map to leave the edit mode, which will trigger automatic save and sync

## Troubleshooting Any Issues

### Common Issues

* **Layer Won't Show on Map**: If the layer source GeoTIFF or COG, check whether the source file is still there
* **Changes Not Syncing**: Check your internet connection stability, if connection is regained, the previous edit should auto flow through immediately too
* **Performance Issues**: Reduce the number of very dense vector layers which are the usual performance bottlenecks especially if the polygon shapes are complex

### Other Solutions

* **Refresh Map**: Close the Map panel and double click to reopen it
* **Support**: Contact support for persistent issues

Happy Mapping!


# Create your First Map
Source: https://docs.nikaplanet.com/guides/become-map-expert/create-your-first-map

Learn how to create a new map, customize basemaps, and set up your initial view

Learn how to create a new map in NikaMap, customize basemaps, and set up your initial view. Everything gets persisted automatically, so your map will look exactly the same when you reopen it.

## Step 1: Access NikaMap

1. **Navigate to NikaMap**: In NikaWorkspace, click on the Globe icon in the left sidebar
2. **View Map List**: You'll see a list of your existing maps on the left panel
3. **Create New**: Click the "+" button to see two options.

   * **Draft maps** are erased on refresh
   * **Collaborative Saved maps** persist between sessions.

   For now I recommend choosing **Collaborative Saved Map**

<img alt="NikaMap Create" />

4. **First Map**: Your first map will appear in the middle of the screen

<img alt="NikaMap Interface" />

## Step 2: Rename Your Map

1. **Reame**: Right click on a map to open rename dialog
2. **Save**: Click "Save" to finalize

<img alt="Map Naming" />

## Step 3: Choose Your Basemap

When creating a new map, it will by default use `dataviz` basemap, you can follow [Change Base Map](/guides/become-map-expert/change-base-map) to select other options.

## Tips and Best Practices

### Map Organization

* **Descriptive Names**: Use clear, descriptive names for your maps
* **Consistent Naming**: Follow a naming convention for your team
* **Cleaning**: Right click to delete temporary maps that you will no longer use

### Performance

* **Start Simple**: Begin with a basic basemap and add complexity gradually
* **Layer Limits**: Theoretically NikaMap can load large vector and raster
* **Auto Saving**: NikaMap will auto save your changes, no more worry of data loss


# Modify Legend for Viewing
Source: https://docs.nikaplanet.com/guides/become-map-expert/modify-legend

Control which layers appear in the map legend, add captions, and understand how each layer type displays its legend

The Legend view gives you a summarized, read-friendly overview of every layer on your map and what its symbology means. You can toggle layers in and out of the legend, add captions, and reorder entries by reordering the layers themselves.

When your map is published, the legend shown to viewers respects these settings. You can customize which layers show their entries to most effectively present your maps.

## Accessing the Legend

The layer panel has two tabs at the top: **Layers** and **Legend**.

* **Layers tab**: The full layer list where you manage, reorder, and style layers
* **Legend tab**: A focused view showing only the legend-relevant information for each layer

<img alt="Legend Tab" />

Click the **Legend** tab to switch to the legend view.

## Legend Entry Structure

Each layer included in the legend displays:

1. **Layer icon** — indicates the layer type (vector, raster, etc.)
2. **Layer name** — the name as shown in the layer list
3. **Visibility toggle** — an eye icon to show or hide the layer on the map directly from the legend
4. **Remove from legend button** — an X icon to exclude the layer from the legend without removing it from the map
5. **Caption** (if set) — descriptive text displayed below the layer name
6. **Symbology** — the visual representation of how the layer is styled (color swatches, gradients, class breaks, etc.)

<img alt="Legend Example" />

## Show and Hide Layers in the Legend

By default, all layers are **included** in the legend. You can control which layers appear.

### Remove a Layer from the Legend

You have two options:

* In the **Legend tab**: Click the **X** button on any legend entry to remove it
* In the **Layer Styles panel**: Toggle the **Show** switch off in the Legend section

<img alt="Layer Style Control" />

The layer remains on the map — it is only hidden from the legend view.

### Restore a Layer to the Legend

Layers removed from the legend appear in a collapsible **"Other layers"** section at the bottom of the Legend tab.

1. Click **"Other layers (N)"** to expand the section
2. Click the **arrow-up icon** next to any layer to add it back to the legend

<img alt="Layer Style Control" />

Alternatively, open the layer's styling panel and toggle the **Show** switch on in the Legend section.

### Toggle Layer Visibility

The **eye icon** on each legend entry controls whether the layer is visible on the map. This is the same as toggling visibility in the Layers tab — hidden layers remain in the legend but are not rendered on the map.

## Add a Caption

Captions add descriptive text below the layer name in the legend entry.

1. **Select the layer** to open its styling panel
2. Expand the **Legend** section
3. Type your caption in the **Caption** field
4. The caption is saved automatically (with a short debounce delay)

Captions appear in both the Legend tab and when the map is published.

## Legend Order

The legend displays layers in the **same order as the layer list**. To change the legend order:

1. Switch to the **Layers** tab
2. **Drag and drop** layers to reorder them
3. Switch back to the **Legend** tab — the order is reflected immediately

Layers at the bottom of the layer list render on top of the map, and appear in the same position in the legend.

## How Each Layer Type Displays in the Legend

The legend automatically generates symbology based on each layer's current styling configuration.

### Vector Layers

Vector layer legends are organized by geometry type when a layer contains mixed geometries. Each geometry section shows its own symbology.

#### Polygons

* **Solid color**: A filled square swatch showing the fill color, with an outline if stroke is enabled
* **Gradient (continuous)**: A smooth color ramp bar with min/max labels, labeled by the property name
* **Gradient (discrete/classify)**: A list of colored swatches with value range labels (e.g., "0.5 – 1.2")
* **Unique values**: A list of colored swatches, one per unique value with its label

#### Lines

* **Solid color**: A horizontal line swatch in the line color
* **Gradient / Unique values**: Same class-break or value list format as polygons, but with line swatches

#### Points

* **Solid color**: A filled circle swatch in the icon/point color
* **Gradient / Unique values**: Same format as polygons, but with circle swatches

### Raster Layers

Raster legend display depends on the visualization type and color mode.

#### Single Channel with Named Colormap

A **color ramp bar** showing the gradient from the selected colormap (e.g., Viridis, Blues), with min and max rescale values at either end. The band name or algebra expression is shown as a label.

#### Single Channel with Classify

A **discrete class list** showing colored swatches for each class break with value range labels (e.g., "\< 0.2", "0.2 – 0.4", ">= 0.8").

#### Single Channel with Unique Values

A **value list** showing one colored swatch per unique integer value, with custom labels if set.

#### RGB Channels (Multi-Channel)

A three-part **red/green/blue swatch** labeled "RGB Composite", with the band assignments listed below (e.g., "R: b4 · G: b3 · B: b2").

#### Raster Algebra

Displays the same as Single Channel — the algebra expression name (e.g., NDVI) is shown as the label, with the colormap gradient and rescale range.

#### No Colormap Set

Falls back to a **grayscale gradient** bar (black to white) with the rescale range.

<div>
  <img alt="Sample Legend Appearance 1" />

  <img alt="Sample Legend Appearance 2" />
</div>

## Best Practices

* **Include only meaningful layers** — remove background or reference layers from the legend to keep it focused on the data that matters
* **Add captions** to provide context — a short description like "Population density per km²" makes the legend self-explanatory
* **Use consistent layer naming** — legend entries show the layer name, so clear names make the legend readable without captions
* **Order layers logically** — since legend order follows layer order, arrange layers so the legend reads naturally from top to bottom


# Publish a Map (with Access Control)
Source: https://docs.nikaplanet.com/guides/become-map-expert/publish-map

Learn how to publish your map with team-only, public or password-protected access, including thumbnail generation and collaboration features

Learn how to publish your NikaMap for team-only, public, or password-protected sharing. You can publish maps with different names, generate thumbnails using AI, and control access settings.

## Step 1: Access Publish Options

### Method 1: Right-Click on Map List

1. **Open Map List**: Navigate to your maps in the left panel
2. **Right-click Map**: Right-click on the map you want to publish
3. **Select "Publish"**: Choose the publish option from the context menu

<img alt="Right-click to Publish" />

### Method 2: Publish Button in Map

1. **Open Your Map**: Open the map you want to publish
2. **Find Publish Button**: Look for the publish button in the top-right toolbar
3. **Click Publish**: Click the publish button to open the publish dialog

## Step 2: Fill in Compulsory Fields

### Required Information (marked with asterisk \*)

1. **Title**\*: Enter a descriptive name for your published map
2. **Version**\*: Specify the version number (e.g., "1.0.0")
3. **Category**\*: Add at least one category by clicking "+ Add Category"

### Optional Information

* **Description**: Add a detailed description of the map content (optional)
* **Tags**: Add relevant tags for categorization (optional)

### Thumbnail Options

You have three options for creating a thumbnail:

#### Option 1: URL

* Enter an image URL in the "Image URL" field

#### Option 2: Upload

* Click "Upload" and select an image file from your computer

#### Option 3: AI Generate (Recommended if no thumbnail)

* Click "AI Generate" with the sparkle icon
* AI will automatically create a relevant thumbnail based on your map content

### Access Control Settings

* **Public**: Anyone from public can discover and access the map. All public content can be found at [Nika Hub](https://planet.nika.eco/en/hub)
* **Password Protected**: Anyone with the link can access with password. Share the link and password with specific users
* **Restricted (Team Only)**: Only people from your organization can discover and access. All team published content can be found at [Team Hub](https://planet.nika.eco/en/dashboard/team-hub) if you are already signed in

<img alt="Publish Dialog with Required Fields" />

## Step 3: Update Published Map

### Access Update Options

1. **Open Published Map**: Open your published map
2. **Find Update Button**: Look for the update option in the publish dialog
3. **Modify Information**: Change any of the following:
   * Title and version
   * Description
   * Categories
   * Thumbnail (URL, upload, or AI generate)
   * Tags
   * Access Control (Public, Password Protected, or Team Only)

### Update Process

1. **Make Changes**: Modify the desired information
2. **Review Settings**: Double-check all settings
3. **Click "Update"**: Click the update button to republish changes
4. **Alternative: Unpublish**: Use "Unpublish" button to remove from public/team access

<img alt="Update Published Map Dialog" />

## Step 4: View Published Map

### Access Published Map

1. **Click Arrow Icon**: Click the arrow icon at the top right of the publish dialog
2. **New Tab Opens**: A new browser tab will open with your published map
3. **Static View**: The map opens in a static, view-only format

### Published Map Features

* **View-Only Access**: Users can view but not edit the map
* **Layer Visibility**: All layers are visible as configured
* **Interactive Elements**: Map maintains interactive features like zoom and pan
* **Public Hub**: If published publicly, the map appears in the NikaHub

<img alt="Published Map View" />

## Best Practices

### Before Publishing

* **Finalize Your Map**: Ensure all layers and styling are complete
* **Set Initial View**: Position the map at the desired initial view
* **Test Functionality**: Test all interactive features
* **Optimize Performance**: Ensure good loading performance

### Content Quality

* **Accurate Data**: Ensure data accuracy and currency
* **Clear Visualization**: Create clear and informative visualizations
* **Proper Styling**: Use appropriate styling and colors
* **Clear Documentation**: Provide clear descriptions and documentation

### Publishing Strategy

* **Consistent Naming**: Use consistent naming conventions
* **Regular Updates**: Keep published maps current and updated
* **Quality Assurance**: Implement quality assurance processes
* **Community Engagement**: Engage with community feedback

## Troubleshooting

### Common Issues

* **Publishing Fails**: Check that all required fields (marked with \*) are filled
* **Thumbnail Issues**: Use AI generation if you don't have a thumbnail
* **Permission Problems**: Verify access control settings (Public, Password Protected, or Team Only)
* **Update Issues**: Ensure you click "Update" after making changes

### Solutions

* **Validate Data**: Ensure all data is valid and properly formatted
* **Check Required Fields**: Review all fields marked with asterisks
* **Test Locally**: Test map functionality before publishing
* **Contact Support**: Contact support for persistent issues

## Next Steps

Now that you've published your map:

1. **Share**: Share your published map with your team or community
2. **Monitor**: Monitor engagement and feedback
3. **Update**: Keep your map current and updated
4. **Engage**: Engage with the community and respond to feedback

Happy publishing!


# Raster Layer Styling
Source: https://docs.nikaplanet.com/guides/become-map-expert/raster-styling

Customize raster layer visualization with band selection, color modes, range adjustments, and spectral indices

Customize how your raster layers appear on the map using the Layer Styles panel. Control visualization types, band selection, color mapping, and data ranges to effectively display your raster data.

<img alt="Raster Layer Styling Overview" />

## How to Style Raster Layers

### Access Styling Panel

1. **Click on a raster layer** in the layers panel to select it
2. The **styling panel opens** on the side with all raster customization options
3. Use the **header buttons** to zoom to the layer, access layer settings (rename, remove, etc.), or unselect the layer

### Available Styling Sections

#### **General Section**

* **Type**: Choose visualization method — Single Channel, RGB Channels, Raster Algebra, or Hillshade
* **Band Selection**: Select which bands to display (options change based on type)
* **Range**: Set data range for each band using absolute values or percentiles

#### **Raster Section**

* **Color Mode** (Single Channel only): Choose between Named Colormap, Classify, or Unique Values
* **Color**: Select a color map from grouped presets, or configure custom classification stops
* **Clip** (Google Earth Engine layers only): Clip the raster to a polygon vector layer on the map
* **Opacity**: Adjust layer transparency (0–100%) with a slider and numeric input
* **Position**: Control layer stacking order
* **Resample**: Select resampling method for zoom levels

#### **Legend Section**

* **Show**: Toggle legend visibility on or off
* **Caption**: Add descriptive text for the layer legend

#### **Popups Section**

* **Show**: Configure when popup information appears (Hover Only)

#### **Info Section**

* **File type**: Shows raster format — Cloud Optimized GeoTIFF or GeoTIFF (with a warning if not cloud-optimized)
* **File name**: Display file name
* **CRS**: Show coordinate reference system

## Visualization Types

<img alt="Visualization Types" />

### Single Channel

* **Display one band** at a time
* **Choose band**: Select from any available band in the dataset
* **Set range**: Adjust min/max values for the selected band
* **Apply color mode**: Use Named Colormaps, Classify, or Unique Values

### RGB Channels

Available when the raster has more than one band.

* **Display three bands** mapped to red, green, and blue channels
* **Band Red / Green / Blue**: Select which band maps to each channel
* **Individual ranges**: Set min/max or percentile values independently for each channel

### Raster Algebra

Available for non-GEE rasters with more than one band. Compute spectral indices from band math.

* **Select an expression**: Choose from built-in spectral indices
* **Map bands**: Assign which dataset bands correspond to each variable in the formula
* **Set range**: Adjust display range for the computed result

#### Built-in Spectral Indices

| Index | Formula | Description |
| - | - | - |
| **NDVI** | `(NIR-R)/(NIR+R)` | Vegetation health and density |
| **EVI** | `2.5*((NIR-R)/(NIR+6*R-7.5*B+1))` | Enhanced vegetation, high-biomass sensitivity |
| **SAVI** | `((NIR-R)/(NIR+R+0.5))*(1.5)` | Soil-adjusted vegetation index |
| **NDWI** | `(G-NIR)/(G+NIR)` | Water body detection |
| **NBR** | `(NIR-SWIR)/(NIR+SWIR)` | Burn area and severity |
| **NDRE** | `(NIR-RedEdge)/(NIR+RedEdge)` | Chlorophyll content for precision agriculture |
| **GNDVI** | `(NIR-G)/(NIR+G)` | Chlorophyll concentration (more sensitive than NDVI) |
| **NDBI** | `(SWIR-NIR)/(SWIR+NIR)` | Urban areas and bare soil |
| **NDMI** | `(NIR-SWIR)/(NIR+SWIR)` | Vegetation water content |
| **ARVI** | `(NIR-(2*R-B))/(NIR+(2*R-B))` | Atmospherically resistant vegetation |
| **BSI** | `((SWIR+R)-(NIR+B))/((SWIR+R)+(NIR+B))` | Bare soil detection |
| **MSAVI** | `(2*NIR+1-sqrt((2*NIR+1)^2-8*(NIR-R)))/2` | Modified soil-adjusted vegetation |
| **BAI** | `1/((0.1-R)^2+(0.06-NIR)^2)` | Post-fire burn area emphasis |
| **GLI** | `(2*G-R-B)/(2*G+R+B)` | Green leaf fraction estimation |
| **CIG** | `(NIR/G)-1` | Leaf chlorophyll content |

### Hillshade

* **Select a band** for terrain shading (currently in preview)

## Band Range Adjustment

<img alt="Band Range Control" />

Click the **Range** button next to any band to open the range popover with a histogram and controls.

### Range Mode

* **Absolute**: Set explicit min and max values for the band
* **Percentile**: Set a low and high percentile (e.g., p2–p98) to clip outliers automatically

### Adjust Min/Max Values

1. **Open the range popover** by clicking the range display
2. **Choose a mode** — Absolute or Percentile
3. **Enter values** directly or **drag the histogram sliders** to set the range
4. **See real-time updates** on the map

### Adapt Min/Max To

* **Window**: Recalculate statistics based on the current map viewport
* **Entire Layer**: Reset to the full data range across the entire dataset

When adapted to a window, the range button shows a visual indicator. Click **Entire Layer** to reset.

### Histogram Display

* **Data distribution**: See how pixel values are spread across the band
* **Draggable range sliders**: Adjust min/max directly on the histogram
* **Color gradient preview**: The histogram reflects the currently applied color map

## Color Modes

<img alt="Color Map Options" />

Color modes are available when using **Single Channel** visualization. RGB Channels always display the raw band values as red, green, and blue.

### Named Colormap

Select from a library of predefined color maps, organized by category:

| Category | Color Maps |
| - | - |
| **Basic** | None (grayscale) |
| **Perceptually Uniform Sequential** | Blues, Greens, Oranges, Purples, Reds |
| **Sequential** | Viridis, Plasma, Inferno, Magma, Cividis |
| **Sequential 2** | BuGn, BuPu, GnBu, OrRd, PuBu, PuBuGn, PuRd, RdPu, YlGn, YlGnBu, YlOrBr, YlOrRd |
| **Diverging** | BrBG, PRGn, PiYG, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral |
| **Cyclic** | Twilight, Twilight Shifted |
| **Qualitative** | Accent, Dark2, Paired, Pastel1, Pastel2, Set1, Set2, Set3 |
| **Miscellaneous** | Gist Earth, Terrain, Ocean, Jet, Rainbow, Cubehelix, and more |

Each color map shows a **gradient preview** in the dropdown so you can see the colors before applying.

### Classify

Group pixel values into discrete classes with custom color stops.

* **Preset ramp**: Choose a starting color ramp
* **Number of classes**: Set how many bins to divide the data into (default: 5)
* **Apply**: Generate evenly spaced class breaks from the preset
* **Edit individual stops**: Adjust break values and colors for each class

<img alt="Classify Example" />

### Unique Values

Available when all pixel values in the band are integers (up to 100 unique values).

* **Preset ramp**: Apply a color ramp across all unique values
* **Edit individual colors**: Click any color swatch to customize
* **Labels**: Add descriptive labels to each unique value for the legend

<img alt="Unique Values Example" />

## Resampling Methods

Control how pixel values are interpolated when zooming. Available methods:

* **Nearest**: No interpolation, preserves original values
* **Bilinear**: Linear interpolation between 4 nearest pixels
* **Cubic**: Cubic interpolation for smoother results
* **Cubic Spline**: Spline-based cubic interpolation
* **Lanczos**: High-quality resampling with Lanczos windowing
* **Average**: Average of contributing pixels
* **Mode**: Most common value among contributing pixels
* **Gauss**: Gaussian-weighted interpolation
* **RMS**: Root mean square of contributing pixels

## Auto-Save Feature

All styling changes are **automatically saved** for future sessions:

* **Settings persist** when you close and reopen the map
* **No manual saving** required
* **Consistent appearance** across sessions
* **Team collaboration** benefits from saved settings

## Best Practices

### Choose Appropriate Visualization

* **Single Channel**: For analyzing individual bands with color mapping
* **RGB Channels**: For natural color or false color composites
* **Raster Algebra**: For computing spectral indices like NDVI, NDWI, or custom band math

### Set Optimal Ranges

* **Use percentile mode** (e.g., p2–p98) to handle outliers without manual tuning
* **Use the histogram** to understand data distribution before setting ranges
* **Adapt to Window** to focus on the area you're currently viewing

### Select Suitable Color Modes

* **Named Colormap**: Best for continuous data — choose sequential for one-directional data (elevation, temperature) or diverging for data with a meaningful midpoint
* **Classify**: Best for categorizing continuous data into meaningful groups
* **Unique Values**: Best for categorical/integer rasters like land cover or classification results

## Next Steps

* **Add More Raster Layers**: Combine multiple raster datasets
* **Create Composites**: Build custom band combinations with Raster Algebra
* **Publish Your Map**: Share your styled raster layers


# Set Initial View
Source: https://docs.nikaplanet.com/guides/become-map-expert/set-initial-view

Save the current map view as the default opening view

Save your current map view (zoom level and center position) so that whenever the map is reopened, it starts from that exact view state.

<img alt="Set Initial View" />

## How to Set Initial View

### Save Current View

1. **Navigate to your desired view** - pan and zoom to the perfect position
2. **Click the "Save Initial View" button** in the top toolbar
3. **View is now saved** - the map will open to this view every time

### What Gets Saved

* **Center position** - the geographic center of the map
* **Zoom level** - how close or far the view is
* **Current view state** - exactly as you see it now

### Update Initial View

* **Navigate to a new view** and click the save button again
* **Previous view is replaced** with the new one
* **All future opens** will use the updated view

## Use Cases

* **Focus on important data** - center on your key analysis area
* **Professional presentation** - ensure others see the right view first
* **Consistent experience** - everyone opens to the same view
* **Save time** - no need to navigate to the right view each time

## Next Steps

* **Publish Your Map**: Share your map with the saved initial view
* **Add More Layers**: Enhance your map with additional data


# Sync Multiple Map Views
Source: https://docs.nikaplanet.com/guides/become-map-expert/sync-multiple-maps

Synchronize view states across all opened maps for coordinated navigation

Synchronize the center and zoom level across all opened maps with a simple button click. When enabled, panning and zooming on any map will move all other maps to the same view state.

<img alt="Map Synchronization" />

## How to Sync Maps

### Enable Synchronization

1. **Open multiple maps** in separate panels
2. **Click the sync button** in the top toolbar of any map panel
3. **All maps are now synchronized** - panning or zooming on one map moves all others

### What Gets Synced

* **Center position** - all maps show the same geographic center
* **Zoom level** - all maps maintain the same zoom level
* **Real-time updates** - changes happen instantly across all maps

### Disable Synchronization

* **Click the sync button again** to turn off synchronization
* **Maps return to independent navigation** - each map can be moved separately

## Use Cases

* **Compare different datasets** on the same area
* **View different base maps** at the same location
* **Analyze multiple time periods** side by side
* **Coordinate team analysis** with consistent views

## Next Steps

* **Set Initial View**: Optimize your synchronized map display
* **Publish Your Maps**: Share synchronized views with others


# Vector Layer Styling
Source: https://docs.nikaplanet.com/guides/become-map-expert/vector-styling

Customize the appearance of vector layers with polygon fill, line, point icon, text label, and legend options

Customize how your vector layers appear on the map using the Layer Styles panel. Control fill colors, line widths, point icons, text labels, and more to make your data stand out.

## How to Style Vector Layers

### Access Styling Panel

1. **Click on a vector layer** in the layers panel to select it
2. The **styling panel opens** on the side with all vector customization options
3. Use the **header buttons** to zoom to the layer, access layer settings (rename, remove, export, etc.), or unselect the layer

The panel automatically detects your layer's geometry types (points, lines, polygons) and shows only the relevant styling sections.

<img alt="Top Panel Controls" />

### Available Styling Sections

#### **Polygon Style** (polygon layers)

* **Fill Color Type**: Choose between Solid, Gradient, or Unique Values
* **Fill Color**: Pick a color and adjust opacity (0–100%) when using Solid mode
* **Gradient**: Color polygons based on a numeric property using a color ramp with continuous or discrete interpolation
* **Unique Values**: Assign distinct colors to each unique value of a chosen property, with preset ramp or custom colors
* **Elevation Field**: Extrude polygons in 3D based on a numeric property
* **Polygon Outlines**: Toggle stroke visibility on or off
* **Add Polygon Text**: Generate text labels at polygon centroids by selecting a property (creates a new point layer)

<img alt="Polygon Styles" />

#### **Line Style** (line layers and polygon outlines)

* **Line Width**: Set thickness using a slider or numeric input, with unit selection (pixels, meters, km)
* **Line Type**: Choose between Solid or Dashed
* **Dash Parameters**: When dashed, configure dash length and gap (as multiples of line width)
* **Line Color Type**: Choose between Solid, Gradient, or Unique Values
* **Line Color**: Pick a color and adjust opacity (0–100%) when using Solid mode
* **Gradient**: Color lines based on a numeric property using a color ramp with continuous or discrete interpolation
* **Unique Values**: Assign distinct colors to each unique value of a chosen property

<img alt="Line Styles" />

#### **Point Style** (point layers)

* **Icon Color Type**: Choose between Base SVG, Solid, Gradient, or Unique Values
* **Icon Color**: Pick a color and adjust opacity (0–100%) when using Solid mode
* **Gradient**: Color points based on a numeric property using a color ramp
* **Unique Values**: Assign distinct colors to each unique value of a chosen property
* **Icon Size Type**: Choose between Constant, Proportional, or Ranges
* **Icon Size**: Set a fixed size with unit selection (pixels, meters, km) when using Constant mode
* **Proportional Size**: Scale icon size between a min and max based on a numeric property, with linear or logarithmic normalization
* **Range Size**: Define custom size ranges based on a numeric property
* **Icon Anchor Point**: Set where the icon anchors to the point — Top, Middle, or Bottom
* **Icon**: Choose from default icon groups or upload custom SVG icons (searchable library with grouped categories)
* **Point Labels**: Toggle text labels on points

<img alt="Point Styles" />

#### **Text Style** (point layers with labels enabled)

* **Text Property**: Select which feature property to display as text
* **Text Color**: Pick a color and adjust opacity (0–100%)
* **Font Family**: Choose from Arial, Courier New, Helvetica, Inter, JetBrains Mono, Libre Baskerville, Merriweather, Noto Sans, Roboto, or Times New Roman
* **Text Background**: Toggle a background rectangle behind text labels
* **Background Color**: Pick a color and adjust opacity when background is enabled
* **Background Corner Radius**: Adjust border radius of the background rectangle (0–50)
* **Text Size**: Set size with unit selection (pixels, meters, km)
* **Line Width Limit**: Optionally limit how wide a text line can be before wrapping (1–50 characters)
* **Text Outline Color**: Pick a halo/outline color and adjust opacity
* **Text Outline Width**: Set the outline thickness (0–10)
* **Text Position**: Choose anchor and alignment using a 3×3 directional grid
* **Text Pixel Offset X/Y**: Fine-tune text position with pixel offsets

<img alt="Text Styles" />

#### **Legend Section**

* **Show**: Toggle whether the layer appears in the legend
* **Caption**: Add descriptive text for the layer legend

#### **Popups Section**

* **Show**: Configure when popup information appears (Hover Only)

#### **Info Section**

* **Features Selected**: View how many features are currently selected, with an option to unselect all

<img alt="Misc Sections" />

## Color Modes

These color modes apply to both **Polygon Style** and **Line Style** sections. The same three modes are also available for **Point Style** icon coloring (with an additional Base SVG option for points).

### Solid

* **Pick a single color** from the color picker
* **Adjust opacity** with the slider (0–100%)
* All features in the layer share the same color

<img alt="Solid Coloring" />

### Gradient

Color features based on a numeric property value.

1. **Select a numeric property** from the dropdown
2. **Choose a preset color ramp** or customize individual stops
3. **Set interpolation method** — Continuous for smooth gradients or Discrete for classified breaks
4. **Configure number of classes** and apply to generate evenly spaced class breaks

<img alt="Gradient Coloring" />

### Unique Values

Assign a distinct color to each unique value of a chosen property.

1. **Select any property** from the dropdown
2. **Choose a preset color ramp** (including random) or customize individual colors
3. **Edit individual colors** by clicking any color swatch

<img alt="Unique Values Coloring" />

## Icon Library

The icon picker provides a searchable library of icons organized by category.

### Default Icons

Browse grouped icon categories with visual previews. Icons render with the current icon color and anchor settings.

### Custom Icons

Upload your own SVG icons to use as point symbols. Custom icons can be renamed and deleted via the context menu. We recommend using [Lucide](https://lucide.dev) for custom SVG icons.

<img alt="Custom Icons" />

## Auto-Save Feature

All styling changes are **automatically saved** for future sessions:

* **Settings persist** when you close and reopen the map
* **No manual saving** required
* **Consistent appearance** across sessions
* **Team collaboration** benefits from saved settings

## Best Practices

### Choose Appropriate Styling by Geometry

* **Polygon layers**: Use fill color modes (Solid, Gradient, Unique Values) combined with elevation for 3D effects
* **Line layers**: Adjust width, dash patterns, and color modes to distinguish different line features
* **Point layers**: Combine icon selection, sizing modes, and text labels for maximum clarity

### Color Modes

* **Solid**: Best for layers where all features represent the same category
* **Gradient**: Best for continuous numeric data like population density, temperature, or elevation
* **Unique Values**: Best for categorical data like land use types, status codes, or region names

### Text Labels

* **Enable text background** for better readability over complex base maps
* **Adjust outline color and width** to create contrast with the map underneath
* **Use the position grid** to avoid overlapping text with the icon itself

## Next Steps

* **Add More Layers**: Enhance your map with additional data
* **Publish Your Map**: Share your styled vector layers


# Best Practices
Source: https://docs.nikaplanet.com/guides/best-practices/best-practices

Learn best practices for using Nika platform effectively

## Best Practices

Follow these best practices to maximize productivity and collaboration in Nika platform.

## Workspace Organization

### One Project, One Workspace

* **Logical Separation**: Create separate workspaces for each project
* **Data Management**: Easier to manage project-specific data and resources
* **Resource Isolation**: Keep project resources organized and accessible
* **Clean Structure**: Maintain clear boundaries between different projects

### Benefits of Project-Based Workspaces

* **Focused Environment**: Dedicated space for each project's needs
* **Efficient Resource Management**: Better control over data, notebooks, and maps
* **Simplified Collaboration**: Team members can focus on specific projects
* **Easier Maintenance**: Streamlined project lifecycle management

## Team Collaboration

### Team-Based Access

* **Invite to Team**: Add team members directly to your team for full access
* **Workspace Access**: Team members get access to all workspaces under the team
* **Shared Resources**: Collaborate on data, notebooks, and analysis
* **Unified Management**: Centralized team and workspace administration

### Best Practices for Teams

* **Clear Roles**: Define team member roles and permissions
* **Consistent Naming**: Use consistent naming conventions across workspaces
* **Regular Communication**: Keep team informed about workspace changes
* **Resource Sharing**: Leverage shared resources for efficiency

## Resource Management

### Data Organization

* **Structured Folders**: Organize data in logical folder structures
* **Clear Naming**: Use descriptive names for files and datasets
* **Version Control**: Maintain version history for important data
* **Documentation**: Document data sources and processing steps

### Workspace Efficiency

* **Regular Cleanup**: Remove unused resources and data
* **Resource Monitoring**: Keep track of workspace usage and costs
* **Backup Strategy**: Implement regular backups for critical data
* **Performance Optimization**: Use appropriate VM configurations for workloads

*Last updated: August 2025*


# Performance
Source: https://docs.nikaplanet.com/guides/best-practices/performance

Learn how to optimize performance in Nika platform

## Performance

Nika platform leverages advanced data lakehouse architecture to deliver exceptional performance across all services.

## Data Lakehouse Architecture

### Unified Data Platform

* **Single Architecture**: Notebooks, maps, storage, databases, and VMs all powered by one platform
* **Data Lakehouse**: Combines data lake flexibility with data warehouse performance
* **Unified Access**: Seamless data access across all Nika services

### Scalable Infrastructure

* **100TB+ Data Hosting**: Standard capacity for any analysis workload
* **PB-Scale Enterprise**: Petabyte-scale support for large enterprise workloads
* **Auto-Scaling**: Dynamic resource allocation based on demand

## Performance Features

### High-Performance Computing

* **GPU Acceleration**: NVIDIA T4 and H100 GPU support for ML workloads
* **Multi-Core Processing**: Up to 30 CPU cores for parallel processing
* **Memory Optimization**: Up to 156GB RAM for large dataset handling

### Data Processing

* **Streaming Execution**: Real-time data processing and analysis
* **Background Processing**: Long-running tasks continue when workspace is closed
* **Optimized Storage**: Efficient data formats and compression

### Network Performance

* **High-Bandwidth**: Fast data transfer and access
* **Global CDN**: Content delivery network for worldwide access
* **Low Latency**: Minimal delay for interactive operations

## Optimization Best Practices

### Data Management

* **Efficient Formats**: Use optimized file formats (Parquet, COG)
* **Partitioning**: Implement data partitioning for faster queries
* **Caching**: Leverage built-in caching for repeated operations

### Resource Utilization

* **Right-Sized VMs**: Choose appropriate machine configurations
* **Batch Processing**: Process data in manageable chunks
* **Memory Management**: Clean up large variables when done

### Code Optimization

* **Vectorized Operations**: Use vectorized operations over loops
* **Parallel Processing**: Utilize multiple cores for computation
* **Efficient Libraries**: Use optimized libraries (NumPy, Pandas, GDAL)

## Performance Monitoring

### Real-Time Metrics

* **Resource Usage**: Monitor CPU, memory, and GPU utilization
* **Execution Time**: Track code execution performance
* **Data Throughput**: Measure data processing speeds

### Optimization Tools

* **Built-in Profiling**: Performance analysis tools
* **Resource Monitoring**: Real-time resource tracking
* **Performance Alerts**: Automatic performance notifications

*Last updated: August 2025*


# Security
Source: https://docs.nikaplanet.com/guides/best-practices/security

Learn about security best practices in Nika platform

## Security

Nika platform maintains the highest security standards with comprehensive compliance and ongoing audits.

## Compliance & Certifications

### Government Security Clearance

* **29 Security Checks Passed**: Successfully completed with Singapore government clients
* **Government-Grade Security**: Meets stringent government security requirements
* **Multi-Agency Validation**: Approved across multiple government agencies

### SOC II Compliance

* **SOC II Audit in Progress**: Currently undergoing comprehensive SOC II Type II audit
* **Industry Standard**: Following AICPA Trust Services Criteria
* **Continuous Monitoring**: Ongoing security controls and monitoring

## Security Measures

### Data Protection

* **Encryption in Transit**: TLS 1.3 encryption for all data transmission
* **Encryption at Rest**: AES-256 encryption for stored data
* **End-to-End Encryption**: Complete data protection throughout lifecycle

### Access Control

* **Multi-Factor Authentication (MFA)**: Optional for enterprise accounts
* **Role-Based Access Control (RBAC)**: Granular permissions management within team
* **Session Management**: Secure session handling and timeout controls

### Infrastructure Security

* **Secure Cloud Infrastructure**: Enterprise-grade cloud security
* **Network Security**: Advanced firewall and DDoS protection
* **Regular Security Updates**: Automated security patch management

### Compliance Standards

* **GDPR Compliance**: Full compliance with data protection regulations
* **ISO 27001 Framework**: Information security management system
* **Regular Penetration Testing**: Ongoing security vulnerability assessments

## Security Contact

For security-related inquiries:

* **Security Team**: [security@nikaplanet.com](mailto:security@nikaplanet.com)
* **Compliance Questions**: [compliance@nikaplanet.com](mailto:compliance@nikaplanet.com)

*Last updated: August 2025*


# Delegate functions to run in NIKA Planet Runner
Source: https://docs.nikaplanet.com/guides/code-cloud-delegation/python-sdk

Use the NIKA Python SDK to submit notebook functions to managed cloud containers for isolated, long-running execution.

The NIKA Python SDK lets you mark a Python function as cloud-runnable, keep the normal local call path for debugging, and explicitly submit the same function to NIKA-managed compute when you need isolated execution.

<Tip>
  For now, code cloud delegation is designed to run from NIKA cloud notebooks. Local terminals and external notebooks can still import the SDK for development, but remote submission is not a supported workflow outside NIKA notebooks yet.
</Tip>

## Prerequisites

* A cloud NIKA notebook with a running machine
* Access to the workspace or project where the delegated run should execute
* Python code that can be serialized or imported by the remote worker
* Any third-party packages declared in `requirements`
* Inputs and outputs passed as serializable values, workspace file paths, dataset IDs, or other managed references

The SDK package is named `nika_py` and exposes the Python module `nika_py`. The public SDK surface uses run and run-configuration APIs.

```python theme={null}
from nika_py import RunConfig, list_runs, load_run, run
```

## Available SDK Functions

Use these entrypoints from `nika_py`:

| Function or method | What it does |
| - | - |
| `run(compute=..., run_timeout_hours=..., requirements=...)` | Decorates a Python function so it can still run locally and can also be submitted to NIKA cloud compute. |
| `RunConfig(name=...)` | Defines per-submission configuration for one delegated run. |
| `decorated_function(...)` | Calls the original Python function locally in the current notebook kernel. |
| `decorated_function.local(...)` | Explicitly calls the original Python function locally. |
| `decorated_function.submit(..., config=RunConfig(...))` | Submits one invocation to NIKA cloud compute and returns a `RunHandle`. |
| `decorated_function.load(run_id)` | Returns a `RunHandle` for an existing run using the decorated function's client configuration. |
| `load_run(run_id)` | Returns a `RunHandle` for an existing run. |
| `list_runs(status=..., name=..., limit=..., cursor=..., parent_run_id=...)` | Returns a `RunPage` with one page of `RunHandle` objects plus `next_cursor` for pagination. |
| `run_handle.status()` | Fetches the current run status. |
| `run_handle.logs(tail=...)` | Fetches logs, optionally limited to the most recent lines. |
| `run_handle.result()` | Returns the Python result once the run has completed, and raises if the run is still active or failed. |
| `run_handle.wait(timeout=..., poll_interval=...)` | Polls until the result is ready or the wait timeout is reached. |
| `run_handle.cancel(poll_interval=...)` | Requests cancellation for a still-running run and returns a `RunCancellation` awaitable. |
| `run_handle.children(status=..., name=..., limit=...)` | Lists recent child runs whose parent is the current run. |
| `run_handle.parent()` | Loads the parent run when the current handle has parent metadata. |

## Step 1: Decorate a Function

Use `@run` to define the compute target, timeouts, and dependency requirements for the remote invocation. Calling the function normally still runs it in the current notebook kernel.

```python theme={null}
from pathlib import Path

import geopandas as gpd
from nika_py import run


@run(
    compute="CPUx7",
    run_timeout_hours=2,
    requirements=[
        "geopandas>=0.14",
        "pyogrio>=0.7",
        "shapely>=2.0",
    ],
)
def build_buffer_summary(
    input_path: str,
    output_path: str,
    distance_m: float,
) -> dict[str, object]:
    source = gpd.read_file(input_path)
    source_crs = source.crs

    projected = source.to_crs(epsg=3857)
    buffered = projected.copy()
    buffered["geometry"] = projected.geometry.buffer(distance_m)
    buffered = buffered.to_crs(source_crs)

    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
    buffered.to_file(output_path, driver="GeoJSON")

    return {
        "input_features": int(len(source)),
        "output_features": int(len(buffered)),
        "output_path": output_path,
    }
```

Use direct execution first when you are still checking the logic:

```python theme={null}
preview = build_buffer_summary.local(
    "/workspace/data/site-boundary.geojson",
    "/workspace/outputs/site-boundary-buffered.geojson",
    50,
)

preview
```

`build_buffer_summary(...)` and `build_buffer_summary.local(...)` both run in the notebook kernel. Nothing is submitted to cloud delegation until you call `.submit(...)`.

## Step 2: Submit to Cloud Compute

Call `.submit(...)` to serialize the invocation and send it to the NIKA cloud runner available from the notebook.

```python theme={null}
from nika_py import RunConfig

run = build_buffer_summary.submit(
    "/workspace/data/site-boundary.geojson",
    "/workspace/outputs/site-boundary-buffered.geojson",
    50,
    config=RunConfig(name="site-buffer-summary"),
)

run.run_id
```

You can also choose to fan out multiple runs with custom names.

```python theme={null}
runs = [build_buffer_summary.submit(
    "/workspace/data/site-boundary.geojson",
    "/workspace/outputs/site-boundary-buffered.geojson",
    50,
    config=RunConfig(name=f"site-buffer-summary-{i}"),
) for i in range(5)]

print([run.run_id for run in runs])
```

The returned `RunHandle` is a lightweight reference to the remote run. It can poll status, fetch logs, wait for a result, or request cancellation.

```python theme={null}
print(run.status())
print(run.logs(tail=200))

result = run.wait(timeout=3600, poll_interval=5)
result
```

If you call `run.result()` while the run is still `pending`, `initializing`, `running`, or `cancelling`, the SDK raises `RunNotCompleteError`. Use `run.wait(...)` when the notebook should block until the result is ready. The `timeout` argument on `run.wait(...)` is in seconds and only controls how long the notebook blocks — it never affects the run itself. The `run_timeout_hours` and `queue_timeout_hours` options on `@run(...)` are in hours and bound the run.

## Step 3: Choose Compute and Runtime Options

The decorator currently accepts these options:

| Option | Description |
| - | - |
| `compute` | Machine type requested for the delegated run. Supported presets include `CPUx3`, `CPUx7`, `CPUx20`, `CPUx42`, `T4x1`, `T4x2`, `T4x4`, and `H100x1`. |
| `run_timeout_hours` | Optional positive integer in hours, defaulting to `1`. Bounds execution once the run has a machine. The SDK always sends a value, so omitting it submits a one-hour execution timeout rather than deferring to the server. |
| `queue_timeout_hours` | Optional positive integer in hours, at most 336 hours (14 days). Maximum time the run may wait for compute before it is failed. Omit it and the SDK leaves it out of the request entirely, so the server applies its own default of 24 hours. |
| `requirements` | Optional list of Python package requirement strings, such as `["pandas>=2.0", "rasterio==1.3.10"]`. Requirements are validated before submission. |

The remote platform may reject compute types that are not enabled for your workspace. Start with the smallest machine that matches the memory or GPU profile of the task, then scale up only when the logs or runtime behavior show that the run needs it.

Per-run configuration is passed to `.submit(...)` with `RunConfig`:

| Config field | Description |
| - | - |
| `name` | Optional run label used for exact-match filtering with `list_runs(name=...)`. |

Run names are optional, can be up to 63 characters, and must match `^[a-zA-Z0-9]([-a-zA-Z0-9_.]*[a-zA-Z0-9])?$`. Use them for stable labels such as `site-buffer-summary`, `nightly-index`, or `experiment-1`.

Because `.submit(..., config=RunConfig(...))` reserves the `config` keyword for SDK configuration, a function decorated with `@run` cannot define a parameter named `config`.

## Step 4: Reconnect to Existing Runs

Use `load_run(...)` when you already have a run ID from a previous cell, browser refresh, or shared notebook note.

```python theme={null}
from nika_py import load_run

run = load_run("nr--20260612143005-6d9e736b188d47fc")

print(run.status())
print(run.logs(tail=100))
```

If you are working from the decorated function object, use `.load(...)` to reuse the same client configuration:

```python theme={null}
run = build_buffer_summary.load("nr--20260612143005-6d9e736b188d47fc")
print(run.status())
```

Use `list_runs(...)` to retrieve one page of runs visible from the notebook. The returned `RunPage` contains `runs` and `next_cursor`.

```python theme={null}
from nika_py import list_runs

page = list_runs(status="running", limit=20)
for run in page.runs:
    print(run.run_id, run.status())

while page.next_cursor is not None:
    page = list_runs(status="running", limit=20, cursor=page.next_cursor)
    for run in page.runs:
        print(run.run_id, run.status())
```

Allowed status filters are `pending`, `initializing`, `running`, `cancelling`, `succeeded`, `failed`, and `cancelled`. The `name` filter is an exact match on the run name, `limit` must be between `1` and `200`, and `cursor` should only be set from a previous page's `next_cursor`.

You can also filter child runs client-side with `parent_run_id`:

```python theme={null}
children_page = list_runs(parent_run_id=run.run_id)
for child in children_page.runs:
    print(child.run_id, child.parent_run_id, child.status())
```

## Step 5: Track Child Runs

When code inside a delegated run submits more work, the SDK can link the nested submission back to the run that started it. Notebook submissions do not set a parent and remain root runs.

Every returned `RunHandle` exposes `parent_run_id`, which is `None` for root runs. Handles returned from `load_run(...)` and `list_runs(...)` also carry snapshot metadata when the gateway provides it, including `name`, `machine_type`, `run_timeout_hours`, `queue_timeout_hours`, `last_status`, `created_at`, `started_at`, and `finished_at`. `list_runs(parent_run_id=...)` retrieves one page of recent runs and filters that page locally.

You can use handle helpers when you are navigating a run tree:

```python theme={null}
children = run.children(status="running", limit=20)

for child in children:
    print(child.run_id, child.parent_run_id)

parent = children[0].parent() if children else None
```

## Step 6: Cancel a Running Run

If a delegated run is no longer needed, call `cancel()` on its handle.

```python theme={null}
cancellation = run.cancel()
print(cancellation.last_status)

await cancellation
```

Cancellation is asynchronous. Calling `run.cancel()` sends the cancellation request immediately and returns a `RunCancellation` object. The object exposes `last_status` and `done`; when awaited, it polls until the backend reports `cancelled`. If the run reaches `succeeded` or `failed` before cancellation completes, awaiting the cancellation raises `RemoteRunError`.

## How Delegation Works

When you call `.submit(...)`, the SDK builds an invocation envelope and submits it to NIKA cloud compute:

1. The decorated function is converted into a function bundle.
2. Positional and keyword arguments are serialized with `cloudpickle`.
3. Runtime options are attached as `compute` and `run_timeout_hours` (always sent, `1` when you don't set it), plus optional `queue_timeout_hours`, optional `requirements`, and optional per-run `name` from `RunConfig`.
4. If the submitting process is already inside a delegated run, the SDK includes parent-run metadata.
5. NIKA returns `run_id`, and the remote runner starts an isolated worker, executes the function, stores logs, and makes the result available to the handle. New runs use the `nr--...` run ID format, while older `nr-<32 hex>` IDs remain valid for loading, status checks, logs, results, cancellation, and parent-run metadata.

The status lifecycle is `pending` → `initializing` → `running`, then one of `succeeded`, `failed`, or `cancelled`. A short-lived `cancelling` status appears after `run.cancel()` while the operator tears down the worker. Unknown future statuses are treated defensively as running by the SDK.

When a result is ready, the runner can return either an inline pickled `result` payload or a `result_url`. For large or stored results, the SDK fetches the signed `result_url`, decodes the `cloudpickle` bytes, and returns the Python object from `run.result()` or `run.wait(...)`.

The SDK uses two bundling strategies:

| Bundle kind | When it is used | Operational impact |
| - | - | - |
| `module_ref` | The function lives in an importable Python module. | The envelope contains the module name, qualified function name, source hash, runtime metadata, and arguments. This is the more reproducible path because the worker imports code from an installed package or image. |
| `cloudpickle` | The function is defined in a notebook cell, `__main__`, a REPL, or a nested scope. | The function object is serialized with `cloudpickle`, including referenced globals and closure variables. This is the normal notebook experience, but it depends on compatible Python and cloudpickle versions between the notebook and worker. |

Most cloud notebook usage will use `cloudpickle` because functions are usually defined in notebook cells. Keep those functions focused: pass large datasets by path or ID, not by capturing a large dataframe in a closure.

## Serialization Guidelines

Delegated functions should have clear boundaries. The SDK can serialize ordinary Python values, but remote execution is more reliable when the function receives references to data instead of live objects from the notebook session.

Prefer:

* Strings, numbers, booleans, lists, dictionaries, and dataclasses
* Workspace file paths such as `/workspace/data/input.geojson`
* Dataset IDs, table names, object storage URLs, or other managed references
* Return values that are small enough to serialize comfortably
* Output files written to explicit workspace paths

Avoid capturing:

* Open file handles
* Database connections
* Sockets or clients with active network state
* GPU tensors or model objects already loaded in notebook memory
* Large pandas or GeoPandas dataframes in closure variables
* Secrets embedded in source code or closures

If a result is large, write it to a workspace file and return metadata:

```python theme={null}
return {
    "status": "ok",
    "output_path": output_path,
    "feature_count": int(len(buffered)),
}
```

## Troubleshooting

### `AuthenticationError` or `ConfigurationError`

The SDK cannot use the notebook's cloud delegation context. Make sure the code is running inside a cloud NIKA notebook. Local Python processes are not a supported delegation environment at the moment.

### `RunNotCompleteError`

The run has not reached a terminal state yet. Check `run.status()` and `run.logs(tail=200)`, or use:

```python theme={null}
result = run.wait(timeout=3600, poll_interval=5)
```

### Remote Dependency Errors

Add the missing package to `requirements` and pin versions when reproducibility matters.

```python theme={null}
@run(
    compute="CPUx7",
    run_timeout_hours=2,
    requirements=["rasterio==1.3.10", "geopandas>=0.14"],
)
def process_raster(path: str) -> dict[str, object]:
    ...
```

### Cloudpickle Runtime Mismatch

Notebook-defined functions are serialized as Python code objects. If the worker uses a different Python minor version than the notebook kernel, unpickling can fail. Use the cloud notebook runtime selected by NIKA, keep functions simple, or move production code into an importable module so the SDK can use `module_ref`.

## Best Practices

* Test the function locally in the notebook with `.local(...)` before submitting.
* Keep delegated functions deterministic: pass every input explicitly and write outputs to known paths.
* Pin critical dependencies in `requirements`.
* Use `logs(tail=...)` for progress reporting instead of returning large debug payloads.
* Return compact metadata and store large outputs as files.
* Use `load_run(...)` to reconnect instead of re-submitting the same expensive run.
* Treat notebook `cloudpickle` delegation as an exploratory workflow; move stable production routines into importable modules when they need stronger reproducibility.
* Do not place credentials, private endpoints, or long-lived secrets in function closures. Pass secret references or managed paths instead.

## Next Steps

Now that you can delegate Python functions to cloud compute:

1. Learn how to [run code in NIKA notebooks](/guides/data-analysis/run-code-in-notebook)
2. Review [supported Python libraries](/guides/data-analysis/supported-python-libraries)
3. Use [custom geoprocess deployment](/guides/custom-geoprocess-deployment/step-by-step) when you need a versioned worker available from GIS tools


# Your Second Worker: AI-assisted
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/ai-coder-worker

Use AI coding assistants to create, configure, and iterate on GeoEngine workers with sample prompts

Instead of manually editing configuration files, you can use AI coding assistants to create and modify GeoEngine workers from natural language prompts. This page provides ready-to-use prompts for popular AI coder tools.

Follow the [manual steps](/guides/custom-geoprocess-deployment/step-by-step) first to understand the flow before trying the AI agent route.

***

## Prerequisites

* GeoEngine is [installed and logged in](/guides/custom-geoprocess-deployment/installation)
* Docker is running
* An AI coding assistant of your choice (see supported tools below)

### Supported AI Coder Tools

| Tool | Provider | How to Use |
| - | - | - |
| [Claude Code](https://claude.ai/code) (recommended) | Anthropic | Run from terminal in your script directory |
| [Cursor](https://cursor.com) | Cursor | Open your script folder as a project |
| [GitHub Copilot](https://github.com/features/copilot) | GitHub / OpenAI | Use in VS Code, JetBrains, or CLI |
| [Codex](https://openai.com/codex/) | OpenAI | Run from terminal in your script directory |
| [Antigravity IDE](https://antigravity.google) | Google | Open your script folder as workspace |
| NIKA local agent tooling | Nika | Use inside your local NIKA workspace |

<Tip>
  If you have yet to install the skills, follow [Installation & Setup](/guides/custom-geoprocess-deployment/installation#step-3-initialise-ai-agent-skills-optional) to get the skills into your agent.
</Tip>

***

## GeoEngine AI Agent Skills

GeoEngine ships with a built-in **AI agent skill** that gives your AI coder structured knowledge of the GeoEngine workflow. If you ran `geoengine setup skills` during [installation](/guides/custom-geoprocess-deployment/installation#step-3-initialise-ai-agent-skills-optional), the following top-level skill is available to your agent:

| Skill | Description |
| - | - |
| `use-geoengine` | Master routing skill that handles GeoEngine requests and loads the right internal workflow, module, reference, or CLI command guide. |

Inside `use-geoengine`, the agent can load focused resources only when needed:

| Internal resource | What it helps with |
| - | - |
| `workflows/new-worker.md` | End-to-end worker creation: init, script/config/test edits, lint, dev apply, tests, and final apply. |
| `modules/argparse.md` | Adding or repairing Python `argparse` and R `optparse` inputs so GeoEngine can pass `--name value` flags. |
| `modules/geoengine-yaml.md` | Writing or updating the `geoengine.yaml` worker contract. |
| `modules/pixi-toml.md` | Choosing extra conda-forge dependencies for `pixi.toml`. |
| `modules/test-cases.md` | Creating or updating `tests/geoengine.test.yaml` with stable worker tests. |
| `references/` | Detailed command, YAML, dependency, test, image, cloud, and maintenance guidance. |

<Tip>
  With this skill installed, even short prompts like "Make this script a GeoEngine worker" can trigger the full automated workflow.
</Tip>

***

<div />

## Step 1: Download the Starter Script

<a href="https://github.com/NikaGeospatial/geoengine/releases/download/docs-downloads/sg_pgpt_gen.R">Download the starter script</a> and save it in an isolated folder somewhere on your machine — your home directory or Desktop works fine.

<Tabs>
  <Tab title="macOS">
    For this example, we will assume you created a directory in `/Users/<user>/Downloads/sg-pgpt-gen`. Place the script into this directory.
  </Tab>

  <Tab title="Windows">
    For this example, we will assume you created a directory in `C:/Users/<user>/Downloads/sg-pgpt-gen`. Place the script into this directory.
  </Tab>

  <Tab title="Linux">
    For this example, we will assume you created a directory in `/home/<user>/Downloads/sg-pgpt-gen`. Place the script into this directory.
  </Tab>
</Tabs>

***

## Step 2: Point the Agent to the Directory

Allow your AI coder access to the directory that contains your script:

* **Claude Code / Codex** — select the script's directory as the workspace
* **Cursor / GitHub Copilot** — open the script's directory as a project in the IDE
* **Antigravity** — open the script's directory as the workspace in the IDE

The AI coder needs to be able to read and write files in that directory to create and edit `geoengine.yaml`, `pixi.toml`, and your script.

***

## Step 3: Creating the Worker

Describe your script, its inputs, and its outputs as much as possible. The AI coder will handle the rest — initialising the worker, writing the config files, and building the container.

### Prompt Template

```text theme={null}
I have a(n) [Python/R] script called [script-name] in this directory that [describe what the script does].

Make it a GeoEngine worker called [worker-name] with these inputs and outputs:

Inputs:
- [name]: [type] — [description]
- [name]: [type] — [description]

Outputs:
- [name]: [type] — [description]

[Optional: Mention whether you plan to run it from QGIS or ArcGIS Pro.]
```

Available input/output types: `file`, `folder`, `string`, `number`, `boolean`, `enum`, `datetime`.

### Prompt to Use

Based on the template, you can use the following prompt in your agent.

```text theme={null}
I have an R script called sg_pgpt_gen.R in this directory that generates polygons and points within Singapore.

Make it a GeoEngine worker called sg-pgpt-gen with these inputs and outputs:

Inputs:
- n-polygons: number - number of polygons to generate
- n-points: number - number of points to generate
- min-sides: number - minimum number of sides per polygon
- max-sides: number - maximum number of sides per polygon
- seed: number - seed for reproducibility

Outputs:
- output-folder: folder — directory where the generated GeoJSON file will be saved
```

Add one more line at the end if you plan to run the worker from QGIS or ArcGIS Pro. The agent can remind you to run `geoengine setup plugins`, but individual workers no longer need per-worker plugin flags in `geoengine.yaml`.

After the agent is done, ensure the following:

* The directory contains all the necessary artifacts.
* `tests/geoengine.test.yaml` exists and contains at least one realistic test case.
* `geoengine lint`, `geoengine apply --dev`, and `geoengine test` pass.
* Running `geoengine workers` shows the worker "sg-pgpt-gen".

***

## Step 4: Verifying in GIS Platform

You can now test your worker following the [steps outlined](/guides/custom-geoprocess-deployment/step-by-step#step-8-gis-testing) in the guide. The AI agent
should have done a developmental apply, so you will only find the worker with a "latest" version.

***

## Step 5: Saving a Worker Version

When you are happy with the worker, run a production apply so that the stable version of the script is saved. Run the following in a terminal that is opened to your worker directory.

```bash theme={null}
geoengine lint
geoengine test
geoengine apply
```

With this, the worker should now have `v1.0.0` applied and readily available for you to use.

***

## Step 6: Improving the Worker

Sometimes, you might want to improve on the script. With the help of the AI agent, you can just describe what you want to change.
The AI coder will update the script, config files, and dependencies as needed.

### Prompt Template

```text theme={null}
I have an existing GeoEngine worker in this directory.
[Describe the change you want to make.]
```

### Example

Using the same worker, let's say that we want to manually specify the bounding box rather than using an automatic bounding box approximation of Singapore.
Use the following prompt to improve on the worker.

```text theme={null}
I have an existing GeoEngine worker in this directory.
Make the worker take in a parameter of a GeoJSON file that acts as the bounding box, instead of using the hard-coded bounding box.
```

When the AI is done, run `geoengine test` again and then test the "latest" version of the worker in your GIS plugin. Once you are happy with it, feel free to follow
[these steps](/guides/custom-geoprocess-deployment/step-by-step#step-10-push-to-the-cloud) to push the next version to the cloud.

<Tip>
  Remember to bump the version number before your next `geoengine apply`!
</Tip>

***

## Debugging with AI Coder

Here are some prompt templates you can use to debug with your AI coding agent.

### Prompt: Fix a Build Failure

```
My GeoEngine worker failed to build. Here is the error output:

[paste the error output from geoengine apply]

Please diagnose the issue and fix it. Common causes include missing dependencies in pixi.toml, incorrect pixi.toml syntax, or script import errors. After fixing it, run `geoengine lint`, `geoengine apply --dev`, and `geoengine test`.
```

### Prompt: Fix a Runtime Error

```
My GeoEngine worker builds successfully but fails when I run it. Here is the error:

[paste the error output from geoengine run or the GIS log panel]

Please diagnose and fix the issue. Then run `geoengine lint`, `geoengine apply --dev`, and `geoengine test`.
```

### Prompt: Inspect and Explain a Worker

```
Explain what this GeoEngine worker does. Read the geoengine.yaml, pixi.toml, and the main script in this directory and give me a summary of:
- What inputs it accepts
- What it does with them
- What outputs it produces
- What dependencies it needs
```

***

## Tips for Best Results

* **Be specific about inputs and outputs** — mention file types (`.tif`, `.geojson`, `.csv`), whether inputs are read-only or writable outputs, and any optional parameters so the AI sets up `geoengine.yaml` correctly
* **Bounce with the agent** — AI agents are not perfect. It is unlikely that the agent will succeed on first try. Paste error logs into the prompt to get the agent to fix, before trying again
* **Iterate with `--dev`** — always use `geoengine apply --dev` during development to skip version checks; run `geoengine apply` (without `--dev`) when ready for a production release
* **Ask for tests** — have the agent create or update `tests/geoengine.test.yaml`, then keep `geoengine test` in the development loop
* **Review generated files** — check that `geoengine.yaml` inputs match your script's argparse arguments
* **Mention GIS plugins** — if you need QGIS or ArcGIS Pro support, include that in your prompt (e.g. "enable this for QGIS")


# CLI Reference
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/cli-reference

Complete reference for all GeoEngine CLI commands, flags, and options

All GeoEngine commands follow the form `geoengine <command> [options]`. Run any command with `--help` to see its usage inline.

***

## Global Options

These options are accepted by most GeoEngine commands unless a command documents more specific behavior.

| Flag | Description |
| - | - |
| `-v`, `--verbose` | Show more detailed command output on commands that expose the global verbose flag. |
| `-y`, `--yes` | Accept confirmation prompts and defaults non-interactively. Useful for setup, init, apply, delete, and push workflows. |

For `geoengine test`, use the command-specific long flag `geoengine test --verbose` to show container logs for every case.

***

## Authentication

### `geoengine auth login`

Sign in to GeoEngine with your Nika account. Credentials are stored securely on your machine and persist across sessions. Required before worker build, run, registry, and cloud commands. Setup, lint, patch, update, uninstall, and auth commands can run without an active login.

```bash theme={null}
geoengine auth login
```

### `geoengine auth logout`

Sign out and remove stored credentials.

```bash theme={null}
geoengine auth logout
```

### `geoengine auth status`

Reads logged in user's details.

```bash theme={null}
geoengine auth status
```

***

## Worker Setup

### `geoengine init`

Create a new `geoengine.yaml` and `pixi.toml` template in the current directory. It also creates `geoengine.lock`, ensures `.dockerignore` exists, and can scaffold `tests/` and `README.md`. Normal Python/R workers get their generated `Dockerfile` during `geoengine apply`; CUDA init may write a CUDA runtime marker Dockerfile earlier.

```bash theme={null}
geoengine init [-n|--name <worker>] [-e|--env py|r|py-cuda|r-cuda] [-y|--yes]
```

| Flag | Description |
| - | - |
| `-n`, `--name <worker>` | Worker name. Defaults to the current directory name if omitted. |
| `-e`, `--env py` | Generate a Python environment template (default). |
| `-e`, `--env r` | Generate an R environment template. |
| `-e`, `--env py-cuda\|r-cuda` | Generate the environment template for CUDA runtime variants. |
| `-y`, `--yes` | Overwrite existing templates when prompted and create the optional `tests/` and `README.md` scaffolds. |

***

### `geoengine apply`

Register the worker, save the current config, reconcile the Dockerfile, build the Docker image, and refresh GIS plugin discovery state.

```bash theme={null}
geoengine apply [<worker>] [--dev] [--no-cache] [--build-arg KEY=VALUE]
```

| Flag | Description |
| - | - |
| `<worker>` | Worker directory path. Defaults to the worker in the current directory. |
| `--dev` | Skip semantic version validation and update the mutable `latest` image/config only. |
| `--no-cache` | Force a full Docker rebuild, bypassing the layer cache. |
| `--build-arg KEY=VALUE` | Pass a custom Docker build argument into the image build. |

**What apply does:**

1. Runs the same semantic checks as `geoengine lint`
2. Reconciles `pixi.toml` and the Dockerfile with the current runtime image
3. Builds the Docker image (skipped automatically if config and image are unchanged)
4. Registers the worker if new
5. Saves the current config snapshot and updates `latest`
6. For production applies, records the selected `local_tag` so it can be run, tested, deleted, or pushed later

See [Your First Worker: Step-by-Step](/guides/custom-geoprocess-deployment/step-by-step) and [Versioning Workers](/guides/custom-geoprocess-deployment/versioning) for full details.

***

### `geoengine lint`

Validate the current directory's `geoengine.yaml` before applying.

```bash theme={null}
geoengine lint
```

`geoengine apply` runs this check internally and rejects lint errors. Running `geoengine lint` first gives you the full error list up front. Warnings, such as deprecated fields, do not block apply.

***

## Running Workers

### `geoengine run`

Execute a worker in a Docker container. File and folder inputs are auto-mounted, and local run history is recorded by default.

```bash theme={null}
geoengine run [<worker-id>] --actor <NAME> [-i|--input KEY=VALUE ...] [--json] [--tag <tag>] [--no-history] [-- <extra args>]
```

| Flag | Description |
| - | - |
| `<worker-id>` | Worker UUID. Defaults to the worker in the current directory via `geoengine.lock`. |
| `--actor <NAME>` | Required source label for the run. This is an open string, not an enum. GeoEngine trims whitespace and rejects empty values. |
| `-i`, `--input KEY=VALUE` | Pass an input to the worker. Repeat for multiple inputs. File/folder paths are auto-mounted into the container. |
| `--json` | Structured output mode: container logs go to stderr, a JSON result is printed to stdout on completion. |
| `--tag <tag>` | Run a specific previously-built local tag using its snapshotted config. Defaults to `latest`. |
| `--no-history` | Do not persist this run in local history. Use for sensitive, ephemeral, or wrapper-managed runs. |
| `-- <extra args>` | Pass additional arguments directly to the container command (after the trailing `--`). |

Recommended actor values include `CLI`, `QGIS`, `ArcGIS Pro`, `NIKA`, or a properly capitalized agent/app name such as `Codex` or `Field Review App`. Agents and app wrappers should invoke runs as `--actor "<Agent Name>"` using proper capitalization.

```bash theme={null}
geoengine run --actor CLI --input input-file=/path/to/file.tif
geoengine run <worker-id> --actor QGIS --json --input key=value
geoengine run <worker-id> --actor "ArcGIS Pro" --json --input key=value
```

**Input mounting:**

* `file` inputs are mounted at `/inputs/<key>/<filename>`
* `folder` inputs are mounted at `/mnt/input_<key>/`
* Non-path values are passed through as plain string arguments

**JSON result format (with `--json`):**

```json theme={null}
{
  "job_id": "01HX4V2Z9B2F4T8H6P9K3N7Q1M",
  "status": "completed",
  "exit_code": 0,
  "files": [
    { "name": "output.geojson", "path": "/path/on/host", "size": 1024, "kind": "output" }
  ]
}
```

**Local run history:**

By default, every run is recorded under:

```text theme={null}
~/.geoengine/runs/<worker_id>/<job_id>/
```

Each run directory includes:

* `record.json` — structured metadata for the run
* `logs.ndjson.gz` — compressed streamed stdout/stderr log events

`record.json` stores the job ID, worker ID/name, actor, local/requested tag, image tag, start/end time, duration, status, exit code, error, command, inputs, extra args, output files, and log stats. Older records created before actor stamping may show `actor` as `Unknown`.

GeoEngine keeps the latest 200 runs per worker and keeps total local history under 1 GiB by default. The current run is always preserved even if it exceeds the cap. History write and prune failures are warnings; they do not fail the worker run.

***

## Frontend Wrapper Integration

To run a worker from a frontend wrapper, invoke the CLI with a clear actor label and JSON output:

```bash theme={null}
geoengine run <worker-id> --actor "<Wrapper Name>" --json --input key=value
```

Parse stdout as JSON for the structured run result, and treat stderr as live logs/progress. The JSON result includes `job_id`; use it to fetch run details or logs later.

To show recent runs:

```bash theme={null}
geoengine worker runs list --json --limit 50
```

To filter by worker:

```bash theme={null}
geoengine worker runs list --worker <worker-id> --json
```

To fetch one run:

```bash theme={null}
geoengine worker runs show <job-id> --json
```

To fetch logs:

```bash theme={null}
geoengine worker runs logs <job-id> --stream all
geoengine worker runs logs <job-id> --stream stderr --tail 100
```

To prune from UI/admin controls:

```bash theme={null}
geoengine worker runs prune --keep 200 --max-size-mb 1024 --json
```

***

## Publishing Workers

### `geoengine push`

Publish a previously-applied production worker image to the cloud registry, making it available for team members to run via the QGIS or ArcGIS Pro plugin without a local setup.

```bash theme={null}
geoengine push [--id <worker-id>] [--tag <local-tag>] [--tenant <tenant>]
```

| Flag | Description |
| - | - |
| `--id <worker-id>` | Worker UUID to push. Defaults to the worker in the current directory via `geoengine.lock`. |
| `--tag <local-tag>` | Local tag to push. Defaults to the most recently applied production `local_tag`. |
| `--tenant <tenant>` | Tenant to publish under. Defaults to your owned tenant. |

Requires a prior **production** `geoengine apply` (without `--dev`). See [Cloud Push](/guides/custom-geoprocess-deployment/cloud-push) for the full workflow.

***

## Inspecting Workers

### `geoengine workers`

List all registered workers.

```bash theme={null}
geoengine workers [--all] [--json]
```

| Flag | Description |
| - | - |
| `--all` | Expand all version sub-rows inline below each worker. |
| `--json` | Output as JSON (includes `id`, `name`, `has_tool`, `description`). |

**Output columns (default):** `ID`, `NAME`, `LATEST TAG`, `LAST APPLIED`

* **LATEST TAG** — most recently applied local tag plus the total number of applied tags, e.g. `claude-1.0.0 (3)`
* **LAST APPLIED** — relative time since last apply (e.g. `3 min 42 s ago`)

With `--all`, the column header changes to `TAG` — expanding each worker with sub-rows for every applied tag.

***

### `geoengine describe`

Show detailed information about a specific worker.

```bash theme={null}
geoengine describe [<worker-id>] [--tag <tag>] [--json]
```

| Flag | Description |
| - | - |
| `<worker-id>` | Worker UUID. Defaults to the worker in the current directory via `geoengine.lock`. |
| `--tag <tag>` | Show info for a specific applied tag snapshot instead of the latest. |
| `--json` | Output as JSON (includes `name`, `description`, `version`, `inputs`, `applied_at`, `applied_tags`, `config_hash`, `plugins_qgis`, `plugins_arcgis`). |

***

### `geoengine worker runs`

List, inspect, stream, and prune local run history. Running `geoengine worker runs` without a subcommand lists recent runs.

```bash theme={null}
geoengine worker runs
geoengine worker runs list [--worker <id>] [--limit N] [--json]
geoengine worker runs show <job-id> [--json]
geoengine worker runs logs <job-id> [--stream stdout|stderr|all] [--tail N]
geoengine worker runs prune [--worker <id>] [--keep N] [--max-size-mb M] [--json]
```

| Command | Description |
| - | - |
| `geoengine worker runs` | List recent runs using the default list view. |
| `geoengine worker runs list` | List recent runs. Use `--worker <id>` to filter, `--limit N` to change the count, and `--json` for structured output. |
| `geoengine worker runs show <job-id>` | Show the saved `record.json` metadata for one run. |
| `geoengine worker runs logs <job-id>` | Print saved logs. Use `--stream stdout`, `--stream stderr`, or `--stream all`; use `--tail N` to return only the last N log events. |
| `geoengine worker runs prune` | Prune local history. Use `--worker <id>` to prune one worker, `--keep N` to keep a run count, `--max-size-mb M` to cap total size, and `--json` for a structured summary. |

Existing `geoengine workers` and `geoengine describe` remain unchanged for now, though they may later move under `geoengine worker list` and `geoengine worker describe`.

***

### `geoengine diff`

Check which tracked files have changed since the last apply.

```bash theme={null}
geoengine diff
```

Checks `geoengine.yaml`, the Dockerfile, and build-relevant worker directory files against the last apply.

***

## Managing Workers

### `geoengine delete`

Delete a worker or a specific local tag.

```bash theme={null}
geoengine delete [--id <worker-id>] [--tag <tag>]
```

| Flag | Description |
| - | - |
| `--id <worker-id>` | Worker UUID to delete. Defaults to the worker in the current directory via `geoengine.lock`. |
| `--tag <tag>` | Delete only this local tag (removes its Docker image, map entry, and config snapshot). Omit to delete the entire worker. |

Running without `--tag` shows a confirmation prompt before deleting the worker's registration, all saved configs, and all state.

***

## Image Management

### `geoengine image list`

List all GeoEngine-managed Docker images.

```bash theme={null}
geoengine image list [--filter <name>] [--all]
```

| Flag | Description |
| - | - |
| `-f`, `--filter <name>` | Filter images by image name. |
| `-a`, `--all` | Include intermediate layers. |

### `geoengine image import`

Import a Docker image from a tarball (useful for air-gapped environments).

```bash theme={null}
geoengine image import <file.tar> [--tag <name:tag>]
```

| Flag | Description |
| - | - |
| `-t`, `--tag <name:tag>` | Apply a tag to the imported image. Optional. |

### `geoengine image remove`

Remove a Docker image and its associated version entry and config snapshot.

```bash theme={null}
geoengine image remove <image:tag> [--force]
```

| Flag | Description |
| - | - |
| `-f`, `--force` | Force removal even if containers are using the image. |

***

## Environment Variables

Global environment variables are injected into every worker container at runtime.

### `geoengine env set`

Set one or more global environment variables.

```bash theme={null}
geoengine env set KEY=value
geoengine env set KEY="value with spaces"
geoengine env set KEY1=val1 KEY2=val2
geoengine env set -f path/to/.env   # Load from a .env file
```

Inline variables override file variables if both are provided in the same command.

### `geoengine env unset`

Remove one or more global environment variables.

```bash theme={null}
geoengine env unset KEY
geoengine env unset KEY1 KEY2
```

### `geoengine env list`

List all currently set global environment variables.

```bash theme={null}
geoengine env list
```

### `geoengine env show`

Show the value of a single global environment variable.

```bash theme={null}
geoengine env show KEY
```

***

## Worker Tests

### `geoengine test`

Run declarative tests from `tests/geoengine.test.yaml`.

```bash theme={null}
geoengine test [<worker>] [--case <name>] [--tag <tag>] [--json] [--keep-workdir] [--verbose]
```

| Flag | Description |
| - | - |
| `<worker>` | Worker directory path or worker UUID. Defaults to the current directory's worker. |
| `--case <name>` | Run one named test case. |
| `--tag <tag>` | Test a specific previously applied local tag. |
| `--json` | Output the test report as JSON. |
| `--keep-workdir` | Keep `.geoengine-test/` case folders for inspection. |
| `--verbose` | Show container logs for every test, not only failures. |

Read-only fixture paths are resolved relative to `tests/`. Output file/folder inputs are resolved inside `.geoengine-test/<case>/`. See [Designing Worker Tests](/guides/custom-geoprocess-deployment/test-designing) for the manifest schema and examples.

***

## Maintenance & Updates

### `geoengine setup`

Initial installation for GeoEngine add-ons. Includes skills and GIS plugins.

```bash theme={null}
geoengine setup skills [--agent <name>]
geoengine setup plugins [--qgis] [--arcgis] [--all]
```

| Command | Description |
| - | - |
| `geoengine setup skills` | Install GeoEngine skills for one or more supported AI agents. |
| `geoengine setup skills --agent Codex` | Install skills for one named agent. Supported names include `Claude`, `Codex`, `Antigravity`, `Cursor`, `Copilot`, and `NIKA`. |
| `geoengine setup plugins --qgis` | Install the QGIS plugin. |
| `geoengine setup plugins --arcgis` | Install the ArcGIS Pro toolbox. Windows only. |
| `geoengine setup plugins --all` | Install all platform-supported GIS plugins. |

### `geoengine patch`

Validate all GeoEngine artifacts and repair anything that is broken or out of date. Safe to run at any time; exits with a non-zero status if issues are found.

```bash theme={null}
geoengine patch
```

Run this after upgrading GeoEngine to sync workers, GIS plugins, and agent skills with the new binary.

`geoengine patch --init` remains as a deprecated compatibility alias for `geoengine setup skills`.

### `geoengine update`

Update GeoEngine to the latest version using the original install method (Homebrew, curl, or PowerShell), then automatically run `geoengine patch`.

```bash theme={null}
geoengine update
```

### `geoengine uninstall`

Remove the GeoEngine binary and GeoEngine files.

```bash theme={null}
geoengine uninstall
```

***

## Quick Reference

| Command | Description |
| - | - |
| `geoengine auth login\|logout\|status` | Authentication-related commands, to login, logout, and see user details |
| `geoengine init [--name] [--env py\|r\|py-cuda\|r-cuda]` | Create GeoEngine worker templates and optional test scaffolds |
| `geoengine apply [--dev] [--no-cache] [--build-arg K=V]` | Register the worker, save config, and build/update the image |
| `geoengine lint` | Validate `geoengine.yaml` semantic rules |
| `geoengine test [--case C] [--tag T] [--json] [--keep-workdir] [--verbose]` | Run worker test cases |
| `geoengine push [--id <id>] [--tag T] [--tenant T]` | Publish a production image to the cloud registry |
| `geoengine run [<worker-id>] --actor <name> --input K=V [--json] [--tag T] [--no-history]` | Run a worker in a container and record local history |
| `geoengine diff` | Check tracked file changes since last apply |
| `geoengine workers [--all] [--json]` | List registered workers |
| `geoengine describe [<worker-id>] [--tag T] [--json]` | Show worker details and config hash |
| `geoengine worker runs list\|show\|logs\|prune` | Inspect and manage local run history |
| `geoengine delete [--id <worker-id>] [--tag T]` | Delete a worker or a single tag |
| `geoengine image list\|import\|remove` | Manage Docker images |
| `geoengine env set\|unset\|list\|show` | Manage global environment variables |
| `geoengine setup skills\|plugins` | Install local agent skills or GIS plugins |
| `geoengine patch` | Repair artifacts and sync plugins/agent skills |
| `geoengine update` | Update to latest version, then run patch |
| `geoengine uninstall` | Remove GeoEngine binary and data |


# Cloud Push
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/cloud-push

Push your GeoEngine worker to the cloud so your whole team can run it without a local setup

`geoengine push` publishes a previously-applied production worker image to Nika's cloud registry. Once pushed, team members can run the worker directly from their QGIS or ArcGIS Pro plugin — without needing Docker, a terminal, or a local GeoEngine setup.

***

## Prerequisites

* GeoEngine installed and authenticated (`geoengine auth login`)
* A production apply completed: `geoengine apply` (without `--dev`) — dev builds cannot be pushed
* Recommended: local checks pass with `geoengine lint` and `geoengine test`

***

## Workflow

### Step 1: Apply in Production Mode

From your worker directory, bump the version in `geoengine.yaml` if needed, then run the local checks:

```bash theme={null}
geoengine lint
geoengine test
```

Then run a production apply:

```bash theme={null}
geoengine apply
```

This builds a versioned image and saves a config snapshot. Dev builds (`--dev`) are not eligible for push.

### Step 2: Push to the Cloud

```bash theme={null}
geoengine push [--id <worker-id>] [--tag <local-tag>] [--tenant <tenant>]
```

| Flag | Description |
| - | - |
| `--id <worker-id>` | Worker UUID to push. Defaults to the worker in the current directory via `geoengine.lock`. |
| `--tag <local-tag>` | Local tag to push. Defaults to the most recently applied production `local_tag`. |
| `--tenant <tenant>` | Tenant to publish under. Defaults to your owned tenant, or prompts when more than one tenant is available. |

Run from your worker directory without any flags to push the latest production version:

```bash theme={null}
geoengine push
```

GeoEngine confirms the local tag and semantic version, uploads the container image to the cloud registry, and registers it in the selected workspace.

### Step 3: Available to Your Team

After a successful push, team members will see the worker in their QGIS or ArcGIS Pro GeoEngine plugin and can run it through the cloud without installing anything locally.

***

## Notes

* Only production images (from `geoengine apply` without `--dev`) can be pushed. If you've only run `geoengine apply --dev`, run `geoengine apply` first.
* If `local_tag` is not set in `geoengine.yaml`, production apply prompts to use the semantic `version` as the local tag.
* If you have access to multiple tenants, use `--tenant` to target a specific one.
* Use `geoengine workers` to see the current applied tag for each worker (`LATEST TAG` column).


# Debug & Troubleshoot
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/debugging

Diagnose worker issues using GeoEngine's CLI inspection commands and log output

GeoEngine provides a set of CLI commands to inspect workers, read container logs, and repair broken state. This guide covers the most common debugging scenarios.

***

## Check What Has Changed

Before re-applying a worker, use `geoengine diff` to see which tracked files have changed since the last apply:

```bash theme={null}
# Check tracked files: geoengine.yaml, Dockerfile, and build-relevant worker files
geoengine diff
```

This is useful for confirming which changes will be picked up when you run `geoengine apply` next.

***

## Inspect Registered Workers

List all registered workers and their current status:

```bash theme={null}
# Summary view
geoengine workers

# Expanded view — shows all versions as sub-rows beneath each worker
geoengine workers --all
```

The output table includes the following columns:

| Column | Description |
| - | - |
| **ID** | Worker UUID used by the CLI and Docker tags |
| **NAME** | Worker name |
| **LATEST TAG** | Most recently applied local tag plus the total number of applied tags, e.g. `claude-1.0.0 (3)` |
| **LAST APPLIED** | Relative time since last apply (e.g. `3 min 42 s ago`) |

If a worker is missing from this list after `geoengine apply`, run `geoengine patch` to repair the worker registry (see below).

***

## Inspect a Specific Worker

Get detailed information about a single worker:

```bash theme={null}
# Show the latest applied version, config hash, and available versions list
geoengine describe

# Show info for a specific previously-built tag
geoengine describe --tag claude-1.0.0
```

The output includes:

* **Name and description**
* **Version** and **applied at** timestamp
* **Config hash** — a SHA-256 of the applied config; useful to confirm two builds used the same configuration
* **Applied tags** — all local tags currently on disk for this worker
* **Runtime image** — the base runtime image used when the tag was applied, when available

***

## Read Container Logs

Container logs stream to **stderr** automatically when you run a worker. To separate logs from the structured result, use `--json` mode:

```bash theme={null}
geoengine run --actor CLI --json --input input-file=/path/to/file.tif
```

* **stderr** — container log output, streamed in real time
* **stdout** — the final JSON result, printed on completion:

```json theme={null}
{
  "job_id": "01HX4V2Z9B2F4T8H6P9K3N7Q1M",
  "status": "completed",
  "exit_code": 0,
  "files": [
    {
      "name": "output.geojson",
      "path": "/path/to/output/file",
      "size": 1024,
      "kind": "output"
    }
  ]
}
```

A non-zero `exit_code` means the container script exited with an error. Check stderr for the Python/R traceback.

***

## Inspect Run History

Every `geoengine run` is saved locally by default, with metadata and compressed streamed logs under `~/.geoengine/runs/<worker_id>/<job_id>/`. Use the `job_id` from the JSON result to inspect the run later:

```bash theme={null}
geoengine worker runs show <job-id> --json
geoengine worker runs logs <job-id> --stream stderr --tail 100
```

Use `geoengine run --no-history` for sensitive or ephemeral runs that should not be written to local history.

***

## Debug Worker Tests

If `geoengine test` fails, rerun the failing case with logs and keep the output folder:

```bash theme={null}
geoengine test --case <case-name> --verbose --keep-workdir
```

Inspect `.geoengine-test/<case-name>/` to confirm what the worker actually wrote. If the output is correct but the comparison failed, update the expected file, tolerance, or ignored JSON paths in `tests/geoengine.test.yaml`.

***

## Force a Clean Rebuild

If your Docker image is stale or a dependency change isn't being picked up, force a full rebuild with `--no-cache`:

```bash theme={null}
geoengine apply --no-cache
```

This bypasses Docker's layer cache and rebuilds the image from scratch. Use it when:

* You've updated a package version in `pixi.toml` but the old version is still being used
* The image is in an inconsistent state after a failed build
* You want to confirm the image builds cleanly from the current config

***

## Repair GeoEngine Artifacts

`geoengine patch` performs a maintenance sweep and repairs any broken state across all GeoEngine-managed artifacts:

```bash theme={null}
geoengine patch
```

Run this after upgrading GeoEngine, or whenever workers, plugins, or agent skills are behaving unexpectedly. It checks and repairs:

* **Global registry** (`~/.geoengine/settings.bin`) — validates the settings file
* **Worker state files** — validates `state/*.json`, reports orphaned records
* **Config snapshots** — validates `saves/<worker>/map.json`, checks all referenced snapshots exist
* **GIS plugins** — reinstalls stale or missing plugin files for QGIS and ArcGIS Pro
* **Agent skills** — syncs skill files into each installed agent's skills folder; files with matching SHA-256 hashes are skipped

`geoengine patch` exits with a non-zero status if any validation issue is found, making it safe to use in scripts.

***

## Delete a Worker or Version

If a worker is in a broken state and needs to be removed:

```bash theme={null}
# Delete a worker entirely by ID (shows a confirmation prompt)
geoengine delete --id <worker-id>

# Delete the worker in the current directory
geoengine delete

# Delete a specific tag only (removes image, mapping, and snapshot)
geoengine delete --tag claude-1.0.0
```

After deleting, re-apply the worker with `geoengine apply` to recreate it cleanly.

***

## Common Issues

### Build fails: `command.script` not found

Make sure the `script` path in `geoengine.yaml` is relative to the worker directory and the file actually exists there.

### `geoengine apply` rejects my version number

In production mode, the version in `geoengine.yaml` must be a valid semantic version (`MAJOR.MINOR.PATCH`) and must be greater than or equal to the highest version already recorded. Use `geoengine apply --dev` to skip this check during development.

### Worker appears in `geoengine workers` but not in QGIS/ArcGIS

Run `geoengine patch` to reinstall any stale plugin files, then close and reopen the GIS Processing Toolbox to refresh the worker list.

### Dependency changes not reflected after apply

Run `geoengine apply --no-cache` to force a full Docker rebuild. Docker may be using a cached layer that predates your `pixi.toml` changes.


# Installation & Setup
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/installation

Install GeoEngine, set up prerequisites, initialise AI agent skills, and configure GIS plugins

Get GeoEngine installed and ready to use on your machine. This guide walks you through installing Docker, the GeoEngine CLI, logging in, and optionally setting up AI agent skills and GIS plugin support.

## Prerequisites

Before installing GeoEngine, make sure you have the following:

### Required

* **[Docker](https://docs.docker.com/get-docker/)** — GeoEngine runs all workers in Docker containers. Install Docker Desktop (macOS/Windows) or Docker Engine (Linux) and ensure it is running before using any GeoEngine commands.

### Optional

* **GIS Platform(s)** — Install one or both if you want to run workers directly from your GIS software:
  * [QGIS](https://qgis.org) (open source)
  * [ArcGIS Pro](https://pro.arcgis.com/en/pro-app/latest/get-started/download-arcgis-pro.htm)
* **AI Agent(s)** — Install one or more if you want to use AI to create and manage workers automatically:
  * [Claude Code](https://claude.ai/code) by Anthropic (recommended)
  * [Cursor](https://cursor.com) by Cursor AI
  * [GitHub Copilot](https://github.com/features/copilot) by VS Code / Microsoft
  * [Codex](https://openai.com/codex/) by OpenAI
  * [Antigravity](https://antigravity.google) by Google
  * NIKA local agent tooling, if your organisation uses it

***

<div />

## Step 1: Install GeoEngine

Choose the installation method that matches your platform:

<Tabs>
  <Tab title="macOS">
    **Homebrew (recommended)**

    ```bash theme={null}
    brew tap NikaGeospatial/geoengine
    brew install geoengine
    ```

    **Shell script (alternative)**

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/geoengine/main/install/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    Open **PowerShell as Administrator** and run:

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/NikaGeospatial/geoengine/main/install/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/geoengine/main/install/install.sh | bash
    ```

    <Tip>This also works in WSL2 on Windows.</Tip>
  </Tab>
</Tabs>

### Offline / Air-Gapped Installation

If your machine has no internet access, copy the `geoengine` binary to the target machine first, then run:

```bash theme={null}
./install.sh --local ./geoengine
```

***

## Setup Troubleshooting

<Tabs>
  <Tab title="macOS">
    **Xcode Command Line Tools Error**

    GeoEngine itself does not depend on Xcode — it runs workers inside Docker containers. However, **Homebrew** (the macOS package manager used to install the GeoEngine CLI) requires the Xcode Command Line Tools to compile and link packages during installation. Without a compatible version of Xcode or its Command Line Tools, Homebrew cannot build the dependencies it needs, and the `brew install geoengine` step will fail.

    If you see errors related to **Xcode** or **Xcode Command Line Tools** when using Homebrew — such as:

    ```
    Error: Your Xcode (14.0) is too outdated.
    ```

    ```
    Error: Xcode alone is not sufficient on Catalina/Big Sur/Monterey/Ventura/Sonoma/Sequoia.
    ```

    ```
    xcode-select: error: command line tools are already installed, use "Software Update" to install updates
    ```

    You need to install or update Xcode before proceeding:

    1. Visit the [Apple Developer Downloads](https://developer.apple.com/download/all/) page
    2. Sign in with your Apple ID
    3. Search for the latest version of **Xcode** compatible with your macOS version
    4. Download and install it
    5. After installation, open a terminal and run:

    ```bash theme={null}
    sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
    sudo xcodebuild -runFirstLaunch
    ```

    6. Then retry the Homebrew installation:

    ```bash theme={null}
    brew tap NikaGeospatial/geoengine
    brew install geoengine
    ```

    <Tip>
      If you only need the **Command Line Tools** (without the full Xcode IDE), you can install them with `xcode-select --install`. However, some Homebrew formulae require the full Xcode application.
    </Tip>
  </Tab>

  <Tab title="Windows">
    No platform-specific issues are common at this stage. If you encounter problems, check that:

    * PowerShell was run **as Administrator**
    * **Docker Desktop** is installed and running
    * Your Windows version supports WSL2 (Windows 10 version 2004+ or Windows 11)
  </Tab>

  <Tab title="Linux">
    No platform-specific issues are common at this stage. If you encounter problems, check that:

    * **Docker Engine** is installed and the `docker` command is available
    * Your user is in the `docker` group (so you can run `docker` without `sudo`):
      ```bash theme={null}
      sudo usermod -aG docker $USER
      ```
      Log out and back in after running this command.
  </Tab>
</Tabs>

***

## Step 2: Log In

GeoEngine requires a free Nika account. Run the login command before using worker build, run, registry, and cloud commands:

```bash theme={null}
geoengine auth login
```

This will open a browser window where you can authorise GeoEngine with your Nika account. If the browser does not open automatically, the terminal will display a URL — hold **Cmd** (macOS) or **Ctrl** (Windows/Linux) and click the URL to open it manually.

<img alt="GeoEngine OAuth login screen" />

Click **Authorize** to complete the login. Your credentials are stored securely on your machine after the first login. You only need to run `geoengine auth login` again if your credentials expire or become corrupted. Commands such as `geoengine setup`, `geoengine lint`, `geoengine patch`, `geoengine update`, and `geoengine uninstall` do not require login, but worker commands like `geoengine apply`, `geoengine run`, `geoengine workers`, and `geoengine push` will prompt you to log in if your session is missing.

***

## Step 3: Initialise AI Agent Skills (Optional)

If you have an AI agent installed, run the following to install the GeoEngine skill bundle into your agent:

```bash theme={null}
geoengine setup skills
```

You will be prompted to select which agent(s) to install skills for:

* **Claude** (Anthropic) — recommended
* **Cursor** (Cursor AI)
* **GitHub Copilot** (VS Code / Microsoft)
* **Codex** (OpenAI)
* **Antigravity** (Google)
* **NIKA** (local NIKA tooling)

GeoEngine currently installs one top-level skill, `use-geoengine`. That skill contains the internal workflow guidance, references, and templates needed for worker creation, YAML updates, dependency updates, tests, cloud push, and maintenance commands. Skills that are already up to date are skipped; changed or missing files are installed automatically.

To install skills for one agent non-interactively, pass `--agent`:

```bash theme={null}
geoengine setup skills --agent Codex
```

### Verify Skills Are Working

After installing, open your AI agent and run the following prompt:

```
What skills do you have?
```

If the agent lists the GeoEngine skill (`use-geoengine`), the installation was successful.

If the agent does not mention the GeoEngine skill in its response, try prompting more specifically:

```
Do you have any GeoEngine-related skills installed?
```

If the agent still does not recognise the skill, check that the skill files are in the correct agent folder (e.g. `~/.claude/skills` for Claude Code) and restart your agent.

See [Create & Modify a Worker Using AI Coder](/guides/custom-geoprocess-deployment/ai-coder-worker) for the full workflow.

***

## GIS Plugin Installation (If Using QGIS or ArcGIS Pro)

<Note>
  This step is only required if you plan to run GeoEngine workers from **QGIS** or **ArcGIS Pro**. If you only use the CLI or AI agents to run workers, you can skip this step entirely.
</Note>

Install the local GIS plugin once with:

```bash theme={null}
geoengine setup plugins
```

You can also install a specific plugin non-interactively:

```bash theme={null}
geoengine setup plugins --qgis
geoengine setup plugins --arcgis   # Windows only
geoengine setup plugins --all
```

After the plugin is installed, applied workers are discovered from your local GeoEngine registry. You no longer need to enable individual workers with a `plugins:` section in `geoengine.yaml`.

If you upgrade GeoEngine later, run `geoengine patch` to bring all plugins back in sync:

```bash theme={null}
geoengine patch
```

***

## Next Steps

You are now ready to start using GeoEngine! Follow the [step-by-step guide](/guides/custom-geoprocess-deployment/step-by-step) to create your first worker!

***

## Enabling GIS Plugin

<Note>
  This section will only apply after you have done the `geoengine setup plugins` step. It is included for your information, but not part of
  GeoEngine's core installation.
</Note>

<div />

<Tabs>
  <Tab title="QGIS">
    You can install QGIS from the [QGIS website](https://qgis.org).

    <img alt="Enabling QGIS Plugin" />

    1. Run `geoengine setup plugins --qgis`, or select QGIS from the interactive plugin menu.
    2. Open QGIS and in the top bar, click **Plugins** > **Manage and Install Plugins...**
    3. Navigate to the **Installed** tab and enable the **GeoEngine** plugin
    4. GeoEngine will now be available in the **Processing** menu

    See [Running Workers in ArcGIS Pro & QGIS](/guides/custom-geoprocess-deployment/running-in-gis) for how to use the plugins once installed.
  </Tab>

  <Tab title="ArcGIS Pro">
    <Tabs>
      <Tab title="Windows">
        You can install ArcGIS Pro from the [ArcGIS website](https://pro.arcgis.com/en/pro-app/latest/get-started/download-arcgis-pro.htm).

        1. Run `geoengine setup plugins --arcgis`, or select ArcGIS from the interactive plugin menu.
        2. GeoEngine prints the path to `GeoEngineTools.pyt`.
        3. In ArcGIS Pro, navigate to the **Catalog** pane and right-click **Toolboxes** > **Add Toolbox**.
        4. Select the printed `GeoEngineTools.pyt` path and click **OK**.
        5. **GeoEngine Tools** should now be available in your Toolboxes.

        See [Running Workers in ArcGIS Pro & QGIS](/guides/custom-geoprocess-deployment/running-in-gis) for how to use the plugins once installed.
      </Tab>

      <Tab title="macOS">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>

      <Tab title="Linux">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Maintain GeoEngine Files
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/maintenance

Handle GeoEngine versioning, updates, and patches, as well as common maintenance issues you may encounter.

## Updating GeoEngine

To update to the latest version, run:

```bash theme={null}
geoengine update
```

GeoEngine detects how it was originally installed (Homebrew, curl, or PowerShell) and upgrades using the same method. After the binary is updated, it automatically runs `geoengine patch` to bring all workers, GIS plugins, and agent skills in sync with the new version.

A typical update looks like this:

```
Detected install method: Homebrew
==> brew update
==> brew upgrade geoengine
==> Upgrading nikageospatial/geoengine/geoengine
  0.6.1 -> 0.6.4
==> Summary
🍺  /opt/homebrew/Cellar/geoengine/0.6.4: 4 files, 10.2MB, built in 1 second
GeoEngine updated via Homebrew

Running geoengine patch...
Checking global artifacts...
  ✓ settings.bin

Checking GIS plugins...
  ✓ QGIS plugin reinstalled (files were stale)
  • ArcGIS not installed on this machine — skipping

Checking agent skills...
  ✓ Claude skills up-to-date
  ✓ Codex skills up-to-date
  ✓ Antigravity skills up-to-date

Patch complete: 0 workers checked, 1 plugin updated, 0 skills synced,
               0 migrations applied, 0 issues found.

...
```

<Tip>
  If the patch step reports that a GIS plugin was updated, restart QGIS or ArcGIS Pro to load the latest plugin version.
</Tip>

## Patching GeoEngine

Sometimes, you might want to check on the integrity of GeoEngine artifacts. To do so, run:

```bash theme={null}
geoengine patch
```

GeoEngine checks the integrity of all artifacts and reports any issues it finds.

### Common Issues

| Issue | Solution |
| - | - |
| Stale config files found | Run `geoengine delete` and `geoengine apply` again to reset worker cache. |
| Missing GIS plugins | Run `geoengine setup plugins`, then restart QGIS or re-add the ArcGIS toolbox. |


# Run Workers in ArcGIS Pro or QGIS
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/running-in-gis

Find and run your GeoEngine workers directly inside ArcGIS Pro and QGIS after applying them

After you have installed the GIS plugin and applied a GeoEngine worker, it appears as a native tool inside your GIS software — no proxy service, no per-worker plugin configuration. This guide shows you how to find and run your workers from QGIS and ArcGIS Pro.

If you haven't applied a worker yet, see [Your First Worker: Step-by-Step](/guides/custom-geoprocess-deployment/step-by-step) first.

***

## Running in QGIS

### Step 1: Open the Processing Toolbox

In QGIS, open the **Processing** menu and click **Toolbox**, or press `Ctrl+Alt+T` (`⌥+⌘+T` on Mac). The Processing Toolbox panel will appear on the right side of the screen.

### Step 2: Find Your Worker

Expand the **GeoEngine** provider in the toolbox. Your workers are listed by name. Each worker shows a **`my-worker (*latest)`** entry, plus one entry for each applied production local tag (for example `my-worker (1.0.0)` or `my-worker (release-candidate)`).

Click on any entry to see its description, config hash, and last-applied time in the help panel on the right.

### Step 3: Fill In Inputs and Run

Double-click a worker entry to open the tool dialog. Fill in the required input parameters:

* **File inputs** — use the file selector to browse to a file on your machine; GeoEngine mounts it automatically
* **Folder inputs** — select a directory
* **Other inputs** (enum, number, boolean, string) — displayed as dropdowns, number fields, checkboxes, or text fields

Click **Run**. Container logs stream into the QGIS log panel in real time. When the run finishes, output files are automatically added as layers to your QGIS project.

Local QGIS executions are stamped in GeoEngine run history with `--actor QGIS`.

***

## Running in ArcGIS Pro

### Step 1: Open the GeoEngine Toolbox

In ArcGIS Pro, open the **Analysis** tab and click **Tools** to open the Geoprocessing pane. Search for **GeoEngine** in the search bar, or browse to the GeoEngine toolbox in the **Toolboxes** section of the Catalog pane.

### Step 2: Find Your Worker

Expand the GeoEngine toolbox. Your applied workers appear as tool entries. The latest entry uses the worker name; tagged production entries include the local tag in brackets, for example `my-worker [1.0.0]`. Click a tool to see its description and parameters.

### Step 3: Fill In Inputs and Run

Double-click a worker to open its tool dialog. Fill in the required parameters and click **Run**. Container logs appear in the Geoprocessing history and messages panel. Output files are added to your ArcGIS Pro map automatically when the run completes.

Local ArcGIS Pro executions are stamped in GeoEngine run history with `--actor "ArcGIS Pro"`.

***

## Understanding Output

When a worker finishes, GeoEngine returns a structured JSON result:

```json theme={null}
{
  "job_id": "01HX4V2Z9B2F4T8H6P9K3N7Q1M",
  "status": "completed",
  "exit_code": 0,
  "files": [
    {
      "name": "output.geojson",
      "path": "/path/to/output/file",
      "size": 123,
      "kind": "output"
    }
  ]
}
```

* **`job_id`** — the saved run ID; use it with `geoengine worker runs show` or `geoengine worker runs logs` when inspecting local run history
* **`kind: "output"`** — a file produced by the worker; automatically added to your GIS view
* **`kind: "input"`** — an input file that was passed in; also shown in the GIS so you can compare input and output side by side

If a run fails, the exit code and any error messages from the container appear in the GIS messages panel.

***

## Cancelling a Run

You can cancel a running worker at any time using the cancel button in the GIS progress dialog. Cancellation terminates the GeoEngine subprocess, which in turn stops and removes the Docker container immediately.

***

## Refreshing the Worker List

The plugin reads the worker list fresh each time the toolbox is opened. If you apply a new worker or a new version and it doesn't appear in your GIS yet, close and reopen the Processing Toolbox (QGIS) or Geoprocessing pane (ArcGIS Pro) to trigger a refresh.


# Your First Worker: Step-by-Step
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/step-by-step

Download a ready-made GeoEngine worker, apply it locally, and push it to the cloud — all in a few commands.

This guide walks you through deploying your first GeoEngine worker from start to finish. Every command is ready to copy and paste — just follow the steps in order. A couple of surprises are built in along the way, so don't skip ahead.

<Note>
  This guide assumes you have already installed GeoEngine and logged in. If you haven't, complete the [Installation & Setup](/guides/custom-geoprocess-deployment/installation) guide first.
</Note>

***

## Introduction

We will be deploying a simple geoprocessing worker that creates a grid around a vector input. The script is written in Python.

***

<div />

## Step 1 — Download the Starter Script

<a href="https://github.com/NikaGeospatial/geoengine/releases/download/docs-downloads/grid_creation.py">Download the starter worker script</a> and save it in an isolated folder somewhere on your machine — your home directory or Desktop works fine.

<Tabs>
  <Tab title="macOS">
    For this example, we will assume you created a directory in `/Users/<user>/Downloads/grid-creator`. Place the script into this directory.
  </Tab>

  <Tab title="Windows">
    For this example, we will assume you created a directory in `C:/Users/<user>/Downloads/grid-creator`. Place the script into this directory.
  </Tab>

  <Tab title="Linux">
    For this example, we will assume you created a directory in `/home/<user>/Downloads/grid-creator`. Place the script into this directory.
  </Tab>
</Tabs>

You should now have a folder called `grid-creator` in your current directory.

***

## Step 2 — Navigate Into the Directory

```bash theme={null}
cd ~/Downloads/grid-creator
```

All GeoEngine commands from here on must be run from inside this folder.

***

## Step 3 - Initialise the Worker

First, you have to generate the worker artifact templates. Run the following in the same terminal.

```bash theme={null}
geoengine init --env py
```

Here, we specify the `--env` flag to create a Python-centric dependencies template. If you were to use an R script, use `--env r` instead.

When GeoEngine asks whether to create a `tests/` folder, choose **Yes**. If you skipped it, the testing step below shows the exact files to create.

***

## Step 4 — Inspect the Files

Take a moment to look at what's inside before running anything:

### Main Script

* **`grid_creation.py`** — the Python script that does the actual geoprocessing work

### GeoEngine Worker Configurations

The following files can be edited to customize the worker:

* **`pixi.toml`** — declares all the Python/conda dependencies GeoEngine will install into the Docker container
* **`geoengine.yaml`** — the worker configuration: its name, version, local tag, command, and inputs

### GeoEngine Worker Build Artifacts

The following files are automatically generated by GeoEngine, and should not be edited unless you know what you're doing:

* **`.dockerignore`** — tells Docker which files to ignore when building the image
* **`geoengine.lock`** - the ID of the worker (do not touch this)
* **`tests/`** — local worker test scaffold, if you chose to create it during init

The **`Dockerfile`** is generated during `geoengine apply` for normal Python/R workers. Once it exists, treat it as a GeoEngine-managed build artifact.

***

## Step 5 - Wire up the Script

Ensure that your script has an argparser set up. If you look at the script, you will notice it is already done. So now, we just need to wire up the config files to match the script.

### Add Dependencies

Open up `pixi.toml` in an editor of your choice.

Here, you can edit the `[workspace]` section if you wish. This will not be reflected anywhere, but is just a mere requirement of Pixi.

You will notice an empty `[dependencies]` section. The GeoEngine runtime image already includes common geospatial packages such as GDAL, pandas, NumPy, GeoPandas, and Shapely, which are sufficient for this script. If your own worker needs extra conda-forge packages, add only those extras here.

### Edit the Config File

Open up `geoengine.yaml` in an editor of your choice.

Here, you will define the worker's details: its name, description, local tag, command, and input parameters.

* The template creates the worker `name` based on your directory folder, but feel free to change it as you wish.
* The `version` field is the cloud-facing semantic version. For now you can leave it at `1.0.0`.
* The `local_tag` field labels this local production build. Use it to provide short but informative information about the local version.
* The `description` field will be write-up on your worker's workings. Optional, but good to have.
* The `command` section details out the running requirements of your worker. The inputs should match the arguments set up in the argparser in your script.
* Inputs marked with `output: true` are writable output paths. Other file and folder inputs are mounted read-only.

For this example, copy and paste the below configuration wholesale into the `geoengine.yaml`.

```yaml theme={null}
name: grid-creator
version: "1.0.0"
local_tag: "my-first-tag"
description: Create square, rectangle, or diamond grids from an input vector extent
command:
  program: python
  script: grid_creation.py
  inputs:
  - name: input-file
    type: file
    required: true
    description: Input vector file used to derive the grid extent
  - name: grid-type
    type: enum
    required: false
    default: square
    description: Grid geometry type
    enum_values:
    - square
    - rectangle
    - diamond
  - name: cell-width
    type: number
    required: true
    description: Grid cell width in CRS units (or meters when auto-reproject is true)
  - name: cell-height
    type: number
    required: false
    description: Grid cell height for rectangle grids (optional for square/diamond)
  - name: output-file
    type: string
    required: false
    default: regular_grid
    description: Output file name without extension (GeoJSON will be written)
  - name: output-dir
    type: folder
    required: true
    description: Output folder for the generated GeoJSON grid
    output: true
  - name: auto-reproject
    type: boolean
    required: false
    default: true
    description: Auto-reproject geographic CRS inputs to UTM while generating the grid
  - name: add-id
    type: boolean
    required: false
    default: true
    description: Add a grid_id column to the output
```

***

## Step 6 — Apply the Worker Locally

First, run the semantic config checks:

```bash theme={null}
geoengine lint
```

Then build and apply the worker in development mode:

```bash theme={null}
geoengine apply --dev
```

GeoEngine will resolve dependencies, build the Docker image, and register the worker on your machine. The first apply takes the longest — pixi is downloading and locking all the packages declared in `pixi.toml`.

<Tip>
  The first `geoengine apply --dev` can take several minutes while pixi installs dependencies into the Docker image. Subsequent applies are much faster because the image layers are cached. This is completely normal — let it run.
</Tip>

When it finishes, you should see output like this:

```
=> Building worker 'grid-creator'...
✓ Successfully built image: geoengine-local/<uuid>:latest
✓ Registered worker 'grid-creator'
✓ Apply complete for worker 'grid-creator'
```

The worker is now built and registered! You can check details of the worker by running while still in the `grid-creator` directory:

```bash theme={null}
geoengine describe
```

***

## Step 7 — Add a First Worker Test

Before opening GIS, add a tiny local contract test. This gives you a repeatable way to prove the worker still builds a grid after future edits.

If `tests/fixtures/` does not exist yet, create it. Then add a file at `tests/fixtures/small_extent.geojson`:

```json theme={null}
{
  "type": "FeatureCollection",
  "name": "small_extent",
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 1
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [0.0, 0.0],
            [0.0, 0.002],
            [0.002, 0.002],
            [0.002, 0.0],
            [0.0, 0.0]
          ]
        ]
      }
    }
  ]
}
```

Now replace `tests/geoengine.test.yaml` with this first smoke test:

```yaml theme={null}
version: 1
cases:
  - name: square-grid-smoke
    inputs:
      input-file: fixtures/small_extent.geojson
      grid-type: square
      cell-width: 0.001
      output-file: square_grid
      output-dir: outputs
      auto-reproject: false
      add-id: true
    expect:
      exit_code: 0
      files:
        - path: outputs/square_grid.geojson
          exists: true
          min_size: 1
          extension: .geojson
```

Run the test:

```bash theme={null}
geoengine test
```

GeoEngine runs the applied worker through the same runtime path as `geoengine run --actor CLI --json`. The fixture path is resolved from `tests/`, and the output path is created under `.geoengine-test/square-grid-smoke/`.

<Tip>
  Use `geoengine test --keep-workdir` if you want to inspect the generated output folder after the run.
</Tip>

***

## Step 8 — GIS Testing

<div />

If you want to run this worker from QGIS or ArcGIS Pro, install the local GIS plugin once:

```bash theme={null}
geoengine setup plugins
```

After the plugin is installed, it discovers applied workers from the local GeoEngine registry.

<Tabs>
  <Tab title="QGIS">
    ### Enable the Plugin in QGIS

    After `geoengine setup plugins --qgis` installs the plugin, enable it inside QGIS once:

    1. In the QGIS top bar, click **Plugins** > **Manage and Install Plugins...**
    2. Go to the **Installed** tab
    3. Find **GeoEngine** in the list and check the box next to it
    4. Close the dialog

    <Note>
      You only need to enable the plugin once. Future applies and updates will not require you to do this again.
    </Note>

    ### Processing Toolbox

    The GeoEngine plugin should now be available in the **Processing Toolbox**. Open it from the top bar **Processing > Toolbox**.

    <Tabs>
      <Tab title="macOS">
        Alternatively, you can use the short cut `⌥`+`⌘`+`T`.
      </Tab>

      <Tab title="Windows">
        Alternatively, you can use the short cut `Ctrl`+`Alt`+`T`.
      </Tab>

      <Tab title="Linux">
        Alternatively, you can use the short cut `Ctrl`+`Alt`+`T`.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="ArcGIS Pro">
    <Tabs>
      <Tab title="Windows">
        ### Enable the Plugin in ArcGIS Pro

        After `geoengine setup plugins --arcgis` installs the toolbox, add it inside each ArcGIS Pro project:

        1. Copy the `GeoEngineTools.pyt` path printed by `geoengine setup plugins --arcgis`
        2. In ArcGIS Pro, navigate to the **Catalog** pane and right-click **Toolboxes** > **Add Toolbox**
        3. Paste the path reference to the plugin in the file dialog and click **OK**
        4. **GeoEngine Tools** should now be available in your Toolboxes

        <Note>
          You need to add the GeoEngine toolbox once per ArcGIS Pro project.
        </Note>

        ### Processing Toolbox

        The GeoEngine plugin should now be available as a Toolbox. Go on to **Catalog** to check it out.

        If the worker list looks stale, right-click the `GeoEngineTools.pyt` toolbox and click **Refresh Toolbox**.
      </Tab>

      <Tab title="macOS">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>

      <Tab title="Linux">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Step 9 — Run the Worker from GIS

<Tabs>
  <Tab title="QGIS">
    In the **Processing Toolbox**, expand **GeoEngine** and find **grid-creator (\*latest)**. Double-click it to open the tool dialog.

    Load a vector layer as the **Input Layer** — any polygon or line layer you have on hand works for a first test run. You can even load in a vector file. Click **Run**.

    GeoEngine executes the script inside the Docker container and streams the output back to QGIS. When it finishes, a result layer will appear in your **Layers** panel and render on the map canvas.

    <Tip>
      If the tool dialog does not appear or the worker shows an error, check the **GeoEngine Log** panel (View > Panels > GeoEngine Log) for the full output from inside the container.
    </Tip>
  </Tab>

  <Tab title="ArcGIS Pro">
    <Tabs>
      <Tab title="macOS">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>

      <Tab title="Windows">
        In the **Geoprocessing** pane, search for **GeoEngine** or browse to **Toolboxes > GeoEngine Tools**. Open **grid-creator**, fill in the parameters, and click **Run**.

        Container logs appear in the Geoprocessing messages panel. When the run completes, output files are added to your map automatically when ArcGIS Pro can read the output format.
      </Tab>

      <Tab title="Linux">
        <Note>
          ArcGIS Pro is not supported on .
        </Note>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Step 10 — Push to the Cloud

Once you're happy with how the worker runs locally, publish it so your whole team can access it. Pushing requires a production apply, so first make sure `geoengine.yaml` has a valid `version` and `local_tag`, then rerun the local checks:

```bash theme={null}
geoengine lint
geoengine test
```

Then apply in production mode:

```bash theme={null}
geoengine apply
```

Then push the image to the cloud:

```bash theme={null}
geoengine push
```

GeoEngine pushes the most recently applied production `local_tag` and publishes it with the semantic `version` from `geoengine.yaml`. If you have access to multiple teams, you will be prompted to select the team you wish to push to.

<Note>
  After pushing, the worker is available to everyone in your Nika organisation — in QGIS, ArcGIS Pro, and the Nika web platform — without them needing to run `geoengine apply` themselves.
</Note>

***

## Next Steps

You've gone from a zip file to a live cloud-deployed geoprocessing worker. Here's where to go from here:

* [Running Workers in ArcGIS Pro & QGIS](/guides/custom-geoprocess-deployment/running-in-gis) — inputs, outputs, and layer handling in detail
* [Designing Worker Tests](/guides/custom-geoprocess-deployment/test-designing) — fixtures, expected outputs, and semantic comparisons
* [Versioning](/guides/custom-geoprocess-deployment/versioning) — how to version, tag, and roll back workers
* [Cloud Push & Deployment](/guides/custom-geoprocess-deployment/cloud-push) — advanced push options and CI/CD integration


# Designing Worker Tests
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/test-designing

Design tight but stable GeoEngine worker tests using fixtures, expected outputs, and semantic comparisons

GeoEngine workers can do almost anything: read rasters, create vectors, write folders of outputs, run analysis, transform files, or generate reports. That flexibility is powerful, but it also makes testing tricky.

`geoengine test` gives you a structured way to test open-ended workers. Instead of only checking exact file matches, you describe small test cases with inputs and expectations: the worker should run successfully, create the right output files, and, whenever possible, match expected semantic output.

<Note>
  Use `geoengine test` during development, before a production `geoengine apply` and `geoengine push`. It helps you catch broken inputs, missing dependencies, incorrect output paths, and accidental behavior changes earlier.
</Note>

***

## What `geoengine test` Does

A GeoEngine test case runs your worker through the same runtime path as:

```bash theme={null}
geoengine run --actor CLI --json
```

That means tests use the applied worker image, the saved `geoengine.yaml` command contract, and GeoEngine's normal file/folder mounting behavior.

A test can check things like:

* The worker exits with code `0`
* An output file was created
* An output file has a minimum size
* A folder contains a certain number of outputs
* A file hash matches exactly
* Text output matches with normalized whitespace
* JSON or GeoJSON matches with numeric tolerance

The best tests are tight but not brittle. They prove the worker produced the right result without failing on harmless serialization details.

***

## Test Folder Layout

When you run `geoengine init`, GeoEngine can scaffold a `tests/` folder for you.

The scaffolded layout is:

```text theme={null}
tests/
  geoengine.test.yaml
  fixtures/
  expected/
```

| Path | Purpose |
| - | - |
| `tests/geoengine.test.yaml` | The test manifest. This is where test cases are declared. |
| `tests/fixtures/` | Small input files used by tests. |
| `tests/expected/` | Expected output files, if you need comparisons. |
| `tests/validators/` | Optional project-side helper scripts if your team wants them. `geoengine init` does not create this folder, and the core `geoengine test` command does not run these automatically. |

When tests run, GeoEngine writes generated outputs to:

```text theme={null}
.geoengine-test/
```

You should not use `.geoengine-test/` as a fixture folder. It is a temporary output area created by `geoengine test`.

<Tip>
  `tests/` and `.geoengine-test/` are excluded from the Docker build context. Test fixtures should not be baked into your worker image.
</Tip>

***

## Path Resolution Rules

`geoengine test` resolves paths differently depending on whether the input is read-only or writable.

### Read-only file and folder inputs

For normal file/folder inputs, relative paths are resolved from `tests/`.

```yaml theme={null}
inputs:
  input-file: fixtures/small_extent.geojson
```

This points to:

```text theme={null}
tests/fixtures/small_extent.geojson
```

### Output file and folder inputs

For inputs marked with `output: true` in `geoengine.yaml`, relative paths are resolved inside the per-case test output folder.

```yaml theme={null}
inputs:
  output-dir: outputs
```

For a case named `square-grid`, this points to:

```text theme={null}
.geoengine-test/square-grid/outputs
```

This keeps test outputs isolated and repeatable.

***

## Manifest Assertions

Each case in `tests/geoengine.test.yaml` can include `inputs`, extra raw `args`, and an `expect` block.

```yaml theme={null}
version: 1
cases:
  - name: smoke
    inputs:
      input-file: fixtures/sample.geojson
      output-dir: outputs
    args: []
    expect:
      exit_code: 0
      files:
        - path: outputs/result.geojson
          exists: true
          min_size: 1
      compare:
        - actual: outputs/result.geojson
          expected: expected/result.geojson
          mode: geojson
```

### File expectations

| Field | Description |
| - | - |
| `path` | One file or folder to check. It can be an output input name, such as `output`, or a path relative to the case output folder. |
| `glob` | Match files under the case output folder. Supports `*`, `?`, and `**`. |
| `exists` | Defaults to `true`. Set to `false` when a path should not exist. |
| `missing` | Set to `true` when a path should be absent. |
| `min_size` / `max_size` | Check file size in bytes. |
| `count` | With `glob`, assert the number of matches. |
| `sha256` | Require an exact SHA-256 hash. Use only for deterministic bytes. |
| `extension` | Require a file extension, such as `.geojson` or `.csv`. |

### Comparisons

| Field | Description |
| - | - |
| `actual` | Output file path, resolved from the case output folder unless it names an input path. |
| `expected` | Expected file path, resolved from `tests/`. |
| `mode` | `bytes` or `exact` for byte comparison, `text` for text, `json` for JSON, `geojson` for GeoJSON. Defaults to `bytes`. |
| `normalize_whitespace` | For `text` mode, compare collapsed whitespace instead of exact spacing. |
| `tolerance.numbers` | Numeric tolerance for `json` or `geojson` comparisons. |
| `tolerance.coordinates` | Alias for numeric tolerance in geospatial comparisons. |
| `ignore_paths` | Dot-style JSON paths to ignore, such as `$.name` or `$.features.0.properties.id`. |

JSON and GeoJSON comparisons are structural: object keys and array order must match unless a path is ignored, and numbers can differ within the configured tolerance.

***

## Start With the Worker Contract

Before writing tests, inspect `geoengine.yaml` and answer:

* Which inputs are required?
* Which inputs are output paths?
* Which branches are meaningful to test?
* Which outputs are deterministic enough to compare?
* Which metadata might vary between machines or library versions?

A good test follows the worker contract. If the script writes to `output-dir` and uses `output-file` as a basename, the test should use those same inputs instead of assuming a hard-coded path inside the container.

***

## Smoke Tests vs Semantic Tests

Smoke tests and semantic tests are both useful, but they are not the same.

### Smoke test

A smoke test proves that the worker runs and writes something plausible:

```yaml theme={null}
expect:
  exit_code: 0
  files:
    - path: outputs/result.geojson
      exists: true
      min_size: 1
```

This catches common failures:

* The worker crashes
* A dependency is missing
* The output path is wrong
* Nothing was written

A smoke test is a good starting point, but it does not prove the output is correct.

### Tight semantic test

A semantic test checks the meaning of the output:

```yaml theme={null}
expect:
  exit_code: 0
  files:
    - path: outputs/result.geojson
      exists: true
      min_size: 1
      extension: .geojson
  compare:
    - actual: outputs/result.geojson
      expected: expected/result.geojson
      mode: geojson
      tolerance:
        numbers: 0.000001
      ignore_paths:
        - $.name
        - $.crs
```

This checks the generated data while allowing harmless metadata and floating-point differences.

<Note>
  When the output is predictable, prefer semantic tests. Smoke-only tests should be the fallback floor, not the default finish line.
</Note>

***

## Example: Testing a Grid Creator Worker

Suppose your worker creates regular grids from an input vector extent.

The relevant `geoengine.yaml` inputs might look like this:

```yaml theme={null}
command:
  program: python
  script: grid_creation.py
  inputs:
    - name: input-file
      type: file
      required: true

    - name: grid-type
      type: enum
      required: false
      default: square
      enum_values:
        - square
        - rectangle
        - diamond

    - name: cell-width
      type: number
      required: true

    - name: cell-height
      type: number
      required: false

    - name: output-file
      type: string
      required: false
      default: regular_grid

    - name: output-dir
      type: folder
      required: true
      output: true

    - name: auto-reproject
      type: boolean
      required: false
      default: true

    - name: add-id
      type: boolean
      required: false
      default: true
```

Create a tiny fixture:

```text theme={null}
tests/fixtures/small_extent.geojson
```

Then create `tests/geoengine.test.yaml`:

```yaml theme={null}
version: 1
cases:
  - name: square-grid
    inputs:
      input-file: fixtures/small_extent.geojson
      grid-type: square
      cell-width: 0.001
      output-file: square_grid
      output-dir: outputs
      auto-reproject: false
      add-id: true
    expect:
      exit_code: 0
      files:
        - path: outputs/square_grid.geojson
          exists: true
          min_size: 1
          extension: .geojson
      compare:
        - actual: outputs/square_grid.geojson
          expected: expected/square_grid.geojson
          mode: geojson
          tolerance:
            numbers: 0.000000001
          ignore_paths:
            - $.name
            - $.crs
            - $.features.0.properties.id
            - $.features.1.properties.id
            - $.features.2.properties.id
            - $.features.3.properties.id

  - name: rectangle-grid
    inputs:
      input-file: fixtures/small_extent.geojson
      grid-type: rectangle
      cell-width: 0.001
      cell-height: 0.002
      output-file: rectangle_grid
      output-dir: outputs
      auto-reproject: false
      add-id: true
    expect:
      exit_code: 0
      files:
        - path: outputs/rectangle_grid.geojson
          exists: true
          min_size: 1
          extension: .geojson
      compare:
        - actual: outputs/rectangle_grid.geojson
          expected: expected/rectangle_grid.geojson
          mode: geojson
          tolerance:
            numbers: 0.000000001
          ignore_paths:
            - $.name
            - $.crs
            - $.features.0.properties.id
            - $.features.1.properties.id
```

This tests two important code paths:

* A square grid with only `cell-width`
* A rectangle grid with both `cell-width` and `cell-height`

It is tighter than a smoke test because it compares generated GeoJSON against expected output. It is still not brittle because it ignores harmless writer metadata such as top-level `name`, `crs`, and generated feature `id` fields.

***

## Running Tests

Before running tests, lint and apply the worker in development mode:

```bash theme={null}
geoengine lint
geoengine apply --dev
```

Then run all test cases:

```bash theme={null}
geoengine test
```

Run one case by name:

```bash theme={null}
geoengine test --case square-grid
```

Keep the generated `.geoengine-test/` output folders for inspection:

```bash theme={null}
geoengine test --keep-workdir
```

Emit a JSON test report:

```bash theme={null}
geoengine test --json
```

Show container logs for every case, even when the case passes:

```bash theme={null}
geoengine test --verbose
```

Test a specific applied local tag:

```bash theme={null}
geoengine test --tag codex-1.0.0
```

***

## Recommended Development Loop

Use this loop while building or changing a worker:

```bash theme={null}
geoengine lint
geoengine apply --dev
geoengine test
```

If tests fail, fix the correct layer:

| Failure | Usually check |
| - | - |
| `geoengine lint` fails | `geoengine.yaml` structure or input definitions |
| `geoengine apply --dev` fails | Dependencies, Docker build, script path, config |
| `geoengine test` exits non-zero | Script logic, missing dependencies, bad test inputs |
| Output file missing | Output path, `output: true`, script write location |
| Comparison fails | Expected file, tolerance, output format, real behavior change |

Repeat the loop until tests pass.

Only then do a production apply:

```bash theme={null}
geoengine apply
```

And, when ready, push:

```bash theme={null}
geoengine push
```

***

## Choosing the Right Assertion Strictness

Start with the strongest check that matches the stability of the output.

### Smoke test

Use this for highly open-ended outputs, early scaffolding, or as a baseline case:

```yaml theme={null}
expect:
  exit_code: 0
  files:
    - path: output
      exists: true
      min_size: 1
```

This catches the most common problems: the worker failed, wrote nothing, or wrote to the wrong place. It does not prove the output is correct.

### Tight semantic test

Use this when the expected result can be described:

```yaml theme={null}
expect:
  files:
    - path: outputs/result.geojson
      exists: true
      min_size: 1
  compare:
    - actual: outputs/result.geojson
      expected: expected/result.geojson
      mode: geojson
      tolerance:
        numbers: 0.000001
      ignore_paths:
        - $.name
        - $.crs
```

This is usually the best option for geospatial outputs: it checks meaningful content while allowing harmless floating-point and metadata differences.

### Exact hash test

Use hashes only when output is truly stable:

```yaml theme={null}
expect:
  files:
    - path: outputs/result.csv
      sha256: "abc123..."
```

Avoid hash checks for files that include timestamps, unordered features, generated IDs, floating-point formatting, or metadata that may vary between library versions.

***

## Good Practices

### Prefer tight semantic checks

A good test should prove the worker produced the right result, not merely that it produced a file.

For deterministic outputs, prefer checks like:

* Expected feature count
* Expected properties or columns
* Expected geometry type
* Expected filenames
* Expected CRS behavior, when stable
* Expected numeric values with tolerance

For example, a grid worker should usually compare against an expected GeoJSON file with `mode: geojson`, rather than only checking that `output.geojson` exists.

### Avoid brittle serialization details

Some output fields depend on the writer library, driver version, or machine environment. Ignore these when they are not part of the worker contract.

Common fields to ignore:

```yaml theme={null}
ignore_paths:
  - $.name
  - $.crs
  - $.features.0.properties.id
```

The goal is to test meaning, not harmless metadata.

### Keep fixtures small

Use the smallest fixture that exercises the behavior. A tiny GeoJSON polygon, a few CSV rows, or a small raster tile is usually better than a realistic production-sized file.

Small fixtures make tests:

* Faster
* Easier to review
* Easier to debug
* Safer to commit

### Test representative branches

Do not write ten nearly identical smoke tests. Instead, choose cases that cover meaningful behavior changes.

For example, a grid worker might test:

* `square`
* `rectangle`
* `diamond`
* Optional `add-id: false`
* Auto-reprojection on/off, if that behavior matters

### Use exact hashes sparingly

Hashes are useful only when the entire file is deterministic. Avoid hashes for GeoJSON, rasters, reports, or files with timestamps unless you are certain the serialization is stable.

Prefer structured comparison with tolerance when possible.

### Commit test inputs and expected outputs

Commit:

```text theme={null}
tests/fixtures/
tests/expected/
tests/geoengine.test.yaml
```

Do not commit:

```text theme={null}
.geoengine-test/
```

That folder is generated by test runs.

***

## Writing Useful Fixtures

Keep fixtures small and intentional.

Good fixtures are:

* Tiny enough to commit to Git
* Representative of real user input
* Focused on one behavior
* Stable across machines
* Free of private or customer data

Avoid fixtures that are:

* Huge
* Downloaded from the network during tests
* Machine-specific
* Licensed or sensitive
* More complicated than the behavior being tested

For geospatial workers, a tiny GeoJSON polygon or point collection is often enough for a meaningful test.

***

## Working With AI Agents

If you are using an AI coding assistant with GeoEngine skills installed, ask it to create tests after the worker config is wired up.

Example prompt:

```text theme={null}
Create GeoEngine test cases for this worker using the GeoEngine testing guidance.
Use small fixtures and prefer tight semantic tests where the output is predictable.
Avoid brittle exact hashes unless the output serialization is deterministic.
Then run geoengine lint, geoengine apply --dev, and geoengine test.
If tests fail, fix the correct layer and repeat until they pass.
```

A good AI-generated test should include:

* `tests/geoengine.test.yaml`
* At least one small fixture
* Expected outputs when the result is predictable
* Assertions that match the worker's real outputs
* No large generated output committed as a fixture unless it is intentional

***

## What to Commit

For a normal worker repository, commit:

```bash theme={null}
git add geoengine.yaml pixi.toml geoengine.lock tests/ *.py
```

For R workers, replace `*.py` with `*.R`.

Do not commit:

```text theme={null}
.geoengine-test/
```

That folder is runtime output from tests.

***

## Common Mistakes

### The test passes locally but fails for a teammate

Make sure `geoengine.lock` is committed so everyone is applying and testing the same worker ID.

Also make sure fixtures use relative paths under `tests/`, not absolute paths from your machine.

### The worker writes no output

Check that the corresponding `geoengine.yaml` input is marked as an output:

```yaml theme={null}
- name: output-dir
  type: folder
  output: true
```

If `output: true` is missing, GeoEngine treats the path as read-only input instead of a writable output mount.

### The test is too loose

If your test only checks that a file exists, ask whether the output is predictable enough to compare.

For deterministic workers, add an expected output and use `mode: json`, `mode: geojson`, or normalized text comparison.

### The test is too brittle

If a comparison fails because of metadata, writer-specific fields, timestamps, generated IDs, or tiny floating-point differences, ignore or tolerate those fields instead of weakening the whole test.

For example:

```yaml theme={null}
tolerance:
  numbers: 0.000001
ignore_paths:
  - $.name
  - $.crs
  - $.features.0.properties.id
```

### Tests force image rebuilds

`tests/` and `.geoengine-test/` are ignored by GeoEngine's Docker build context. If changing tests appears to trigger rebuilds, update GeoEngine and run:

```bash theme={null}
geoengine patch
```

***

## Summary

Use `geoengine test` to make worker development repeatable:

```bash theme={null}
geoengine lint
geoengine apply --dev
geoengine test
```

A good worker test should be tight enough to catch wrong results and flexible enough to ignore harmless serialization differences. Smoke tests are useful, but when the output is predictable, prefer semantic comparisons with expected files and tolerances.


# Version Workers
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/versioning

Understand how GeoEngine versions workers, the difference between versions and local tags, and how to reproduce any past build exactly

GeoEngine uses [Semantic Versioning](https://semver.org/) for cloud-facing worker releases and a separate `local_tag` for local builds. Every production apply records a local tag and a config snapshot, so any past production build can be reproduced and run later — even after the code has changed.

***

## Versions vs Local Tags

These two concepts are related but distinct:

* **Version** — the semantic version string you set in `geoengine.yaml` (e.g. `1.2.0`). It follows `MAJOR.MINOR.PATCH` rules and is enforced by GeoEngine during production applies. This is the version sent to the cloud when you push.
* **Local tag** — the local build label GeoEngine uses for Docker tags and saved snapshots. Set it with `local_tag` in `geoengine.yaml` when you want a named local build (for example `release-candidate`). If you omit it during a production apply, GeoEngine asks whether to use the `version` value as the local tag.

You reference a specific past build using its local tag (for example `--tag 1.2.0` or `--tag release-candidate`), not necessarily the raw semantic version.

***

## Version Format

Worker versions follow the `MAJOR.MINOR.PATCH` format, set in `geoengine.yaml`:

```yaml theme={null}
name: my-worker
version: "1.2.0"
local_tag: "1.2.0"
```

All three version components are required. Examples of valid versions: `1.0.0`, `0.3.1`, `2.10.4`. A version like `1.0` or `1` is invalid and will cause a production `geoengine apply` to fail.

As a general guide:

* **PATCH** (`1.0.0` → `1.0.1`) — bug fixes, small script tweaks, no change to inputs or outputs
* **MINOR** (`1.0.0` → `1.1.0`) — new optional inputs, improved output, backwards-compatible changes
* **MAJOR** (`1.0.0` → `2.0.0`) — removed or renamed inputs, changed output format, breaking changes

***

## Dev vs Production Applies

GeoEngine has two apply modes. Which one you use determines whether versioning is enforced and whether a snapshot is saved.

| | Dev (`--dev`) | Production (no flag) |
| - | - | - |
| Version check | Skipped | Enforced |
| Image tagged as | `latest` only | `<worker-id>:<local_tag>` + `latest` |
| Config snapshot saved | Mutable `latest` snapshot | Tagged snapshot + `latest` |
| Reproducible later | No | Yes — via `--tag` |
| Appears in GIS by version | No — `latest` only | Yes |

### During Development

Use `--dev` to iterate freely without worrying about version numbers:

```bash theme={null}
geoengine apply --dev
```

The image is tagged as `latest`. Running `geoengine apply --dev` again overwrites the mutable latest image and latest config, even if a prior production version exists.

### For Production Releases

When the worker is ready to share or use in GIS tools, apply without `--dev`:

```bash theme={null}
geoengine apply
```

GeoEngine will enforce that:

1. The `version` field is present in `geoengine.yaml`
2. The version is a valid semver string (`MAJOR.MINOR.PATCH`)
3. The version is **greater than or equal to** the highest version currently recorded locally
4. The selected `local_tag` is not `latest` and does not already point to different content

If any of these checks fail, the apply is rejected with an error.

If `local_tag` is missing, GeoEngine prompts you to use the version string as the local tag. Accepting this is fine for normal releases; add an explicit `local_tag` when you need multiple local builds for the same version.

***

## Running a Specific Tag

To run a previously-built local tag instead of `latest`:

```bash theme={null}
geoengine run --actor CLI --tag 1.0.0 --input input-file=/path/to/data.tif
```

GeoEngine loads the snapshotted configuration for that tag and runs the corresponding Docker image. This works regardless of what the current `geoengine.yaml` says — the snapshot is self-contained.

If `--tag` is omitted, `geoengine run` always uses `latest`, which tracks the most recent apply (dev or production).

***

## The `latest` Tag

`latest` always points to the most recent apply, regardless of mode:

* Running `geoengine apply --dev` after a production apply will overwrite `latest` with the dev state
* Running `geoengine apply` (production) also updates `latest` to that version

This means `geoengine run` (without `--tag`) and GIS plugin `latest` entries always reflect the last apply. **If you need a stable, pinned version in GIS, always use a production apply and reference it by its local tag.**

***

## Deleting a Tag

To remove a specific local tag (its Docker image, mapping entry, and snapshot):

```bash theme={null}
geoengine delete --tag 1.0.0
```

The version check during the next `geoengine apply` always reads the live `map.json`, so deleting an older tag does not affect the minimum allowed version for the next apply.

To remove a worker entirely, run from the worker directory or pass `--id <worker-id>`:

```bash theme={null}
geoengine delete
```

***

## Example Versioning Workflow

```bash theme={null}
# --- Development phase ---
# Iterate freely without bumping the version
geoengine apply --dev    # updates mutable latest
geoengine apply --dev    # overwrites latest again

# --- Ready for release ---
# Bump version in geoengine.yaml to 1.0.0, then:
geoengine apply          # saves snapshot, creates local tag 1.0.0 + latest

# --- Iteration after release ---
geoengine apply --dev    # dev build overwrites latest
geoengine apply --dev    # keep iterating

# --- Next release ---
# Bump version to 1.1.0, then:
geoengine apply          # saves snapshot, creates local tag 1.1.0 + latest

# --- Run a specific old build by its local tag ---
geoengine run --actor CLI --tag 1.0.0 --input input-file=/data.tif
```


# Collaborate on Workers
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-deployment/worker-collaboration

Share a worker's source code with your team using GitHub so multiple developers can contribute and push updates

GeoEngine workers are just files — `geoengine.yaml`, `pixi.toml`, your script, `geoengine.lock`, and usually a `tests/` folder. Putting them in a Git repository lets your whole development team work on the same worker, review changes, and push new versions independently.

***

## Step 1: Create a GitHub Repository

Go to [github.com](https://github.com) and create a new repository. Name it after your worker (e.g. `land-cover-classifier`). Leave it empty — no README, no `.gitignore` — you'll push the worker directory as the initial commit.

***

## Step 2: Initialise Git in Your Worker Directory

From inside the worker directory, run:

```bash theme={null}
echo "# land-cover-classifier" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin <repo_link>
git push -u origin main
```

Replace `<repo_link>` with the HTTPS or SSH URL from your GitHub repo (e.g. `https://github.com/your-org/land-cover-classifier.git`).

Then add the rest of the worker files:

```bash theme={null}
git add geoengine.yaml pixi.toml geoengine.lock tests/ *.py   # or *.R for R workers
git commit -m "add worker files"
git push
```

<Note>
  Commit `geoengine.lock` — it stores the worker ID that ties local builds to the cloud registry. Without it, teammates who clone the repo will get a fresh ID and create a separate worker instead of sharing yours.
</Note>

***

## Step 3: Teammates Clone and Apply

Anyone on the team can clone the repo and apply the worker locally:

```bash theme={null}
git clone <repo_link>
cd land-cover-classifier
geoengine lint
geoengine apply --dev
geoengine test
```

Because `geoengine.lock` is committed, everyone works against the same worker ID. Local builds stay on each person's machine — nothing is shared until someone runs `geoengine push`.

***

## Step 4: Pushing Changes

The normal development loop for each contributor:

```bash theme={null}
# Pull the latest changes
git pull

# Make your edits, then apply locally and run worker tests
geoengine lint
geoengine apply --dev
geoengine test

# When ready to release, bump version/local_tag in geoengine.yaml, then:
geoengine lint
geoengine test
geoengine apply        # production apply — builds versioned image
geoengine push         # publish to the cloud

# Commit and push the source changes
git add geoengine.yaml pixi.toml tests/ *.py
git commit -m "feat: add confidence threshold input (v1.1.0)"
git push
```

Any team member with access to the same Nika tenant can run `geoengine push` and the worker will appear under the same entry in the cloud registry — no extra setup needed.

***

## Known Limitations

**Versioning is on you.** GeoEngine enforces that each production apply uses a version that is greater than or equal to the highest version already recorded locally — but it does not enforce coordination between different machines. If two developers both bump to `1.1.0` in their local `geoengine.yaml` and try to push, GeoEngine will accept both applies locally. Agree on version numbers and local tags with your team before doing a production apply, and use the Git commit as the source of truth for what version is current.

**First push wins for a given version.** If two teammates both apply and push the same version (e.g. `1.1.0`), only the first push will succeed; subsequent pushes of the same version will be rejected. Coordinate releases, or use a simple rule: the person who merged the PR does the push.

**Dev builds are local only.** `geoengine apply --dev` never touches the cloud. Only production applies (`geoengine apply` without `--dev`) produce images that can be pushed.


# Access Job Outputs
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-usage/access-job-outputs

View job history and access the outputs of your custom geoprocessing jobs directly inside the QGIS and ArcGIS NIKA plugin.

On both versions of the plugin, you can access the job history by clicking the "Job History" button in the NikaPlanet panel. The panel lets you view the history of all your jobs, both past and active.

The job history panel is searchable by worker name, version, job ID.

<img alt="QGIS Job History" />

By clicking "filters", you can fine-tune the search results to specific workers, versions, teams, or dates:

<img alt="QGIS Filters" />

If a job has outputs, you can click the "outputs" tab to view the outputs. The outputs window supports multi-select as well as downloading and adding the files as layers.

<img alt="QGIS Outputs" />

<Warning>
  Outputs will only be available for 3 days after the job completes, so be sure to download them if you need them after that.
</Warning>


# Setup the Plugin in GIS
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-usage/setup-plugin-in-gis

Install and configure the NIKA Planet plugin in QGIS or ArcGIS to run custom geoprocessing workers directly from your GIS.

<div />

<Tabs>
  <Tab title="QGIS">
    ## Installing the plugin

    The QGIS plugin for NikaPlanet is available [here](https://github.com/NikaGeospatial/nikaplanet-qgis-plugin).

    To install the plugin:

    1. On the github repository page, click on the code button and select "Download ZIP"
       <img alt="QGIS Zip Download" />
    2. In QGIS, go to the "Plugins" menu (upper left) and select "Manage and Install Plugins..."
       <img alt="QGIS Plugin Menu" />
    3. Click the "Install Plugin From ZIP" button, then click the "..." button and select the downloaded ZIP file
       <img alt="QGIS Install Plugin From ZIP" />
    4. Click the "Install Plugin" button
    5. The plugin will be installed and you can now use it to connect to NikaPlanet

    ## Logging in to NikaPlanet

    Logins are shared between the NikaPlanet website and the QGIS plugin. If you are already logged in to NikaPlanet, you simply need to authorize the plugin to access your account.

    1. In QGIS, click the "NikaPlanet" button in the top bar. It is generally located beside the Python button.
       <img alt="QGIS Plugin Button" />
    2. If this is your first time logging in, you will be prompted to authorize the plugin to access your account. Click the "Sign in with NikaPlanet" button.
       <img alt="QGIS Login Prompt" />
    3. You will be redirected to the NikaPlanet login page. Enter your NikaPlanet credentials and click the "Sign in" button.
       <img alt="NikaPlanet Login" />
    4. You will be redirected back to QGIS and the NikaPlanet panel will automatically navigate to the dashboard. Click the "Geoengine Workers" button to view your workers.
       <img alt="QGIS Landing" />
  </Tab>

  <Tab title="ArcGIS Pro">
    ## Installing the plugin

    The ArcGIS Pro plugin is currently not available for download. Please contact us at [support@nikaplanet.com](mailto:support@nikaplanet.com) if you are interested in using the plugin.

    ## Logging in to NikaPlanet

    Logins are shared between the NikaPlanet website and the ArcGIS Pro plugin. If you are already logged in to NikaPlanet, you simply need to authorize the plugin to access your account.

    1. In ArcGIS Pro, click the "Nika" tab in the top bar, then click the "Show Panel" button.
    2. If this is your first time logging in, you will be prompted to authorize the plugin to access your account. Click the "Sign in with NikaPlanet" button.
       <img alt="ArcGIS Login Prompt" />
    3. You will be redirected to the NikaPlanet login page. Enter your NikaPlanet credentials and click the "Sign in" button.
       <img alt="NikaPlanet Login" />
    4. You will be redirected back to ArcGIS Pro and the NikaPlanet panel will automatically navigate to the dashboard. Click the "Geoengine Workers" button to view your workers.
       <img alt="ArcGIS Landing" />
  </Tab>
</Tabs>


# Submit a Job
Source: https://docs.nikaplanet.com/guides/custom-geoprocess-usage/submitting-a-job

Submit a custom geoprocessing job to a deployed NIKA worker from QGIS or ArcGIS, and track its progress from the plugin.

<div />

<Tabs>
  <Tab title="QGIS">
    To submit a job, your team (or a team you have access to) must have a worker deployed to their workspace. To learn more about deploying a worker, see the [Geoengine deployment](/guides/custom-geoprocess-deployment/step-by-step) guide.

    1. Identify the worker you want to run. Take note of the worker's name and version.
       <img alt="QGIS Worker List" />
    2. Click "select this version" to open the job dialog.
    3. Fill in the required input parameters and choose an appropriate machine type. Note that larger machines may take longer to start up.
       <img alt="QGIS Input Parameters" />
    4. Configure what you want to do after the job completes:
       * Download the outputs to your local machine
       * Add the outputs as layers to your QGIS project
         <img alt="QGIS Post Job Behavior" />
    5. Click the "Submit Job" button to submit the job. If you choose to download the outputs, you will be prompted to select a folder to download the outputs to.
    6. The job will be submitted and you will be able to view the job in the "Job History" panel.
       <img alt="QGIS Job List" />
    7. Once the job completes, you will be able to view the outputs by clicking on the job in the "Job History" panel and clicking on the "outputs" tab.
       <img alt="QGIS Outputs" />
  </Tab>

  <Tab title="ArcGIS Pro">
    To submit a job, your team (or a team you have access to) must have a worker deployed to their workspace. To learn more about deploying a worker, see the [Geoengine deployment](/guides/custom-geoprocess-deployment/step-by-step) guide.

    1. Identify the worker you want to run. Take note of the worker's name and version.
       <img alt="ArcGIS Worker List" />
    2. Click "select this version" to open the job dialog.
    3. Fill in the required input parameters and choose an appropriate machine type. Note that larger machines may take longer to start up.
       <img alt="ArcGIS Input Parameters" />
    4. Configure what you want to do after the job completes:
       * Download the outputs to your local machine
       * Add the outputs as layers to your ArcGIS Pro project
         <img alt="ArcGIS Post Job Behavior" />
    5. Click the "Submit Job" button to submit the job. If you choose to download the outputs, you will be prompted to select a folder to download the outputs to.
    6. The job will be submitted and you will be able to view the job in the "Job History" panel.
       <img alt="ArcGIS Job List" />
    7. Once the job completes, you will be able to view the outputs by clicking on the job in the "Job History" panel and clicking on the "outputs" tab.
       <img alt="ArcGIS Outputs" />
  </Tab>
</Tabs>


# AI Coding in Notebook
Source: https://docs.nikaplanet.com/guides/data-analysis/ai-coding-in-notebook

Learn how to use AI-powered coding features including quick edits, error resolution, and intelligent code suggestions in Nika notebooks

Learn how to leverage AI-powered features in Nika notebooks for faster coding, error resolution, and intelligent code suggestions. Use built-in AI tools to enhance your development workflow.

## Step 1: Quick AI Edit

### Built-in AI Suggestions

1. **Trigger AI Edit**: Press `Cmd/Ctrl + K` or click the AI edit button in the code block toolbar
2. **AI Analyzes Code**: AI reviews your code and suggests improvements
3. **Green Suggestions**: AI suggestions appear in green text
4. **Preview Execution**: Code runs with suggested changes even before accepting

### Accepting Changes

* **Line by Line**: Accept individual suggestions one at a time
* **Accept All**: Accept all AI suggestions at once
* **Undo Actions**: Use `Ctrl + Z` to undo accept/reject actions
* **Preview Mode**: See how code performs with suggestions before committing

### AI Edit Features

* **Context-Aware**: AI understands your notebook's full context
* **Smart Suggestions**: Intelligent code improvements and optimizations
* **Real-time Preview**: Test suggested changes immediately
* **Flexible Control**: Accept, reject, or modify suggestions as needed

<img alt="Quick AI Edit" />

## Step 2: Error Resolution with GAIA

### "Resolve in GAIA" Button

When code encounters errors:

1. **Error Occurs**: Code execution fails with detailed error message
2. **Click "Resolve in GAIA"**: Click the blue button in the error output
3. **AI Agent Activation**: Nika's AI agent analyzes the entire notebook context
4. **Comprehensive Analysis**: AI looks at the bigger picture, not just the error

### GAIA's Analysis

* **Full Context**: Analyzes entire notebook, not just the error line
* **Dependency Tracking**: Understands library imports and dependencies
* **Data Flow**: Tracks how data flows through your analysis
* **Best Practices**: Suggests improvements based on coding standards

<img alt="Resolve in GAIA Button" />

## Step 3: GAIA Chat Interface

### AI-Powered Chat

After clicking "Resolve in GAIA":

1. **Chat Panel Opens**: GAIA chat panel appears on the right side
2. **Error Context**: AI shows understanding of the error and notebook context
3. **Interactive Chat**: Ask questions and get AI assistance
4. **Streaming Responses**: See AI responses stream in real-time

### Chat Features

* **Natural Language**: Ask questions in plain English
* **Code Modifications**: AI can modify your notebook directly
* **Explanation**: Get detailed explanations of errors and solutions
* **Step-by-Step**: Receive guided solutions for complex problems

### Example Chat Interaction

```
User: "can you fix it?"
GAIA: "I see the issue. The Google Earth Engine collection query is being aborted because it's trying to retrieve too many elements at once. Let me fix this by implementing pagination..."
```

<img alt="GAIA Chat Interface" />

## Step 4: AI-Powered Code Execution

### Streaming AI Execution

* **Real-time Modifications**: AI can modify your notebook as you chat
* **Direct Integration**: Changes appear directly in your code blocks
* **Context Preservation**: AI maintains your notebook's structure and flow
* **Immediate Testing**: Modified code can be executed right away

### AI Model Selection

* **GPT-4.1-mini**: Fast and efficient AI model for quick responses
* **Context-Aware**: Model understands your specific notebook context
* **Error-Specific**: Tailored responses based on the exact error encountered
* **Learning**: AI learns from your coding patterns and preferences

## Step 5: Advanced AI Features

### Intelligent Code Suggestions

* **Auto-completion**: AI suggests code completions as you type
* **Import Optimization**: Automatically suggest and add required imports
* **Error Prevention**: Catch potential errors before they occur
* **Performance Optimization**: Suggest more efficient code patterns

### Context-Aware Assistance

* **Notebook History**: AI remembers previous code blocks and outputs
* **Data Understanding**: AI understands your data structures and types
* **Library Knowledge**: AI knows about available libraries and their usage
* **Best Practices**: Suggest improvements based on coding standards

## Next Steps

Now that you can use AI coding features:

1. **Practice AI Edit**: Try `Cmd/Ctrl + K` on your code blocks
2. **Test Error Resolution**: Use "Resolve in GAIA" when you encounter errors
3. **Explore Chat**: Ask GAIA questions about your code and data
4. **Learn Patterns**: Observe how AI suggests improvements

Happy AI-powered coding!


# Create a Notebook to Start Analysis
Source: https://docs.nikaplanet.com/guides/data-analysis/create-your-first-notebook

Learn how to create notebooks in NikaWorkspace for data analysis with collaborative features and auto-saving

Learn how to create notebooks in NikaWorkspace for data analysis. Notebooks are auto-saved and persisted across sessions, allowing you and your team members to collaborate on the same notebook at any time.

## Step 1: Create a Blank Notebook

### Click the "+" Icon

1. **Navigate to Notebooks**: Click on "Notebooks" in the left sidebar
2. **Click "+" Button**: Click the "+" button in the notebook list
3. **Select "Blank Notebook"**: Choose "Blank Notebook" from the dropdown menu
4. **Notebook Created**: A new blank notebook opens automatically

<img alt="Create Blank Notebook" />

### Auto-Save Feature

* **Everything Auto-Saved**: All changes are automatically saved
* **No Manual Saving**: No need to click save buttons
* **Cross-Session Persistence**: Notebook persists across browser sessions
* **Team Sync**: Changes sync automatically with team members

## Step 2: Rename Your Notebook

### Edit the Title

1. **Click Title Area**: Click on the notebook title at the top left
2. **Type New Name**: Enter a descriptive name for your notebook
3. **Auto-Save**: The new name is automatically saved
4. **Professional Naming**: Use clear, descriptive names like "Data Analysis Project" or "Machine Learning Model"

<img alt="Rename Notebook" />

### Naming Best Practices

* **Descriptive Names**: Use names that describe the content or purpose
* **Date Format**: Include dates if relevant (e.g., "Analysis\_2025\_08\_05")
* **Project Context**: Include project or client names if applicable
* **Version Numbers**: Add version numbers for iterative work

## Step 3: Alternative - Duplicate Existing Notebook

### Right-Click Method

1. **Find Notebook**: Locate the notebook you want to duplicate in the list
2. **Right-Click**: Right-click on the notebook name
3. **Select "Duplicate"**: Choose "Duplicate" from the context menu
4. **New Copy Created**: A copy of the notebook is created with "(Copy)" suffix

<img alt="Duplicate Notebook" />

### When to Duplicate

* **Template Use**: Duplicate notebooks that serve as templates
* **Version Control**: Create copies before making major changes
* **Team Sharing**: Duplicate shared notebooks via link from another workspace to share notebook with others securely
* **Experiment Safely**: Test changes on a copy before modifying original

## Step 4: Add Content as Blocks

### Adding New Blocks

#### Method 1: Click "+" Icon

1. **Find "+" Button**: Look for the "+" icon on the left of any row
2. **Click "+"**: Click the "+" button to add a new block
3. **Select Block Type**: Choose from the available block types
4. **Block Added**: New block appears below the current row

#### Method 2: Keyboard Shortcut

1. **Press "/"**: Type "/" in any empty row to trigger block selection
2. **Choose Block**: Select the desired block type from the menu
3. **Block Created**: New block is created with the selected type

<img alt="Cool Blocks Available" />

### Block Toolbar

The floating toolbar provides quick access to:

* **Code Block**: `< >` icon
* **Alert Block**: `▲` icon
* **Headings**: H1, H2, H3 options
* **Lists**: Numbered, bulleted, and checkbox lists
* **Media**: Images, video, audio, and file attachments
* **Formatting**: Text blocks, tables, and emojis

### Block Types Available

#### Code Block

* **Python Code**: Write and execute Python code
* **Kernel Integration**: Runs in the selected VM kernel
* **Output Display**: Shows results, plots, and errors
* **Variable Persistence**: Variables persist across cells

#### Alert Block

* **Important Information**: Highlight important notes with blue info boxes
* **Warning Messages**: Display warnings and cautions
* **Info Boxes**: Provide additional information with white 'i' icon
* **Customizable**: Choose different alert styles

#### Content Blocks

* **Headings**: Create section headers (H1, H2, H3)
* **Paragraphs**: Add plain text paragraphs
* **Lists**: Create bulleted lists (•), numbered lists (1.), and checkboxes (☐)
* **Tables**: Create data tables with grid layout

#### Media Blocks

* **Images**: Insert images or GIFs to your notebook
* **Video Clips**: Add video content to your analysis
* **Audio**: Include audio files for multimedia notebooks
* **File Attachments**: Attach documents and other files

## Key Features

### Auto-Save and Persistence

* **Real-time Save**: Changes are saved automatically
* **No Manual Save**: No need to click save buttons
* **Cross-session**: Notebook persists across browser sessions
* **Team Sync**: Changes sync with team members

### Collaborative Features

* **Multiple Users**: Multiple team members can work simultaneously
* **Live Cursors**: See where others are working
* **Change Indicators**: Visual indicators for recent changes
* **Auto-sync**: Changes sync automatically across users

### Enhanced Over Jupyter

* **Rich Media**: Support for images, videos, and audio
* **Interactive Lists**: Checkbox lists and interactive elements
* **Alert Blocks**: Highlight important information
* **Better UI**: Modern, intuitive interface
* **Team Collaboration**: Real-time collaborative editing

## Best Practices

### Notebook Organization

* **Clear Structure**: Organize notebooks logically with headings
* **Descriptive Names**: Use clear, descriptive names
* **Documentation**: Add markdown cells for documentation
* **Modular Code**: Break code into logical sections

### Content Creation

* **Use Alerts**: Highlight important information with alert blocks
* **Rich Media**: Include images and videos to enhance analysis
* **Interactive Elements**: Use checkboxes and lists for organization
* **Clear Documentation**: Document your analysis process

### Collaboration

* **Communication**: Communicate with team members
* **Clear Comments**: Add clear comments to your code
* **Regular Updates**: Keep notebooks current and updated
* **Share Knowledge**: Use notebooks to share knowledge

## Next Steps

Now that you've created your notebook:

1. **Add Content**: Start adding code blocks and documentation
2. **Run Code**: Learn about [Running Code in Notebook](/guides/data-analysis/run-code-in-notebook)
3. **Use Libraries**: Explore [Supported Python Libraries](/guides/data-analysis/supported-python-libraries)
4. **Publish**: [Publish Your Notebook](/guides/data-analysis/publish-notebook) to share with others

Happy analyzing!


# GDAL and CUDA Installation
Source: https://docs.nikaplanet.com/guides/data-analysis/gdal-cuda-installation

GDAL and CUDA are pre-installed on all ephemeral VM kernels for geospatial analysis and GPU acceleration

GDAL and CUDA are pre-installed on all ephemeral VM kernels that your notebooks have direct access to. No manual installation required.

## Pre-Installed Software

### Available Configurations

All VM kernels come with:

* **GDAL 3.9.1**: Geospatial Data Abstraction Library for raster and vector data
* **CUDA 12.2**: NVIDIA CUDA for GPU acceleration
* **Python 3.10/3.11**: Multiple Python versions available

### Kernel Selection

When starting your machine, you can choose from:

* **Python 3.10, GDAL 3.9.1 CUDA 12.2**
* **Python 3.11, GDAL 3.9.1 CUDA 12.2**
* **Python 3.10, GDAL 3.9.1 CUDA 12**

<img alt="GDAL CUDA Pre-installed" />

## Ready to Use

### No Installation Required

* **Pre-configured**: All geospatial libraries are ready to use
* **GPU Ready**: CUDA drivers and libraries are installed
* **Immediate Access**: Start analyzing geospatial data right away

### Direct Access

* **Workspace Integration**: Direct access to workspace files
* **Large Dataset Support**: Optimized for TB-PB sized geospatial data
* **Performance Optimized**: GPU acceleration for raster processing

## Usage Examples

### GDAL Operations

```python theme={null}
import rasterio
import geopandas as gpd

# Read raster data
with rasterio.open('/workspace/data/satellite.tif') as src:
    data = src.read()

# Read vector data
gdf = gpd.read_file('/workspace/data/shapefile.shp')
```

### CUDA Acceleration

```python theme={null}
import cupy as cp
import numpy as np

# GPU-accelerated array operations
gpu_array = cp.array(np.random.random((1000, 1000)))
result = cp.linalg.svd(gpu_array)
```

## Next Steps

Now that you have GDAL and CUDA ready:

1. **Start Analysis**: Begin your geospatial analysis immediately
2. **Load Data**: Access your workspace data files
3. **Use GPU**: Leverage CUDA for accelerated processing
4. **Scale Up**: Work with large geospatial datasets efficiently

Happy analyzing!


# Publish a Notebook (with Access Control)
Source: https://docs.nikaplanet.com/guides/data-analysis/publish-notebook

Learn how to publish your notebook with team-only or public access, including thumbnail generation and collaboration features

Learn how to publish your NikaWorkspace notebook for team collaboration or public sharing. The process is very similar to publishing maps - you can publish with different names, generate thumbnails using AI, and control access settings.

## Step 1: Access Publish Options

### Method 1: Right-Click on Notebook List

1. **Open Notebook List**: Navigate to your notebooks in the left panel
2. **Right-click Notebook**: Right-click on the notebook you want to publish
3. **Select "Publish"**: Choose the publish option from the context menu

<img alt="Right-click to Publish" />

### Method 2: Publish Button in Notebook

1. **Open Your Notebook**: Open the notebook you want to publish
2. **Find Publish Button**: Look for the publish button in the top toolbar
3. **Click Publish**: Click the publish button to open the publish dialog

## Step 2: Fill in Compulsory Fields

### Required Information (marked with asterisk \*)

1. **Title**\*: Enter a descriptive name for your published notebook
2. **Version**\*: Specify the version number (e.g., "1.0.0")
3. **Category**\*: Add at least one category by clicking "+ Add Category"

### Optional Information

* **Description**: Add a detailed description of the notebook content (optional)
* **Tags**: Add relevant tags for categorization (optional)

### Thumbnail Options

You have three options for creating a thumbnail:

#### Option 1: URL

* Enter an image URL in the "Image URL" field

#### Option 2: Upload

* Click "Upload" and select an image file from your computer

#### Option 3: AI Generate (Recommended if no thumbnail)

* Click "AI Generate" with the sparkle icon
* AI will automatically create a relevant thumbnail based on your notebook content

### Access Control Settings

* **Public**: Anyone from public can discover and access the notebook. All public content can be found at [Nika Hub](https://planet.nika.eco/en/hub)
* **Password Protected**: Anyone with the link can access with password. Share the link and password with specific users
* **Restricted (Team Only)**: Only people from your organization can discover and access. All team published content can be found at [Team Hub](https://planet.nika.eco/en/dashboard/team-hub) if you are already signed in

<img alt="Publish Dialog with Required Fields" />

## Step 3: Update Published Notebook

### Access Update Options

1. **Open Published Notebook**: Open your published notebook
2. **Find Update Button**: Look for the update option in the publish dialog
3. **Modify Information**: Change any of the following:
   * Title and version
   * Description
   * Categories
   * Thumbnail (URL, upload, or AI generate)
   * Tags
   * Access Control (Public, Password Protected, or Team Only)

### Update Process

1. **Make Changes**: Modify the desired information
2. **Review Settings**: Double-check all settings
3. **Click "Update"**: Click the update button to republish changes
4. **Alternative: Unpublish**: Use "Unpublish" button to remove from public/team access

<img alt="Update Published Notebook Dialog" />

## Step 4: View Published Notebook

### Access Published Notebook

1. **Click Arrow Icon**: Click the arrow icon at the top right of the publish dialog
2. **New Tab Opens**: A new browser tab will open with your published notebook
3. **Static View**: The notebook opens in a static, view-only format

### Published Notebook Features

* **View-Only Access**: Users can view but not edit the notebook
* **Code and Output**: All code cells and their outputs are visible
* **Interactive Elements**: Notebook maintains interactive features
* **Public Hub**: If published publicly, the notebook appears in the NikaHub

<img alt="Published Notebook View" />

## Publishing Options

### Team-Only Publishing

* **Restricted Access**: Only team members can access the notebook
* **Collaboration Features**: Full collaborative editing capabilities
* **Team Management**: Team admins can manage access
* **Private Sharing**: Share within your organization only

### Password Protected Publishing

* **Controlled Access**: Anyone with the link can access with password
* **Secure Sharing**: Share the link and password with specific users
* **Flexible Control**: Control who can access your notebook
* **Easy Management**: Change or remove password as needed

### Public Publishing

* **Public Access**: Anyone can view the published notebook
* **Hub Listing**: Notebook appears in the [public notebook hub](https://planet.nika.eco/en/hub/notebooks)
* **Community Sharing**: Share with the broader community
* **Attribution**: Proper attribution to your organization

## Best Practices

### Before Publishing

* **Complete Your Analysis**: Ensure all code cells are executed and results are visible
* **Add Documentation**: Include markdown cells explaining your analysis
* **Test Functionality**: Test all interactive elements
* **Optimize Performance**: Ensure good loading performance

### Content Quality

* **Accurate Analysis**: Ensure analysis accuracy and validity
* **Clear Visualizations**: Create clear and informative visualizations
* **Proper Documentation**: Use appropriate documentation and comments
* **Clear Documentation**: Provide clear descriptions and documentation

### Publishing Strategy

* **Consistent Naming**: Use consistent naming conventions
* **Regular Updates**: Keep published notebooks current and updated
* **Quality Assurance**: Implement quality assurance processes
* **Community Engagement**: Engage with community feedback

## Troubleshooting

### Common Issues

* **Publishing Fails**: Check that all required fields (marked with \*) are filled
* **Thumbnail Issues**: Use AI generation if you don't have a thumbnail
* **Permission Problems**: Verify access control settings (Public, Password Protected, or Team Only)
* **Update Issues**: Ensure you click "Update" after making changes

### Solutions

* **Validate Content**: Ensure all cells execute without errors
* **Check Required Fields**: Review all fields marked with asterisks
* **Test Locally**: Test notebook functionality before publishing
* **Contact Support**: Contact support for persistent issues

## Next Steps

Now that you've published your notebook:

1. **Share**: Share your published notebook with your team or community
2. **Monitor**: Monitor engagement and feedback
3. **Update**: Keep your notebook current and updated
4. **Engage**: Engage with the community and respond to feedback

Happy publishing!


# Run the Code in Notebook
Source: https://docs.nikaplanet.com/guides/data-analysis/run-code-in-notebook

Learn how to run code in notebooks with hover menus, keyboard shortcuts, streaming execution, and AI-powered debugging

Learn how to run code in your NikaWorkspace notebooks with multiple execution methods, streaming output, and powerful debugging features. Code execution is streamed from the kernel, allowing you to close the workspace and return later to see results.

## Step 1: Run Individual Code Blocks

### Method 1: Hover Menu Run Button

1. **Hover Over Code Block**: Hover over any code block
2. **Click Run Button**: Click the play button (▶️) that appears in the hover menu
3. **Code Executes**: Code runs and output streams in below the block
4. **Status Updates**: Green checkmark shows successful execution

### Method 2: Keyboard Shortcut

1. **Select Code Block**: Click on the code block you want to run
2. **Press Shift+Enter**: Use the keyboard shortcut to execute
3. **Code Executes**: Code runs and cursor moves to next block
4. **View Results**: See streaming output in real-time

<img alt="Run Button in Hover Menu" />

## Step 2: Run All Code Blocks

### Run All Feature

1. **Click "Run All"**: Use the "Run All" button in the top-right toolbar
2. **Sequential Execution**: All codeNo Dragging Required blocks execute in order from top to bottom
3. **Progress Tracking**: Watch as each block executes in sequence
4. **Complete Execution**: All blocks finish with results displayed

### Clear All Outputs

* **Click "Clear All Outputs"**: Remove all execution results
* **Fresh Start**: Start with clean output areas
* **Re-run**: Execute blocks again as needed

<img alt="Run All Button" />

## Step 3: Handle Exceptions and Errors

### Exception Display

When code encounters errors:

* **Detailed Error Messages**: Full exception details are displayed
* **Traceback Information**: Complete stack trace for debugging
* **Error Context**: Shows exactly where the error occurred
* **Helpful Details**: Error messages provide debugging guidance

### AI-Powered Debugging

* **"Resolve in GAIA" Button**: Click to get AI assistance with errors
* **Smart Suggestions**: AI provides code fixes and explanations
* **Context-Aware Help**: AI understands your notebook context
* **Learn More**: See [AI Coding in Notebook](/guides/data-analysis/ai-coding-in-notebook) for detailed AI features

<img alt="Exception Handling with AI" />

## Step 4: Code Quality Features

### Real-Time Code Linting

* **Syntax Checking**: Python syntax is checked after each line change
* **Error Highlighting**: Syntax errors are highlighted immediately
* **Best Practices**: Suggestions for code improvements
* **Instant Feedback**: Get feedback as you type

### Autocompletion (Coming Soon)

* **Tab Key Trigger**: Press Tab to trigger code completion
* **Context-Aware**: Suggestions based on notebook context
* **Smart Predictions**: AI-powered code completion
* **Variable Recognition**: Understands variables in your notebook

## Step 5: Reorder Code Blocks

### Easy Block Reordering

1. **Use Arrow Buttons**: Click up/down arrow buttons in block toolbar
2. **Shift Blocks**: Move blocks up or down without dragging
3. **Visual Feedback**: See blocks move in real-time
4. **Maintain Order**: Keep logical flow of your analysis

### Block Management

* **Shift Up**: Move block to previous position
* **Shift Down**: Move block to next position
* **Dragging**: Dragging block for reordering in a longer range
* **Preserve Output**: Block outputs move with the code

<img alt="Block Reordering" />

## Step 6: Streaming Execution

### Background Execution

* **Streaming Output**: Results stream in real-time from kernel
* **Leave and Return**: Close workspace, return hours later
* **Persistent Execution**: Long-running code continues in background
* **Output Preservation**: All results are saved and displayed

### Long-Running Tasks

```python theme={null}
# Example: Long-running analysis
import time
import pandas as pd

# Load large dataset
print("Loading large dataset...")
data = pd.read_parquet('/workspace/data/massive_dataset.parquet')

# Process data in chunks
print("Processing data...")
for i in range(100):
    chunk = data[i*1000:(i+1)*1000]
    # Complex processing here
    time.sleep(1)  # Simulate processing time
    print(f"Processed chunk {i+1}/100")

print("Analysis complete!")
```

### Benefits of Streaming

* **No Time Pressure**: Start long tasks and walk away
* **Resource Efficiency**: Use compute resources effectively
* **Progress Monitoring**: Check progress when you return
* **Reliable Execution**: No interruption from browser closure

## Step 7: Code Execution Examples

### Basic Code Execution

```python theme={null}
# Simple data analysis
import pandas as pd
import numpy as np

# Load data
data = pd.read_csv('/workspace/data/sample.csv')
print(f"Dataset shape: {data.shape}")

# Basic statistics
print(f"Mean: {data['value'].mean()}")
print(f"Standard deviation: {data['value'].std()}")
```

### Library Installation

```python theme={null}
# Install required libraries
!pip install earthengine-api geemap geopandas

# Libraries are installed and ready to use
import ee
import geemap
import geopandas as gpd
```

### Error Handling Example

```python theme={null}
try:
    # Attempt to load data
    data = pd.read_csv('/workspace/data/missing_file.csv')
except FileNotFoundError as e:
    print(f"Error: {e}")
    print("Please check if the file exists in the workspace")
```

## Best Practices

### Code Organization

* **Logical Flow**: Arrange blocks in logical order
* **Clear Comments**: Add comments to explain your code
* **Modular Code**: Break complex tasks into smaller blocks
* **Error Handling**: Use try-catch blocks for robust code

### Execution Strategy

* **Test Small**: Run small code blocks first
* **Incremental Development**: Build analysis step by step
* **Save Results**: Save intermediate results for long tasks
* **Monitor Resources**: Keep track of memory and CPU usage

### Performance Tips

* **Use Streaming**: Leverage background execution for long tasks
* **Efficient Code**: Write optimized, vectorized code
* **Batch Processing**: Process data in manageable chunks
* **Resource Management**: Clean up large variables when done

## Troubleshooting

### Common Issues

* **Code Not Running**: Check if VM is started and ready
* **Syntax Errors**: Use the real-time linting to catch errors
* **Long Execution**: Use streaming execution for background tasks
* **Memory Issues**: Clear outputs or restart VM if needed

### Solutions

* **Restart VM**: Stop and restart if VM becomes unresponsive
* **Clear Outputs**: Use "Clear All Outputs" to free memory
* **AI Debugging**: Use GAIA for help with complex errors
* **Contact Support**: Get help for persistent issues

## Next Steps

Now that you can run code effectively:

1. **AI Assistance**: Learn about [AI Coding in Notebook](/guides/data-analysis/ai-coding-in-notebook) for debugging
2. **Install Libraries**: Check [Supported Python Libraries](/guides/data-analysis/supported-python-libraries)
3. **Start Machine**: Learn about [Starting Your Machine](/guides/data-analysis/start-machine)
4. **Publish Results**: [Publish Your Notebook](/guides/data-analysis/publish-notebook) to share your work

Happy coding!


# Start Machine
Source: https://docs.nikaplanet.com/guides/data-analysis/start-machine

Learn how to start and manage VM kernels for Nika notebooks with different CPU and GPU configurations

Learn how to start and manage VM kernels for your Nika notebooks. Choose from different CPU and GPU configurations to match your analysis needs.

## Step 1: Select Machine Type

### Available Configurations

Choose from these pre-configured options:

#### CPU Machines

| Machine | CPU Cores | RAM | Ready Time |
| - | - | - | - |
| **CPUx3** | 3 | 24 GB | \<30 sec |
| **CPUx7** | 7 | 53 GB | >2 min |
| **CPUx20** | 20 | 156 GB | >2 min |
| **CPUx42** | 42 | 326 GB | >2 min |

#### GPU Machines

| Machine | CPU Cores | RAM | GPU | GPU Memory | Ready Time |
| - | - | - | - | - | - |
| **Nvidia T4 x1** | 6 | 24 GB | 1x Tesla T4 | 16 GB | >2 min |
| **Nvidia T4 x2** | 14 | 50 GB | 2x Tesla T4 | 32 GB | >2 min |
| **Nvidia T4 x4** | 30 | 100 GB | 4x Tesla T4 | 64 GB | >2 min |
| **Nvidia H100 x1** | 24 | 210 GB | 1x H100 | 80 GB | >2 min |

<img alt="Machine Selection Options" />

## Step 2: Start Your Machine

### Quick Start

1. **Select Configuration**: Choose your desired machine type from the dropdown
2. **Click "Start Machine"**: Click the prominent white button
3. **Wait for Ready**: Machine will be ready in 15-40 seconds depending on type

### Start Times

* **CPUx3**: Under 30 seconds (fastest)
* **All other machines**: Over 2 minutes (varies by availability)

<img alt="Start Machine Button" />

## Step 3: Monitor Machine Status

### Status Indicators

Your machine status is shown as a colored indicator dot in the machine panel and the bottom-left icon. The color reflects the current state:

<div>
  <div>
    <span />

    <div>
      <strong>Green — Accessible</strong><br />
      Machine is running and ready to execute code.
    </div>
  </div>

  <div>
    <span />

    <div>
      <strong>Orange — Starting</strong><br />
      Machine is being provisioned. Applies to <em>Pending</em>, <em>Running</em> (container starting), and <em>Succeeded</em> states. Wait for it to turn green.
    </div>
  </div>

  <div>
    <span />

    <div>
      <strong>Red — Error</strong><br />
      Something went wrong. This covers:

      <ul>
        <li><strong>Failed</strong> — the machine crashed or encountered an error.</li>
        <li><strong>Unavailable</strong> — the required cloud compute resources could not be provisioned after multiple auto-retries on NikaPlanet's backend. It could be due to overwhelming demand for this machine type by all cloud users. You will have to wait for the supply to increased by cloud service provider.</li>
      </ul>
    </div>
  </div>

  <div>
    <span />

    <div>
      <strong>Grey — Terminated</strong><br />
      Machine is stopped. No compute charges apply.
    </div>
  </div>
</div>

### Viewing Status

#### Method 1: Machine Panel

* **Hover over the indicator dot**: Shows detailed status information
* **View metrics**: Uptime, CPU usage, memory usage
* **Real-time updates**: Status updates automatically every 10 seconds

<img alt="Machine Status Panel" />

#### Method 2: Bottom Left Icon

* **Hover over machine icon**: Quick status overview
* **Visual indicator**: Colored dot matches the states above
* **Easy access**: Always visible in workspace

<img alt="Bottom Left Status Icon" />

## Step 4: Stop Machine

### Stop Process

1. **Click "Stop Machine"**: Click the white button in machine panel
2. **Immediate Stop**: Machine stops running immediately
3. **No Compute Cost**: No charges after stopping

### Benefits of Stopping

* **Save Resources**: Stop when not actively using
* **Cost Control**: No charges when stopped
* **Quick Restart**: Can restart anytime needed

<img alt="Stop Machine Button" />

## Best Practices

### Machine Selection

* **Start Small**: Begin with CPUx3 for simple analysis
* **Scale Up**: Upgrade to larger machines for complex tasks
* **GPU for ML**: Use GPU machines for machine learning workloads
* **Cost Consideration**: Larger machines consume more resources

### Resource Management

* **Stop When Done**: Stop machines when not actively working
* **Monitor Usage**: Check status regularly
* **Plan Sessions**: Start machines when ready to work

## Next Steps

Now that your machine is running:

1. **Start Coding**: Begin your analysis in the notebook
2. **Load Data**: Access your workspace files
3. **Use GPU**: Leverage GPU acceleration if available
4. **Monitor Performance**: Keep an eye on resource usage

Happy computing!


# Supported Python Libraries
Source: https://docs.nikaplanet.com/guides/data-analysis/supported-python-libraries

Learn about the Python libraries supported in NikaWorkspace for data analysis and geospatial processing

NikaWorkspace supports almost all open-source Python libraries as long as Jupyter supports them. You can install any library you need using `!pip install` in code blocks.

## Step 1: Installing Libraries

### Using pip install

```python theme={null}
# Install any library you need
!pip install library_name

# Example installations
!pip install pandas numpy matplotlib
!pip install scikit-learn tensorflow
!pip install geemap leafmap
```

### Installation Process

1. **Run Installation**: Execute the pip install command in a code cell
2. **Wait for Installation**: Installation completes automatically
3. **Restart Kernel**: Restart kernel if needed for some libraries
4. **Import and Use**: Import and use the library in subsequent cells

## Step 2: Popular Libraries

### Data Analysis

* **pandas**: Data manipulation and analysis
* **numpy**: Numerical computing
* **scipy**: Scientific computing
* **scikit-learn**: Machine learning

### Geospatial Libraries

* **geemap**: Google Earth Engine integration
* **leafmap**: Interactive mapping
* **geopandas**: Geospatial data analysis
* **rasterio**: Raster data processing
* **folium**: Interactive maps
* **pyproj**: Coordinate transformations

### Machine Learning

* **tensorflow**: Deep learning framework
* **pytorch**: Machine learning library
* **xgboost**: Gradient boosting
* **lightgbm**: Light gradient boosting

### Visualization

* **matplotlib**: Basic plotting
* **seaborn**: Statistical visualization
* **plotly**: Interactive plots
* **bokeh**: Interactive visualization

## Step 3: Geospatial Libraries

### Earth Engine Integration

```python theme={null}
# Install and use geemap
!pip install geemap

import geemap
import ee

# Initialize Earth Engine
ee.Initialize()

# Create a map
Map = geemap.Map()
Map.addLayer(ee.Image('USGS/SRTMGL1_003'), {}, 'SRTM')
Map
```

### Interactive Mapping

```python theme={null}
# Install and use leafmap
!pip install leafmap

import leafmap

# Create interactive map
m = leafmap.Map()
m.add_basemap('OpenStreetMap')
m
```

### Geospatial Analysis

```python theme={null}
# Install and use geopandas
!pip install geopandas

import geopandas as gpd

# Load geospatial data
gdf = gpd.read_file('/workspace/data/shapefile.shp')
gdf.plot()
```

## Step 4: Machine Learning Libraries

### Deep Learning

```python theme={null}
# Install and use TensorFlow
!pip install tensorflow

import tensorflow as tf
print(f"TensorFlow version: {tf.__version__}")

# Check GPU availability
print(f"GPU available: {tf.config.list_physical_devices('GPU')}")
```

### Traditional ML

```python theme={null}
# Install and use scikit-learn
!pip install scikit-learn

from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

# Train model
model = RandomForestClassifier()
model.fit(X_train, y_train)
```

## Step 5: Data Visualization

### Static Plots

```python theme={null}
# Install and use matplotlib/seaborn
!pip install matplotlib seaborn

import matplotlib.pyplot as plt
import seaborn as sns

# Create plots
plt.figure(figsize=(10, 6))
sns.scatterplot(data=df, x='x', y='y')
plt.show()
```

### Interactive Plots

```python theme={null}
# Install and use plotly
!pip install plotly

import plotly.express as px

# Create interactive plot
fig = px.scatter(df, x='x', y='y', color='category')
fig.show()
```

## Step 6: Specialized Libraries

### Image Processing

* **opencv-python**: Computer vision
* **PIL/Pillow**: Image processing
* **scikit-image**: Image processing

### Statistical Analysis

* **statsmodels**: Statistical modeling
* **pingouin**: Statistical testing
* **scipy.stats**: Statistical functions

### Database Integration

* **sqlalchemy**: Database ORM
* **psycopg2**: PostgreSQL adapter
* **pymongo**: MongoDB driver

### Cloud Services

* **boto3**: AWS SDK
* **google-cloud-storage**: Google Cloud
* **azure-storage-blob**: Azure Storage

## Step 7: Library Management

### Version Management

```python theme={null}
# Check installed versions
!pip list

# Install specific versions
!pip install pandas==1.5.3

# Upgrade libraries
!pip install --upgrade library_name
```

### Environment Management

* **Automatic Installation**: Libraries install automatically
* **Version Compatibility**: System handles version conflicts
* **Dependency Resolution**: Automatic dependency management
* **Clean Environment**: Fresh environment for each session

### Best Practices

* **Install as Needed**: Install libraries when you need them
* **Check Compatibility**: Verify library compatibility
* **Use Virtual Environments**: Consider virtual environments for complex setups
* **Document Dependencies**: Keep track of required libraries

### Enterprise Feature: Library Persistence (Coming Soon)

* **Persistent Libraries**: Enterprise users can persist libraries across kernel sessions
* **GUI Management**: Manage persistent libraries through a user-friendly interface
* **Custom Environments**: Create and maintain custom library environments
* **Contact Support**: Email support request for early access to this feature

## Step 8: Troubleshooting

### Common Issues

* **Installation Fails**: Check library name and internet connection
* **Import Errors**: Restart kernel after installation
* **Version Conflicts**: Install compatible versions
* **Memory Issues**: Use smaller libraries or optimize code

### Solutions

* **Restart Kernel**: Often resolves import issues
* **Check Documentation**: Verify installation instructions
* **Alternative Libraries**: Use alternative libraries if needed
* **Contact Support**: Get help for persistent issues

### Performance Tips

* **Lazy Loading**: Import libraries only when needed
* **Memory Management**: Monitor memory usage
* **Efficient Libraries**: Use efficient library alternatives
* **Caching**: Cache results to avoid recomputation

## Next Steps

Now that you know about supported libraries:

1. **Install Libraries**: Start installing the libraries you need
2. **GDAL Setup**: GDAL is pre-installed — no setup required
3. **Run Code**: [Run Code in Notebook](/guides/data-analysis/run-code-in-notebook) with your libraries
4. **Publish**: [Publish Your Notebook](/guides/data-analysis/publish-notebook) with your analysis

Happy coding!


# Create New Flow
Source: https://docs.nikaplanet.com/guides/data-conversion-pipeline/create-new-flow

Learn how to create a new data conversion workflow and add nodes

## Opening the Workflow Panel

To create a new data conversion workflow:

1. Navigate to the **Workflows** section in the left panel
2. Click the **+** button next to the search bar, or
3. Click the **New Workflow** button on the right side of the main content area

<img alt="Create New Workflow Interface" />

## Adding Nodes to Your Workflow

Once you've created a new workflow, you can add different types of nodes:

1. Click the **Add Node** button at the top of the workflow canvas
2. Select from the available node types:
   * **Add Input** - For specifying data sources
   * **Add Conversion** - For data format transformations
   * **Add Output** - For defining output destinations

<img alt="Add Node Options" />

## Connecting Nodes

After adding nodes to your workflow:

1. Click and drag from the output port (right side) of one node
2. Connect it to the input port (left side) of another node
3. This creates a data flow connection between the nodes

The workflow canvas will show your connected nodes with visual connections indicating the data flow path.


# Edit Conversion Flow
Source: https://docs.nikaplanet.com/guides/data-conversion-pipeline/edit-conversion-flow

Configure input, conversion, and output nodes for your data pipeline

## Configuring Input Nodes

### Setting Input Sources

1. Click on an **Input Data** node to open its configuration panel
2. In the **Include Paths** section, add your data source paths:
   * All paths **must start with `/data/`** prefix
   * Use wildcards (e.g., `/data/*.tif`) to include multiple files
   * Add paths one at a time
   * Double click an existing path to modify the text

<img alt="Input Node Configuration" />

### Using Exclude Paths

To refine your input scope:

1. In the **Exclude Paths (Optional)** section, specify files to exclude
2. This is useful when using wildcards - you can include a broad pattern and then exclude specific unwanted files
3. Example: Include `/data/cwdz02/*.wd2` but exclude `/data/cwdz02/000casdas.wd2`

<img alt="Wildcard Include with Exclude Paths" />

### \[Advanced] Drag and Drop from Files Panel

For faster path entry:

1. Open the **Files** panel on the left
2. Select multiple files from the data lake filesystem
3. Drag and drop them directly into the input node panel's dropzone
4. This automatically adds all selected file paths that are valid for currently selected input data format

<img alt="Drag and Drop Files" />

## Configuring Conversion Nodes

### Setting Input and Output Formats

1. Click on a **Format Conversion** node
2. Configure the conversion parameters:
   * **Input Type** - Select the data type (Vector, Raster, etc.)
   * **Input Format** - Choose the source format (GeoJSON, KML, etc.)
   * **Output Type** - Select the target data type
   * **Output Format** - Choose the destination format (KMZ, Shapefile, etc.)
3. Check out [NikaFlow page](/nika-planet/nika-flow#geospatial-format-support) for latest supported input and output data type/formats

<img alt="Conversion Node Configuration" />

## Configuring Output Nodes

### Setting Output Destination

1. Click on an **Output Data** node
2. The **Data Type** and **Format** will automatically sync with the connected conversion node
3. Optionally set an **Output Folder Path**:
   * Must start with `/data/` and end with `/`
   * If left empty, outputs will be saved in the same folder as each source file

<img alt="Output Node Configuration" />


# Execute and Verify Pipeline
Source: https://docs.nikaplanet.com/guides/data-conversion-pipeline/execute-and-verify-pipeline

Run your data conversion workflow and monitor execution status

## Running Your Workflow

### Starting the Workflow

1. Once your workflow is configured with input, conversion, and output nodes, click the **Run Workflow** button in the top-right corner
2. The system will begin processing your data according to the workflow configuration

<img alt="Run Workflow Button" />

## Monitoring Execution

### Run History

After starting the workflow:

1. Check the **Run History** section in the workflow overview panel
2. You'll see entries showing:
   * Execution start time and date
   * Workflow status (started, completed, failed)
   * Node and edge count (e.g., "3n/2e" for 3 nodes and 2 edges)

### Real-time Updates

* The UI updates progressively every 10 seconds during execution
* Monitor the status in the Run History section
* Watch for any error messages or warnings

## Handling Errors and Warnings

### Error Detection

If there are issues with your workflow configuration:

1. The system will display a warning panel showing the number of issues found
2. Each issue will be clearly explained with specific details
3. Common issues include:
   * Invalid file extensions for specified formats
   * Missing required configuration fields
   * Invalid file paths

<img alt="Error Detection and Warnings" />

### Fixing Issues

1. Review the error messages carefully
2. Check that file extensions match the expected format (e.g., `.geojson` for GeoJSON files)
3. Verify that all required fields are properly configured
4. Make necessary corrections and re-run the workflow

## Workflow Overview

The workflow overview panel provides a summary of your pipeline:

* **Inputs** - Lists all input nodes and their configurations
* **Conversions** - Shows conversion nodes and their transformations
* **Outputs** - Displays output nodes and their destinations

This overview helps you verify that your workflow is properly configured before execution.


# Connect to MotherDuck
Source: https://docs.nikaplanet.com/guides/database-management/connect-motherduck

Connect to MotherDuck cloud database service

Connect to MotherDuck for cloud-native DuckDB with serverless architecture.

## Step 1: Add MotherDuck Connection

1. Navigate to **Database Management**
2. Click **"Add External Database"**
3. Select **"MotherDuck"** from the database types

## Step 2: Create MotherDuck Access Token

1. Go to [https://app.motherduck.com/settings/tokens](https://app.motherduck.com/settings/tokens) after login, to create a new access token
2. Copy the value of the new token

<img alt="Connect MotherDuck Step 1" />

## Step 3: Configure MotherDuck

1. **Service Token**: Your MotherDuck service token
2. **Database Name**: Target database (optional)
3. **Region**: Select your preferred region
4. Click **"Test Connection"**

<img alt="Connect MotherDuck Step 2" />

## Step 3: Save Connection

1. Verify connection status shows **"Connected"**
2. Click **"Save Connection"**
3. Your MotherDuck database is now available for queries

<Note>
  MotherDuck provides serverless DuckDB with automatic scaling and built-in spatial support.
</Note>


# Connect to PostgreSQL
Source: https://docs.nikaplanet.com/guides/database-management/connect-postgres

Connect to external PostgreSQL databases like Supabase

Connect to external PostgreSQL databases including Supabase for spatial data analysis.

## Step 1: Add Database Connection

1. Go to **Database Management**
2. Click **"Add External Database"**
3. Select **"PostgreSQL"** from the database types

## Step 2: Get Connection String from your Postgres Database

1. Go to your database provider such as [Supabase](https://supabase.com/) in this example
2. Creacte new or select an existing postgres database project
3. Click `Connect` at its top bar
4. Copy the value of the session pool url and replace the password placeholder with your actual password

<img alt="Connect PostgreSQL Step 2-1" />

<img alt="Connect PostgreSQL Step 2-2" />

## Step 3: Enter Connection String in Creation Connection Dialog

1. **Host**: Your PostgreSQL server address
2. **Port**: Default 5432 (or your custom port)
3. **Database**: Target database name
4. **Username**: Your database username
5. **Password**: Your database password
6. **SSL Mode**: Required for Supabase connections

<img alt="Connect PostgreSQL Step 3" />

## Step 4: Test and Save

Click **"Save Connection"**

<Note>
  For Supabase, use your project's connection string and ensure SSL is enabled.
</Note>


# Create Managed DuckDB
Source: https://docs.nikaplanet.com/guides/database-management/create-managed-duckdb

Set up a new managed DuckDB instance for spatial SQL queries

Create a new DuckDB instance managed by Nika for high-performance spatial data analysis.

## Step 1: Access Database Management

1. Navigate to **Database Management** in your NikaWorkspace
2. Click **"Create New Database"**
3. Select **"Managed DuckDB"** from the database types

<img alt="Create Managed DuckDB Step 1" />

## Step 2: Configure Database

1. Enter a **database name** (e.g., "spatial\_analysis")
2. Choose **storage location** (Nika cloud or local)
3. Enable **spatial extensions** for geospatial functions
4. Click **"Create Database"**

<img alt="Create Managed DuckDB Step 2" />

## Step 3: Verify Creation

Your new managed DuckDB instance is ready for spatial SQL queries with built-in geospatial functions.

<Note>
  Managed DuckDB instances include spatial extensions by default and support direct file querying from your workspace.
</Note>


# Query Managed DuckDB
Source: https://docs.nikaplanet.com/guides/database-management/query-managed-duckdb

Execute SQL queries using built-in editor or AI generation

Execute spatial SQL queries on your managed DuckDB instance using the built-in query editor or AI assistance.

## Step 1: Open Query Editor

1. Click `Databases` in the left bar of a NikaWorkspace
2. Select a **managed DuckDB** from the database list
3. Double click or right click to select **"Open SQL Query Editor"**
4. The query interface opens with your database context

## Step 2: Open Query Editor

1. Click `Files` in the left bar
2. Right click on a spatial file of your interest to `Copy Path`

<img alt="Query Managed DuckDB Step 1" />

## Step 3: Write SQL Query

### Manual SQL Writing

1. Type your spatial SQL query in the editor of a NikaWorkspace
2. Use spatial functions from DuckDB SQL like `ST_READ()`, `ST_AsText()`, `ST_DWithin()`
3. Click **"Execute"** to run the query

<img alt="Query Managed DuckDB Step 2" />

### AI-Powered SQL Generation

1. \[Optional] Select AI model (GPT-4, Claude, etc.)
2. Describe your query in natural language
3. Click **"Generate SQL"** button
4. AI generates SQL based on your table schema

<img alt="Query Managed DuckDB Step 3" />

## Step 4: View Results

1. Query results display in the results table
2. **Download CSV** for data export
3. **Add to Map** to visualize spatial results (WIP)

<Note>
  AI SQL generation understands your table schema if you mention it with '/' trigger and suggests optimal spatial queries for your data.
</Note>

<img alt="Query Managed DuckDB Step 4" />


# Conducting AI-Supported Field Surveys
Source: https://docs.nikaplanet.com/guides/field-survey/ai-audio-gps

Learn how to conduct an environmental field survey using NikaField's voice-to-form AI, offline audio transcription, and GPS tracking.

This guide will walk you through setting up and executing a survey using **NikaField**. You will learn how to leverage on-device AI for seamless voice-to-form auto-population while tracking your movement with integrated GPS.

## Prerequisites

* **NikaField Application** installed on your mobile device.
* Pre-configured survey plans and schemas on your Nika dashboard.

## Step 1: Selecting the Survey

When you arrive at the survey site, open NikaField. You'll land on your **Survey List**.

1. Locate the correct site from your synchronized plans.
2. Tap on the desired survey to view the designated target nodes and tasks.

<img alt="Survey List" />

## Step 2: Utilizing the GPS Trail

It's critical for methodologies like Biodiversity Net Gain (BNG) walks and bat transects to have proof-of-coverage.

1. Within the survey view, switch to the map tab to see your **GPS Trail**.
2. Start walking your transect or plot. NikaField logs your pathway, allowing you to easily view the exact coverage you've completed for QA evidence.

<img alt="GPS Trail" />

## Step 3: Entering a Session and Using Voice AI

Instead of manually navigating through 15+ form fields, you can use NikaField's offline, on-device AI to transcribe and organize your observations automatically.

1. Create a new **Survey Session** for the current subplot or feature.
2. Tap the **Audio Mode** button to begin recording.
3. Simply speak your observations naturally. For example: *"The broad habitat is grassland, specifically poor semi-improved. Scattered scrub covers about 15% of the area..."*

<img alt="Survey Session" />

### On-Device Transcription

Once you stop recording, NikaField immediately processes your speech into text. Because this uses an on-device model, **no internet connection is required**.

<img alt="Audio Transcript" />

## Step 4: AI Auto-Fill

After the transcription is complete, click the AI Auto-Fill action.

1. The built-in AI assistant automatically maps your spoken sentences to the corresponding fields in your compliance schema.
2. Review the structured data—habitat type, coverage percentage, species counts, etc. have all been placed in their correct fields.
3. Make any minor adjustments if necessary, then save the session.

<img alt="AI Auto-Fill" />

## Summary

By leveraging Voice-to-Form AI and offline speech-to-text, you drastically reduce time spent typing on small screens. NikaField ensures your data stays organized, compliant, and spatially accurate with full GPS transparency.


# Assign a Labeling Job
Source: https://docs.nikaplanet.com/guides/image-labeling/assign-labeling-job

Learn how to assign labeling jobs to team members and manage annotation workflows

Learn how to assign your created labeling jobs to team members and manage the annotation workflow effectively.

<img alt="Assign Labeling Job" />

## Step 1: Add Collaborators to Your Workspace

Before you can assign a labeling job to team members, you need to ensure they have access to your workspace. This requires two steps:

### Add People to Your Team

First, invite users to your team by following the [Invite to Team](/guides/access-control/invite-to-team) guide. This adds them to your organization's team.

### Grant Workspace Access with EDITOR Permissions

Next, give team members access to the specific workspace containing your labeling job. Follow the [Invite to Workspace](/guides/access-control/invite-to-workspace) guide and make sure to assign them **EDITOR** access. Only users with EDITOR access can be assigned as labelers or reviewers.

## Step 2: Assign Users to the Labeling Job

Once your team members have EDITOR access to the workspace, you can assign them to the labeling job.

<img alt="Assign User to Job" />

You can assign:

* **Yourself** as the labeler
* **Other team members** who have EDITOR access to the workspace

After making an assignment, the job status will automatically update from **UNASSIGNED** to **ANNOTATING**.

## Step 3: Manage Existing Assignments

Each assigned user has management options available on the right side of their assignment entry.

<img alt="Manage Assignment" />

You can:

* **Switch Role**: Click the switch icon to toggle between **Labeler** and **Reviewer** roles
* **Remove Assignment**: Click the trash icon to remove the user from this job

## Step 4: Add More Assignments with Different Roles

You can assign multiple users to the same job with different roles using the select dropdown.

<img alt="Add More Assignments" />

Use the dropdown to:

* Assign additional labelers to distribute the workload
* Assign reviewers to quality-check annotations
* Mix roles as needed for your workflow

Once a user is assigned a role to this job, one can click the **play button** to start the labeling or reviewing task from the first image.

Happy labeling!


# Create a Labeling Job
Source: https://docs.nikaplanet.com/guides/image-labeling/create-labeling-job

Learn how to create an image labeling job, configure modes, and set up instructions for your team

Learn how to create a new labeling job in Nika Labeler, switch between labeling modes, and configure instructions that your team members will see when working on annotations.

## Step 1: Create a New Labeling Job

1. **Navigate to Nika Labeler**: In NikaWorkspace, click on the Labeler icon in the left sidebar
2. **Create New Job**: Click the "+" button to create a new labeling job
3. **Configure Job Settings**: Set up your job name and initial configuration

<img alt="Create Labeling Job" />

## Step 2: Switch Between Labeling Modes

Nika Labeler supports different labeling modes to accommodate different annotation workflows. You can easily switch between modes using the switch.

<img alt="Switch Labeling Modes" />

### Available Labeling Modes

* **Classification Mode**: For categorizing entire images with 1 or more classes
* **Segmentation Mode**: For bounding box, polygon, linestring drawing on images with associated classes

Note: you can still switch mode after images are uploaded. However, all existing annotations will be gone.

## Step 3: Edit Job Instructions

Clear instructions are essential for consistent annotations. Set up detailed guidance that assignees will reference while labeling.

1. **Click Edit Instructions**: Click the instruction editor button to open the instruction panel

<img alt="Edit Instructions Button" />

2. **Write Clear Guidelines**: Provide detailed instructions for your labeling task
   * Describe what to annotate
   * Include examples of edge cases
   * Specify quality standards
   * Add any project-specific requirements

3. **Save Instructions**: Click "✅" to finalize your instructions

<img alt="Save Instructions" />

After saving, your instructions will be visible to assignees in the right panel's annotations tab. This ensures they have constant access to guidelines while working.

<img alt="Assignee View of Instructions" />

## Step 4: Add Images to Your Labeling Job

Now that your job is configured with instructions, it's time to add the images that need to be labeled. Nika Labeler provides two convenient ways to add images to your job.

<img alt="Add Images to Job" />

### Method 1: Drag and drop from Nika File Storage

1. **Open File Storage**: Access your files from the left sidebar in NikaWorkspace
2. **Select Files or Folders**: Choose the images or folders containing images you want to label
3. **Drag to Images Section**: Drag and drop the selected files or folders directly to the images section of your labeling job

This method is ideal when your images are already uploaded to Nika's cloud storage.

### Method 2: Drag and drop from Desktop

1. **Locate Files on Desktop**: Find the images on your local computer
2. **Drag Directly**: Drag the files from your desktop (or any local folder) directly to the images section
3. **Upload Automatically**: The files will be uploaded and added to your labeling job automatically

This method is perfect for quickly adding new images without pre-uploading them to Nika File Storage.

## Job Ready for Assignment

Your labeling job is now configured and ready to be assigned to team members! The job includes:

✅ Configured labeling mode\
✅ Clear instructions for assignees\
✅ Proper setup for consistent annotations

Happy labeling!


# Edit Labeling Classes
Source: https://docs.nikaplanet.com/guides/image-labeling/edit-labeling-classes

Learn how to add, edit, and manage labeling classes for your annotation jobs

Learn how to manage labeling classes in your annotation jobs, including adding new classes, editing existing ones, and protecting classes from accidental changes.

## Step 1: Add a New Class

Use the bottom of the labeler right panel to add new class entries.

<img alt="Add New Class" />

When adding a class, you can specify:

* **Class Name**: The name of the annotation class
* **Super Class** (optional): Used to group classes of the same family together for certain model training purposes

## Step 2: Edit or Remove a Class

Once a class is created, you have options to manage it.

<img alt="Edit or Remove Class" />

For each class, you can:

* **Edit**: Click the edit button to enter edit mode
* **Remove**: Click the trash button to remove this class

**Note**: Removing a class will also remove all associated annotations with this class.

## Step 3: Modify Class Properties

When in edit mode, you can modify various properties of the class.

<img alt="Edit Class Properties" />

You can modify:

* **Class Name**: Change the name of the class
* **Super Class Name**: Update or add a super class grouping
* **Class Color**: Adjust the color used to display this class in annotations

After making changes:

* Click the **✓** (tick emoji) to save your changes
* Click the **✕** (cross emoji) to cancel changes

## Step 4: View Associated Annotations

Each class displays the number of annotations associated with it.

<img alt="View Annotation Count" />

This helps you track which classes are being used and how extensively they've been annotated.

## Step 5: Lock Classes to Prevent Changes

Users of the workspace can click the lock button to lock/unlock class edits to protect against mistaken changes.

<img alt="Lock Classes" />

When classes are locked:

* Other users cannot make edits to existing classes
* Other users cannot remove existing classes in this job
* This protects your class structure from accidental modifications

Happy labeling!


# Import and Export Classes/Annotations
Source: https://docs.nikaplanet.com/guides/image-labeling/import-export-formats

Learn how to import and export annotation data in various formats

Learn how to import existing classes/annotations and export your completed labeling work in industry-standard formats.

## Supported Formats

Nika Labeler supports various annotation formats for import and export:

* **COCO 1.0 JSON** (Currently supported)
* YOLO format (To be confirm)
* Pascal VOC XML (To be confirm)
* LabelMe JSON (To be confirm)
* Custom JSON formats (To be confirm)

## Step 1: Import Annotations

To import existing annotations into your labeling job, use the import dropzone.

<img alt="Import Annotations" />

You can import annotations by:

* **Click the dropzone**: Click to open a file browser and select your annotation file
* **Drag and drop**: Drop a file from your desktop directly to the dropzone

## Step 2: Resolve Import Conflicts

Once the file is validated successfully, a dialog will appear for resolving conflicts before the import.

<img alt="Resolve Conflicts" />

In the conflict resolution dialog, you can:

* **Merge conflicting classes**: Combine classes with similar names
* **Rename classes**: Adjust class names to match your existing schema
* **Select classes**: Click on classes to choose whether to include or ignore them
* **Select images**: Click on images to choose whether to include or ignore them

After reviewing and resolving conflicts, click the **"Proceed"** button to finalize the import.

## Step 3: Export Annotations

Once you have completed annotating images in this job, you can export the existing job via the download button.

<img alt="Export Annotations" />

Click the download button in the top right to export your annotations in the selected format.

Happy labeling!


# Label on Images
Source: https://docs.nikaplanet.com/guides/image-labeling/label-on-images

Learn how to annotate images using various drawing tools and keyboard shortcuts

Learn how to annotate images efficiently using drawing tools, keyboard shortcuts, and smart segmentation features.

## Step 1: Enter Drawing Mode

Double click on an image to enter drawing mode on that image.

<img alt="Drawing Mode with Keyboard Shortcuts" />

### Keyboard Shortcuts

The following keyboard shortcuts are available to speed up your annotation workflow:

#### Navigation

| Shortcut | Action |
| - | - |
| `A` | Previous image |
| `D` | Next image |

#### Class Selection (Segmentation Mode Only)

| Shortcut | Action |
| - | - |
| `1-9` | Select class 1-9 |

#### Drawing Tools

| Shortcut | Action |
| - | - |
| `S` | Pan tool |
| `Q` | Bounding Box tool (Segmentation mode) |
| `W` | Polygon tool (Segmentation mode) |
| `E` | Polyline tool (Segmentation mode) |
| `R` | Mask tool (To be confirmed) |
| `F` | Point Marker (To be confirmed) |
| `X` | Smart Segmentation |
| `C` | Comment tool |

#### Actions

| Shortcut | Action |
| - | - |
| `⌘Z` | Undo |
| `⌘⇧Z` | Redo |
| `Enter` | Finish drawing / Accept (Segmentation mode) |
| `Esc` | Cancel / Reset to Pan |
| `Backspace` | Delete selected annotation (Segmentation mode) |

## Step 2: Switch Between Classes

In segmentation jobs, you can click the dropdown at top right of the drawing page to switch between classes for your current annotation.

<img alt="Switch Class Dropdown" />

This allows you to quickly change the class you're annotating without interrupting your workflow.

## Step 3: Draw Polygons

In polygon mode, you can create precise annotations by clicking to add points.

<img alt="Polygon Drawing Mode" />

To draw a polygon:

* **Click** to add a point
* **Double click** or **click again on an existing node** to finalize the polygon drawing

## Step 4: Use Smart Segmentation

Nika's smart segmentation tool uses SAM 2.0 from Meta for quick segmentation of parts of the image.

<img alt="Smart Segmentation Tool" />

With smart segmentation, you can:

* Define the number of polygons allowed before finalizing
* Adjust the complexity/smoothness of boundary segmented
* Quickly segment complex objects with AI assistance
* Refine the generated polygons as needed

## Step 5: Submit for Review

Once you've finished annotating all images, you can submit your work for review.

<img alt="Submit for Review" />

As a user assigned the labeler role:

1. Go back to the job page
2. Click the top right status select dropdown
3. Select **Submit for Review**

Happy labeling!


# Review Existing Annotations
Source: https://docs.nikaplanet.com/guides/image-labeling/review-existing-annotations

Learn how to review annotations, add comments, and approve or reject labeling work

Learn how to review annotations as a reviewer, provide feedback through comments, and approve or reject completed labeling work.

## Step 1: Add Comments During Review

A reviewer role can add comments with different severity levels for labelers to see in real time and reply.

<img alt="Add Comment on Image" />

To add a comment:

1. Click the comment button on the right
2. Click anywhere on the image to drop a comment there

Comment levels available:

* **INFO**: General information or suggestions
* **WARNING**: Issues that should be addressed
* **ERROR**: Critical problems that must be fixed

## Step 2: Manage Issues in the Right Panel

The labeler right panel displays a list of all issues (comments) added to the current image.

<img alt="Issues List in Right Panel" />

Users can:

* **Reply**: Other users can reply to issues for discussion
* **Resolve**: Mark an issue as resolved once addressed
* **Remove**: Issue owner can remove an issue entirely from the job

## Step 3: Filter and View Resolved Issues

Use the filter at the top right to control which issues are displayed.

<img alt="Filter Issues" />

The filter allows you to:

* **Show all issues**: View both open and resolved issues
* **View resolved issues**: See previously resolved issues
* **Reopen issues**: Reopen resolved issues for further actions if needed

## Step 4: Approve or Reject the Job

Once you've finished reviewing all images, you can approve or reject the job overall.

<img alt="Approve or Reject Job" />

As a reviewer:

1. Go back to the job overview page
2. Click **Reject** or **Approve** at the top right

This completes the review cycle and notifies the labeler of the outcome.

Happy labeling!


# Download Files and Folders
Source: https://docs.nikaplanet.com/guides/manage-file-lake-per-workspace/download-files-and-folders

Learn how to download files and folders from your workspace's file storage

You can download individual files, multiple files, or entire folders from the File Storage panel.

## Download Files

1. **Select files**: Click a file to select it, or hold **Cmd** (Mac) / **Ctrl** (Windows) and click to select multiple files
2. **Right-click**: Right-click on any of the selected files
3. **Click "Download"**: Choose "Download" from the context menu

Each selected file will be downloaded individually to your computer.

<img alt="Download Files" />

## Download a Folder

1. **Right-click** on the folder you want to download
2. **Click "Download"**: Choose "Download" from the context menu

The folder and all its contents will be automatically zipped and downloaded as a `.zip` file.

<img alt="Download Folder" />

<Note>
  Folders past about 2 GB cannot be zipped in the browser. Nika Planet detects
  this and offers the **Nika Planet Downloader** instead — see
  [Large Folder Downloads](/guides/manage-file-lake-per-workspace/large-folder-downloads).

  For very large one-off migrations, our data migration team can help —
  [book a call](https://cal.com/lawrence-nika/export-20-gb-files-from-nika.eco)
  or email [support@nikaplanet.com](mailto:support@nikaplanet.com).
</Note>


# How to Download Large Folders from Nika Planet
Source: https://docs.nikaplanet.com/guides/manage-file-lake-per-workspace/large-folder-downloads

Install the Nika Planet Downloader to transfer folders over 2 GiB or 2,000 files, resume interrupted downloads, and verify each file.

Browsers download a folder by building the whole ZIP in memory before anything
reaches your disk. Folders over 2 GiB or 2,000 files can stall, and there is no
way to resume — so Nika Planet hands folders past either limit to a small
terminal tool instead.

The **Nika Planet Downloader** writes straight to the drive you choose, transfers
files in parallel, resumes where it left off, and verifies every file against the
checksum storage reports.

The web app sends large **folders** to the downloader. Individual file
selections continue to use the normal browser download, even when a file is
large. The downloader transfers the objects inside each selected folder
individually; you can also run it directly for folders without starting from
the web app.

<div />

## Install

One install covers every export, in any workspace.

<Tabs>
  <Tab title="macOS">
    With [Homebrew](https://brew.sh):

    ```bash theme={null}
    brew install nikageospatial/nika-planet-downloader/nika-planet-downloader
    ```

    It is ready to use as soon as the command finishes. `brew upgrade
        nika-planet-downloader` picks up new versions.

    No Homebrew? Use the install script instead:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.sh | sh
    ```

    The script adds the downloader to your `PATH`, so **open a new terminal
    window** before running it. Run the script again to update.
  </Tab>

  <Tab title="Windows">
    In PowerShell:

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.ps1 | iex
    ```

    It installs to `%LOCALAPPDATA%\Programs\nika-planet-downloader` and adds that
    folder to your `PATH` — no administrator rights needed — and the window you ran
    it in can use the downloader straight away.

    Rather not paste a command? Download
    [`install.cmd`](https://github.com/NikaGeospatial/nika-planet-downloader/releases/latest/download/install.cmd)
    and double-click it, then **open a new PowerShell window** to use the
    downloader. It is not code-signed yet, so Windows may ask you to confirm before
    it runs.

    Run either one again to update. 64-bit Windows only; on Windows on Arm the x64
    build runs under emulation.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.sh | sh
    ```

    The script adds the downloader to your `PATH`, so **open a new terminal
    window** before running it. Run the script again to update. x86\_64 only for
    now.
  </Tab>
</Tabs>

## Download a folder

Point the tool at a folder using a `nikafs://` address:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output ~/Downloads
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output "$HOME\Downloads"
    ```

    Write the output folder as `"$HOME\Downloads"` rather than `~/Downloads`:
    Windows PowerShell passes `~` to programs unchanged, so the download would land
    in a folder literally named `~`.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output ~/Downloads
    ```
  </Tab>
</Tabs>

You do not need to sign in first. If no session is cached, the command opens your
browser once, and continues into the download as soon as you have authorised it.

<Note>
  **`--output` is the parent directory.** The folder structure from Nika Planet
  is recreated inside it, so `--output ~/Downloads` saves the example above to
  `~/Downloads/stac/cogs` (on Windows, `--output "$HOME\Downloads"` saves it to
  `Downloads\stac\cogs` in your user folder). Passing `--output ~/Downloads/stac`
  would give you `~/Downloads/stac/stac`.
</Note>

### Finding the address

The `nikafs://` address is your project id followed by the folder path:

1. **Project id** — the UUID in the workspace URL while the project is open
2. **Folder path** — right-click the folder in File Storage and choose
   **Copy Path**, which gives you something like `/data/stac/cogs/`

Join them: `nikafs://<project-id>/data/stac/cogs`

Addresses do not expire. Keep one in a script or runbook and it will keep working
for as long as you have access to that folder.

### Several folders at once

Pass as many addresses as you like. They may span different projects.

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    nika-planet-downloader export \
      'nikafs://<project-id>/data/stac/cogs' \
      'nikafs://<project-id>/data/imagery/2024' \
      --output ~/Downloads
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    nika-planet-downloader export `
      'nikafs://<project-id>/data/stac/cogs' `
      'nikafs://<project-id>/data/imagery/2024' `
      --output "$HOME\Downloads"
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    nika-planet-downloader export \
      'nikafs://<project-id>/data/stac/cogs' \
      'nikafs://<project-id>/data/imagery/2024' \
      --output ~/Downloads
    ```
  </Tab>
</Tabs>

### Starting from the web app

If you select folders in File Storage and choose **Download**, anything too large
for the browser collapses into a single row in Active Operations. Click
**Download via CLI** for a dialog with the install command and the exact export
command already filled in. It shows the commands for the operating system you
are on; switch between **macOS**, **Windows** and **Linux** at the top if you
are setting up another machine. Copy them and run them.

## Options

| Flag | Default | What it does |
| - | - | - |
| `--output` | required | Parent directory for the download |
| `--concurrency` | `4` | Files transferred at once. Raise it if your connection is not saturated |
| `--force` | off | Re-download files even when a verified local copy exists |
| `--dry-run` | off | List what would transfer, then stop |

<Note>
  The flags above are the ones you are likely to reach for; run
  `nika-planet-downloader export --help` for the full list.
</Note>

## Resuming

Press **Ctrl-C** at any point. Partly-transferred files are kept as `.nikapart`
files, and re-running the identical command picks up where it stopped. Files that
already finished are skipped after a size check, so repeating a command is cheap
and safe.

## Other commands

```bash theme={null}
nika-planet-downloader login     # sign in ahead of time
nika-planet-downloader whoami    # show the current sign-in state
nika-planet-downloader logout    # forget the cached session on this machine
```

## Access and privacy

The tool signs in as **you**. It can only download what your own Nika Planet
account is already allowed to download, and that permission is re-checked on
every request — so if your workspace access changes, an in-progress download
stops. Read access is granted one hour at a time and can be revoked.

Your session is stored in your operating system's credential store — the
Keychain on macOS, Credential Manager on Windows — never in a file.

## If something goes wrong

<AccordionGroup>
  <Accordion title="'command not found' or 'is not recognized'">
    Open a new terminal window. The installer added the downloader to your
    `PATH`, and windows that were already open do not see the change.
  </Accordion>

  <Accordion title="'no folders given, and nothing is waiting on this account'">
    You ran `export` with no address. Pass a `nikafs://` address, or start a
    download from the web app and use **Download via CLI**.
  </Accordion>

  <Accordion title="'No files found under …'">
    The path is wrong or the folder is empty. Re-copy it with **Copy Path** and
    check the project id matches the workspace the folder is in.
  </Accordion>

  <Accordion title="'You do not have permission to download from this workspace'">
    Your access to that project changed. Ask a workspace owner to confirm you
    are still a contributor or above.
  </Accordion>

  <Accordion title="Some files failed">
    Re-run the identical command. Only the files that failed are retried;
    everything already downloaded is skipped.
  </Accordion>

  <Accordion title="Windows: the browser shows 'Sign-in failed — Missing code'">
    Earlier versions of the downloader opened the sign-in page on Windows
    without the details it needs. Re-run the Windows install command to update,
    then sign in again.
  </Accordion>

  <Accordion title="Windows: 'An Application Control policy has blocked this file'">
    Smart App Control, which is on by default on new Windows 11 installations,
    blocks programs it does not recognise yet, and the downloader is not
    code-signed. Windows offers no way to allow a single program past it, so
    run the downloader on another computer, or contact us below.
  </Accordion>

  <Accordion title="Windows: double-clicking install.ps1 does not install anything">
    Windows does not run downloaded PowerShell scripts that way. Use
    `install.cmd`, or paste the `irm … | iex` command from the Windows install
    tab into PowerShell.
  </Accordion>
</AccordionGroup>

Still stuck? Email [support@nikaplanet.com](mailto:support@nikaplanet.com), or
[book a call](https://cal.com/lawrence-nika/export-20-gb-files-from-nika.eco) for
help with very large migrations.


# Monitor File Storage
Source: https://docs.nikaplanet.com/guides/manage-file-lake-per-workspace/monitor-file-storage

Learn how to monitor storage usage per workspace and across your team

NikaPlanet provides several ways to monitor how much file storage your team is using.

## Check Storage in a Workspace

At the bottom of the File Storage panel in any workspace, you can see the total storage available for your organization.

<img alt="Workspace Storage Indicator" />

## Check Storage Across All Workspaces

For a detailed breakdown of storage usage across all workspaces under your team:

1. Go to **Settings** → **Usage** ([planet.nika.eco/en/settings/usage](https://planet.nika.eco/en/settings/usage))
2. Select the correct team from the team switcher on the left sidebar
3. Click the **Storage** tab

<img alt="Select Team in Settings" />

This view shows storage used per workspace, including object counts, storage size, and percentage distribution.

<img alt="Team Storage Usage Details" />

## Check Your Current Plan

To see the storage quota included in your current plan:

1. Go to **Settings** → **Billing** ([planet.nika.eco/en/settings/billing](https://planet.nika.eco/en/settings/billing))
2. Select the correct team from the team switcher on the left sidebar
3. Review the **Storage** line item showing your plan's total allocation

<img alt="Billing Plan Storage" />

## Upgrade Storage

If you need more storage, you can:

* **Book a call with our sales team**: [cal.com/lawrence-nika/nika-expert](https://cal.com/lawrence-nika/nika-expert)
* **Email support**: [support@nikaplanet.com](mailto:support@nikaplanet.com)


# Organize Files and Folders
Source: https://docs.nikaplanet.com/guides/manage-file-lake-per-workspace/organize-files-and-folders

Learn how to move and organize files and folders within your workspace's file storage

After uploading your data, you can reorganize files and folders by moving them between directories. There are two ways to move items in the File Storage panel.

## Method 1: Move via Right-Click Menu

1. **Select Items**: Hold **Cmd** (Mac) or **Ctrl** (Windows) and click each file or folder you want to move
2. **Right-Click**: Right-click on any of the selected items
3. **Choose "Move"**: Select "Move" from the context menu
4. **Pick Destination**: Choose which subfolder or the root `/data/` folder to move them into

<img alt="Move via Right-Click Menu" />

## Method 2: Drag and Drop

1. **Select Items**: Hold **Cmd** (Mac) or **Ctrl** (Windows) and click to select one or more files or folders
2. **Drag**: Click and drag the selected items
3. **Drop onto Folder**: Drop them onto any existing folder at the same level in the file list

<img alt="Drag and Drop to Move" />

A progress status bar will appear to track the move operation.


# Upload Files and Folders
Source: https://docs.nikaplanet.com/guides/manage-file-lake-per-workspace/upload-files-and-folders

Learn how to upload files and folders to your workspace's file storage for data migration

Every workspace in NikaPlanet has a built-in File Storage panel on the left sidebar. You can use it to upload, organize, and manage files and folders for your geospatial data workflows.

<Note>
  There is no limit to how much data you can store in a single workspace. Users have stored over 100 TB of data in a single workspace for complex projects — the architecture is well tested and proven at scale. For projects of that size, we also provide a dedicated data migration service to ensure timely delivery. [Book a call](https://cal.com/lawrence-nika/nika-expert) or email [support@nikaplanet.com](mailto:support@nikaplanet.com) to learn more.
</Note>

File Storage is the foundation that all other NikaPlanet services build on. Notebooks can access all files here directly in the attached VM, maps can load spatial files from this storage, and pipelines can read and write data here — making it the central hub for your geospatial workflows.

## Step 1: Create Folders

Before uploading, you may want to set up a folder structure to keep your data organized.

1. **Open File Storage**: Click the Files icon in the left sidebar of your workspace
2. **Click "+" Button**: Click the "+" button at the top right of the file list
3. **Select "Create Folder"**: Choose "Create Folder" from the dropdown menu
4. **Name Your Folder**: Enter a name for your new folder

<img alt="Create Folder" />

You can repeat this process to create subfolders and build out your desired folder hierarchy.

## Step 2: Navigate Folders

To navigate into a folder, **double-click** it. The breadcrumb at the top of the panel shows your current location. `/data/` is the root folder of every workspace.

<img alt="Navigate into Subfolder" />

To go back:

* **Click the back arrow** to move up one level
* **Click any parent folder** in the breadcrumb to jump directly to it

## Step 3: Upload Files or Folders

Once you have navigated to the target folder, there are two ways to upload.

### Method 1: Drag and Drop

Simply drag one or more files or folders from your desktop and drop them onto the File Storage panel.

<img alt="Drag and Drop Upload" />

### Method 2: Upload via Menu

1. **Click "+" Button**: Click the "+" button at the top right
2. **Select "Upload File" or "Upload Folder"**: Choose the appropriate option from the dropdown

<img alt="Upload via Menu" />

## Step 4: Track Upload Progress

Once the upload starts, an **Active Operations** dialog appears showing the progress of each file with percentage bars.

<img alt="Upload Progress" />

## Step 5: Verify Uploaded Files

As files finish uploading batch by batch, they automatically appear in the File Storage panel if you are still viewing the folder they were uploaded to. No manual refresh is needed.

<img alt="Uploaded Files Auto-Refresh" />


# Building Your First App
Source: https://docs.nikaplanet.com/guides/tutorials/building-first-app

Learn how to build your first application with NikaStudio

## Building Your First App

This guide will help you build your first application using NikaStudio.

*Content coming soon...*


# Geospatial Analysis
Source: https://docs.nikaplanet.com/guides/tutorials/geospatial-analysis

Learn how to perform geospatial analysis with NikaWorkspace in 7 easy steps

## Geospatial Analysis

Learn how to perform geospatial analysis with NikaWorkspace in 7 easy steps. This tutorial will guide you from creating your first notebook to publishing your analysis results.

## Step 1: Create Your First Notebook

### Quick Start

1. **Navigate to Notebooks**: Click on "Notebooks" in the left sidebar
2. **Click "+" Button**: Click the "+" button in the notebook list
3. **Select "Blank Notebook"**: Choose "Blank Notebook" from the dropdown menu
4. **Auto-Save Enabled**: Your notebook is automatically saved

### Rename Your Notebook

* **Click Title Area**: Click on the notebook title at the top left
* **Type New Name**: Enter a descriptive name like "Geospatial Analysis Project"
* **Professional Naming**: Use clear, descriptive names for your projects

<img alt="Create Blank Notebook" />

## Step 2: Start Your Machine

### Select Machine Configuration

Choose from available configurations:

* **CPUx3**: 3 CPU cores, 24GB RAM, ready in under 30 seconds (recommended for beginners)
* **CPUx7**: 7 CPU cores, 53GB RAM, ready in over 2 minutes
* **GPU Machines**: For machine learning and complex processing

### Start Machine

1. **Click "Start Machine"**: Click the prominent white button
2. **Wait for Ready**: Machine will be ready in 15-40 seconds
3. **Monitor Status**: Hover over the green dot to check machine status

<img alt="Start Machine" />

## Step 3: Add Content Blocks

### Using the "+" Icon

1. **Find "+" Button**: Look for the "+" icon on the left of any row
2. **Click "+"**: Click to add a new block
3. **Select Block Type**: Choose from code, markdown, alerts, or media blocks

### Using Keyboard Shortcut

* **Press "/"**: Type "/" in any empty row to trigger block selection
* **Choose Block**: Select the desired block type from the menu

### Available Block Types

* **Code Block**: For Python code execution
* **Alert Block**: Highlight important information
* **Headings**: Create section headers
* **Media**: Insert images, videos, or file attachments

<img alt="Cool Blocks Available" />

## Step 4: Run Your Code

### Multiple Execution Methods

1. **Hover Menu**: Hover over code block and click the play button (▶️)
2. **Keyboard Shortcut**: Select block and press `Shift+Enter`
3. **Run All**: Use "Run All" button in top-right toolbar for sequential execution

### Streaming Execution

* **Real-time Output**: Results stream in from the kernel
* **Background Processing**: Long-running code continues even if you close the workspace
* **Return Later**: Come back hours later to see completed results

<img alt="Run Button in Hover Menu" />

## Step 5: Use Pre-installed Geospatial Libraries

### GDAL and CUDA Ready

All VM kernels come with:

* **GDAL 3.9.1**: Geospatial Data Abstraction Library
* **CUDA 12.2**: NVIDIA CUDA for GPU acceleration
* **Python 3.10/3.11**: Multiple Python versions available

### Example Geospatial Code

```python theme={null}
# Import geospatial libraries
import rasterio
import geopandas as gpd
import numpy as np

# Load raster data
with rasterio.open('/workspace/data/satellite.tif') as src:
    data = src.read()
    print(f"Raster size: {src.width} x {src.height}")

# Load vector data
gdf = gpd.read_file('/workspace/data/shapefile.shp')
print(f"Number of features: {len(gdf)}")

# Perform analysis
ndvi = (data[3] - data[2]) / (data[3] + data[2])
print(f"NDVI calculated successfully")
```

<img alt="GDAL CUDA Pre-installed" />

## Step 6: Use AI-Powered Features

### Quick AI Edit

* **Press `Cmd/Ctrl + K`**: Get AI suggestions for code improvements
* **Green Suggestions**: AI suggestions appear in green text
* **Preview Execution**: Test suggested changes before accepting
* **Accept/Reject**: Choose which suggestions to keep

### Error Resolution with GAIA

* **"Resolve in GAIA" Button**: Click when you encounter errors
* **AI Analysis**: GAIA analyzes your entire notebook context
* **Chat Interface**: Ask questions and get AI assistance
* **Direct Modifications**: AI can modify your notebook directly

<img alt="Resolve in GAIA Button" />

## Step 7: Publish Your Analysis

### Prepare for Publishing

1. **Finalize Your Analysis**: Ensure all code blocks are executed
2. **Add Documentation**: Include markdown blocks explaining your work
3. **Test Functionality**: Verify all interactive features work

### Publish Your Notebook

1. **Right-click Notebook**: Right-click on your notebook in the list
2. **Select "Publish"**: Choose the publish option from the context menu
3. **Fill Required Fields**: Enter title\*, version\*, and category\*
4. **Generate Thumbnail**: Use AI generation if you don't have a thumbnail
5. **Set Visibility**: Choose Team Only or Public access
6. **Click Publish**: Finalize your publication

### View Published Notebook

* **Click Arrow Icon**: Click the arrow icon in the publish dialog
* **New Tab Opens**: Your published notebook opens in a new tab
* **Static View**: Notebook is view-only for others
* **Public Hub**: If public, appears in the NikaHub

<img alt="Publish Dialog with Required Fields" />

## Key Features Summary

### Easy to Use

* **Auto-save**: Everything is automatically saved
* **Streaming Execution**: Long-running tasks continue in background
* **Multiple Execution Methods**: Hover, keyboard shortcuts, or run all
* **Block Reordering**: Easy reordering with arrow buttons

### Powerful Analysis

* **Pre-installed Libraries**: GDAL, CUDA, and Python ready to use
* **Large Dataset Support**: Work with TB-PB sized geospatial data
* **GPU Acceleration**: Use CUDA for faster processing
* **Real-time Linting**: Code quality feedback as you type

### AI-Powered

* **Quick AI Edit**: Get code suggestions with `Cmd/Ctrl + K`
* **Error Resolution**: Use GAIA for intelligent error fixing
* **Context-Aware**: AI understands your entire notebook
* **Chat Interface**: Natural language interaction with AI

### Collaboration Ready

* **Team Publishing**: Share with team members
* **Public Hub**: Share with the broader community
* **Version Control**: Maintain different versions of your work
* **Easy Updates**: Modify and republish as needed

## Next Steps

Now that you've completed the tutorial:

1. **Explore Libraries**: Check [Supported Python Libraries](/guides/data-analysis/supported-python-libraries)
2. **Advanced Features**: Learn about [AI Coding in Notebook](/guides/data-analysis/ai-coding-in-notebook)
3. **Machine Management**: Understand [Starting Your Machine](/guides/data-analysis/start-machine)
4. **Publishing**: Master [Publishing Your Notebook](/guides/data-analysis/publish-notebook)

Happy geospatial analyzing!


# Getting Started With NikaWorkspace
Source: https://docs.nikaplanet.com/guides/tutorials/getting-started-with-nikaworkspace

Learn the basics of Nika platform and get familiar with the interface

## Getting Started with NikaWorkspace

Welcome to Nika! This guide will help you get familiar with the platform and start your first project.

## Prerequisites

Before you begin, make sure you have:

* **Nika Account**: Sign up at [https://planet.nika.eco](https://planet.nika.eco)
* **Onboarding**: Book and complete your [onboarding call](https://cal.com/dianaong/30-minute-consultation) to get trial access

## Step 1: Manage Data Workspaces

1. **Project**: Each of your workspaces is a logical separation for project management, to keep your resources such as file storage, notebooks, maps and databases separate.
2. **Login**: Visit [https://planet.nika.eco](https://planet.nika.eco) and sign in
3. **Dashboard**: You'll see your main dashboard with access to a default workspace if you log in for the first time
4. **Navigation**: Click on the default workspace to open, use the left sidebar to navigate between different tools

<img alt="List of Workspaces" />

## Step 2: Explore the Interface

### Main Components

* **Left Sidebar**: Navigation between Nika products
* **Top Bar**: User settings, notifications, and help
* **Main Area**: Content area that changes based on selected tool
* **Right Panel**: Context-sensitive tools and options

<img alt="Nika UI Overview" />

### Available Tools in Nika

* **Nika Notebooks**: Data analysis, notebooks and VM
* **Nika Map**: Interactive map visualization
* **Nika Studio**: Application development
* **Publish to Nika Hub**: Community and team internal sharing
* **Nika Labeler**: Image annotation
* **Nika ETL**: Data processing pipelines
* **Nika Database Engine**: Intergration with your existing databases or one click creation of Nika managed DuckDB instance
* **Nika GAIA**: Nika's AI Agent for coding and mapping

### Create a New Map

1. **Click Map** icon in the left sidebar
2. **Click "+"** button to create new map
3. **Drag files** from the files list in left sidebar to add as layer to the open map. Note: drop to the center of the map to trigger `Add to Map` instead of opening file

<img alt="Create New Map" />

### Create a New Notebook

1. **Click Notebook** icon in the left sidebar
2. **Click "+"** button to create new notebook
3. **Click Machine** icon at bottom left to then start the machine
4. **Run code in your notebook** by following this [guide](/guides/data-analysis/run-code-in-notebook)

<img alt="Create New Notebook" />

## Step 3: Upload Your First Data

### Upload Files

1. **Click "Files"** in the left sidebar
2. **Click "Upload"** button and select your files from desktop
3. **Drag and Drop** alternaitvely, drag multiple files and drop them on the file list when left sidebar is open
4. **Wait for processing** to complete

<img alt="Upload Files" />

### Design of Nika File Storage

* **Size Limit**: Theoretically Nika Cloud FS can host up to 100s of TB size per workspace
* **Integration**: These files are natively accessible in your notebook code through secure connection, and adding them as layer to map is as easy as drag and drop on map
* **Editor**: For certain formats like .py, .json, .js, you can double click to open the file in Nika web UI and edit them directly
* **Machine Learning**: If you are try to train machine learning models over a large groups of test/train/eval split datasets, Nika FS is the best option as your machine learning code in notebook work immediately on files

<img alt="Upload Files" />

## Next Steps

Now that you're familiar with the basics:

1. **Try Making a Map**: Follow the [Create NikaMap Tutorial](/guides/tutorials/map-visualization) guide
2. **Start Data Analysis**: Follow the [Create Notebook Tutorial](/guides/tutorials/geospatial-analysis) guide
3. **Explore Features**: Check out the other guides in this section
4. **Join Community**: Visit [NikaHub](https://planet.nika.eco/en/hub) to see examples

Happy mapping and analyzing!


# Map Visualization Tutorial
Source: https://docs.nikaplanet.com/guides/tutorials/map-visualization

Learn how to create effective map visualizations with Nika in 7 simple steps

## Map Visualization Tutorial

This tutorial will guide you through creating a complete map visualization using Nika's powerful mapping tools. You'll learn how to create maps, add different types of data layers, and style them effectively to create compelling visualizations.

## What You'll Learn

By the end of this tutorial, you'll be able to:

* Create a new map from scratch
* Add vector, raster, and image data layers
* Style different layer types for optimal visualization
* Organize and manage your map layers
* Export your final visualization

## Prerequisites

Before starting, make sure you have:

* Access to NikaWorkspace
* Sample data files ready (we'll provide examples)
* A modern web browser

## Step 1: Create Your First Map

### Access NikaMap

1. **Navigate to NikaMap**: In NikaWorkspace, click on the Globe icon in the left sidebar
2. **View Map List**: You'll see a list of your existing maps on the left panel
3. **Create New**: Click the "+" button and then the "New Map" button to create a new one

<img alt="NikaMap Create" />

### Name Your Map

1. **Right-click** on your new map to open the rename dialog
2. **Enter a descriptive name** like "My Visualization Project"
3. **Click "Save"** to finalize

<img alt="Map Naming" />

**Pro Tip**: Use clear, descriptive names that will help you identify your map later.

## Step 2: Prepare Your Sample Data

For this tutorial, you'll need three types of sample data:

### Vector Data ([Download Sample File](https://drive.google.com/file/d/1vzdqgcTXbEGNS_Q_uuwQq00D3jLeD75c/view?usp=sharing))

* **GeoJSON file**: Contains point, line, or polygon features
* **Shapefile**: Traditional GIS vector format
* **CSV with coordinates**: Tabular data with latitude/longitude columns

### Raster Data ([Download Sample File](https://storage.cloud.google.com/raster-datasources/Hansen%20GFC%202023%20v1.11%2000N%20050W.tif?authuser=0))

* **GeoTIFF**: High-quality raster imagery or elevation data
* **COG**: Cloud optimized geotiff raster images with the same file extension as .tiff or .tif

### Image Data ([Download Sample File](https://www.globhe.com/sample-drone-data))

* **JPEG**: High-resolution images for overlay

**Download Sample Data**: Click links above to download if you do not have some of these formats to try in NikaMap

## Step 3: Add Vector Layers

### Upload Vector Data

1. **Open Files Panel**: Click "Files" in the left sidebar
2. **Select your vector file** (GeoJSON, Shapefile, or CSV)
3. **Right-click** and select "Add to Map" with your map selected
4. **Wait for processing** - larger files may take a moment

<img alt="Upload Files" />

### Verify Layer Addition

* **Check the layers panel** on the left side
* **Your vector layer** should appear in the list
* **Layer will be visible** on the map automatically

## Step 4: Style Your Vector Layers

### Access Vector Styling

1. **Right-click** on your vector layer in the layers panel
2. **Select "Layer Styles"** from the context menu
3. **Styling panel opens** with customization options

<img alt="Vector Layer Styling" />

### Customize Vector Appearance

#### For Point Layers:

* **Icon Color**: Set point symbol color using the color picker
* **Opacity**: Adjust transparency (0-100%)

#### For Line Layers:

* **Line Color**: Choose line color from the color picker
* **Line Width**: Set thickness using the slider (in pixels)
* **Opacity**: Control transparency

#### For Polygon Layers:

* **Fill Color**: Set interior color of polygons
* **Opacity**: Adjust fill transparency
* **Line Color/Width**: Customize polygon borders

### Layer Organization

* **Reorder layers** by dragging them in the layers panel
* **Bottom layers** appear on top of the map
* **Toggle visibility** using the eye icon

<img alt="Layers Panel" />

## Step 5: Add and Style Raster Layers

### Upload Raster Data

1. **Select your raster file** (GeoTIFF, JPEG with georeference)
2. **Add to map** drag the .tiff file from your desktop into middle section of the opened NikaMap to upload it directly
3. **Wait for processing** - raster files may take longer

<img alt="Drag from Desktop" />

### Access Raster Styling

1. **Right-click** on your raster layer
2. **Select "Layer Styles"** to open the styling panel

<img alt="Raster Layer Styling Overview" />

### Choose Visualization Type

#### Single Channel Mode:

* **Select one band** (b1, b2, b3, etc.)
* **Set data range** using min/max sliders
* **Apply color map** (grayscale, blues, greens, etc.)

#### RGB Channels Mode:

* **Assign bands** to Red, Green, and Blue channels
* **Set individual ranges** for each color channel
* **Create natural or false color** composites

<img alt="Visualization Types" />

### Adjust Data Range

1. **View histogram** showing data distribution
2. **Drag sliders** to set optimal min/max values
3. **See real-time updates** on the map

<img alt="Band Range Control" />

### Select Color Maps

Choose from various color schemes:

* **Grayscale**: For general data visualization
* **Sequential colors**: For continuous data (elevation, temperature)
* **Specialized**: Rainbow, Viridis, Plasma for complex data

<img alt="Color Map Options" />

## Step 6: Add Image Overlays

### Upload Image Data

1. **Select your image file** (JPEG, PNG)
2. **Add to map** using drag-and-drop or right-click
3. **Position appropriately** in the layer stack

### Image Layer Management

* **Adjust opacity** to blend with underlying layers
* **Reorder layers** to control stacking
* **Toggle visibility** as needed

## Step 7: Finalize Your Visualization

### Layer Organization

1. **Arrange layers logically**: Background to foreground
2. **Set appropriate opacity** for each layer
3. **Ensure proper stacking order**

### Export Your Map

1. **Right-click** on individual vector layers to export as GeoJSON
2. **Right-click** on layer groups to export as GeoPackage
3. **Choose destination**: Desktop or NikaWorkspace storage

<img alt="Layer Export" />

### Share Your Visualization

* **Publish your map** for public sharing
* **Collaborate** with team members
* **Export high-resolution** images for presentations

## Best Practices for Map Visualization

### Data Preparation

* **Use appropriate file formats** for your data type
* **Ensure proper coordinate systems** (will auto-convert to EPSG:3857)
* **Keep file sizes reasonable** for optimal performance

### Visual Design

* **Choose complementary colors** for different layer types
* **Use opacity effectively** to show multiple layers
* **Consider colorblind-friendly** color schemes when possible

### Performance Optimization

* **Limit the number** of simultaneous layers
* **Simplify complex geometries** when possible
* **Use appropriate zoom levels** for detailed data

### Layer Management

* **Use descriptive names** for all layers
* **Group related layers** together
* **Remove unused layers** to keep maps clean

## Troubleshooting Common Issues

### Layer Not Appearing

* **Check visibility**: Ensure the eye icon is enabled
* **Zoom to layer**: Double-click layer name to zoom to extent
* **Verify coordinate system**: Data should have proper spatial reference

### Performance Issues

* **Reduce file sizes**: Simplify large datasets
* **Limit active layers**: Hide unnecessary layers
* **Refresh browser**: Clear cache if needed

### Styling Problems

* **Reset styling**: Use reset button in styling panel
* **Check data ranges**: Ensure min/max values are appropriate
* **Verify layer order**: Ensure proper stacking

## Next Steps

Now that you've mastered basic map visualization:

1. **Explore Advanced Styling**: Learn about attribute-based styling and custom color schemes
2. **Create Interactive Maps**: Add popups and interactive features
3. **Collaborative Mapping**: Work with team members on shared projects
4. **Publish and Share**: Make your visualizations public

Happy visualizing!


# ADSB Flight Data
Source: https://docs.nikaplanet.com/industrial-solutions/adsb-flight-data

Comprehensive data pipeline for downloading, processing, and visualizing ADS-B flight tracking data with regional GeoJSON generation

# ADSB Flight Data

<img alt="ADSB Flight Data" />

## ADSB Flight Data Processing and GeoJSON Visualisation Pipeline

A comprehensive data pipeline that downloads, processes, and visualizes ADS-B (Automatic Dependent Surveillance-Broadcast) flight tracking data from June 2024. The system extracts flight traces from GitHub releases, processes them into a DuckDB database, and generates regional GeoJSON files for flight path visualisation.

## Libraries Needed

### Core Libraries

* **os** - File system operations
* **requests** - HTTP requests for downloading data
* **tarfile** - Archive extraction
* **gzip** - Compressed file handling
* **json** - JSON data parsing

### Database & Data Processing

* **duckdb** - High-performance analytical database
* **pandas** - Data manipulation and analysis
* **numpy** - Numerical computing

### Utilities

* **datetime / time** - Date/time operations
* **pathlib.Path** - Modern path handling
* **collections.defaultdict** - Data structures
* **multiprocessing.Pool** - Parallel processing
* **concurrent.futures** - Asynchronous execution
* **tempfile** - Temporary file management
* **shutil** - High-level file operations
* **urllib3.util.retry** - HTTP retry strategies
* **requests.adapters.HTTPAdapter** - HTTP session configuration

## Input Files

### GitHub Release Archives

* v2024.06.01-planes-readsb-staging-0 through v2024.06.30-planes-readsb-staging-0

### Compressed JSON Files

* .json.gz, .json files containing flight trace data

### Split TAR Archives

* .tar.aa, .tar.ab, .tar.gz files

### Flight Trace JSON Structure

* **icao** - Aircraft identifier
* **registration** - Aircraft registration
* **trace** - Array of \[timestamp, latitude, longitude, altitude, heading, speed, vertical\_rate]
* **aircraft\_type** - Aircraft model
* **description** - Aircraft description

## Output Files

### DuckDB Database

* **adsb\_june.duckdb, adsb\_dat\_main.duckdb** - Structured flight data storage

### Temporary Parquet Files

Intermediate data storage for parallel processing

### Regional GeoJSON Files

* **north\_america\_flights.geojson**
* **europe\_flights.geojson**
* **asia\_flights.geojson**
* **africa\_flights.geojson**
* **australia\_flights.geojson**
* **oceania\_flights.geojson**
* And other regional flight path visualizations

### Flight Traces Table Schema

* Aircraft metadata (ICAO, registration, type)
* Positional data (latitude, longitude, altitude)
* Movement data (speed, heading, vertical rate)
* Temporal data (timestamps, sequences)

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/3a4b70be-a02d-44f6-a10e-30f3bb10efb1">
      View Full Solution →
    </a>
  </div>
</div>


# Flood Risk Data LULC In Urban Areas
Source: https://docs.nikaplanet.com/industrial-solutions/flood-risk-data-lulc-urban-areas

Prepare core geospatial layers for analyzing flood-prone areas in Bangkok using elevation, land cover, and rainfall data

# Flood Risk Data LULC In Urban Areas

<img alt="Flood Risk Data LULC In Urban Areas" />

This script prepares core geospatial layers for analyzing flood-prone areas in Bangkok. It exports elevation, land cover (water and built-up areas), and October 2023 rainfall data to local GeoTIFF files using Google Earth Engine and geemap. The outputs are used for flood vulnerability analysis, especially in low-lying, urbanized zones.

## Output File

`/data/bangkok_flood_native`

## Requirements

| Requirement | Details |
| - | - |
| **Software** | Python 3.x, Earth Engine Python API, geemap |
| **Earth Engine** | Enabled Google Earth Engine account ([https://signup.earthengine.google.com](https://signup.earthengine.google.com)) |
| **Python Packages** | geemap, earthengine-api, os, ee |
| **Internet** | Required for Earth Engine data download |

## Files Created

| Filename | Description | Resolution |
| - | - | - |
| **dem\_srtm.tif** | Elevation data from SRTM (clipped to AOI) | 30 m |
| **dw\_water\_built\_mask.tif** | Masked Dynamic World image (1=Water, 2=Built) | 10 m |
| **rainfall\_oct2023\_chirps.tif** | CHIRPS total rainfall for Oct 2023 | \~5.5 km |

## High-Level Workflow Steps

### 1. Setup and Define AOI

Define Bangkok's location and buffer by 10 km to create an Area of Interest (AOI).

### 2. Export SRTM Elevation

* Use the **USGS/SRTMGL1\_003** dataset
* Export as `dem_srtm.tif` at 30 m resolution

### 3. Export Landcover (Water & Built)

* Use the **Google Dynamic World** dataset for 2023
* Use `.mode()` to get the most frequent class
* Remap values: 0 → Water (1), 6 → Built (2), others → 0
* Export as `dw_water_built_mask.tif` at 10 m resolution

### 4. Export Rainfall

* Use **CHIRPS Daily** rainfall dataset
* Sum rainfall for October 2023
* Export as `rainfall_oct2023_chirps.tif` at \~5.5 km resolution

## Flood Risk Classification

This script generates a flood risk classification map of Bangkok using:

* **SRTM DEM (Elevation at 30m)** to identify low-lying areas (\< 5 meters elevation)
* **Dynamic World Landcover (10m)** to locate built-up and water regions

### Output: Flood-Prone Map

You get a matplotlib map showing flood-prone areas based on both elevation and landcover:

#### Legend Explained

| Color | Label | Meaning |
| - | - | - |
| 🔵 **Blue** | Low-lying Water | Areas classified as water in DW and below 5 meters elevation |
| 🔴 **Red** | Low-lying Built-up | Areas classified as built-up and below 5 meters elevation |

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/805c0468-273d-402c-8b0e-774835236df2">
      View Full Solution →
    </a>
  </div>
</div>


# Mean Sea Level Effect On Coastal Regions
Source: https://docs.nikaplanet.com/industrial-solutions/mean-sea-level-coastal-regions

Sea level rise impact analysis for Manila, Philippines using DEM-based scenarios and IPCC AR6 projections

# Mean Sea Level Effect On Coastal Regions

<img alt="Mean Sea Level Effect On Coastal Regions" />

## Sea Level Rise Impact Analysis for Manila, Philippines

### Purpose

This notebook provides two approaches to analyze the impact of sea level rise on Manila's coastal areas:

1. **DEM-based fixed sea level rise scenarios** (0.5m, 1m, 2.5m) using Copernicus DEM and population density
2. **IPCC AR6 regional sea level projections** for selected SSP scenarios and years, combined with DEM and population density

### Date

Thursday, July 3, 2025

## Required Libraries

* **earthengine-api**
* **geemap**
* **numpy**
* **matplotlib**

## Data Sources

### DEM

**Copernicus DEM GLO-30** (30m resolution) from Google Earth Engine

### Population Density

**GPWv411** from Google Earth Engine

### Sea Level Projections

**IPCC AR6 Sea Level Projections Regional (Medium Confidence)** from Google Earth Engine

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/f39a0d8d-0aed-401f-871c-2665d86b97f0">
      View Full Solution →
    </a>
  </div>
</div>


# Mineral and Vegetation Index Calculation from Sentinel-2 Imagery
Source: https://docs.nikaplanet.com/industrial-solutions/mineral-vegetation-index-sentinel2

Calculate remote sensing indices for geological and environmental applications using different band combinations of satellite imagery

# Mineral and Vegetation Index Calculation from Sentinel-2 Imagery

<img alt="Mineral and Vegetation Index Calculation from Sentinel-2 Imagery" />

## Mineral and Vegetation Index Calculation from Satellite Imagery

This Python script is designed to process GeoTIFF files, which are a common format for satellite and aerial imagery. The script calculates a series of remote sensing indices—specifically, mineral and vegetation indices—using different band combinations of the input imagery. It performs calculations like those for Ferrous Iron, Iron Oxide, Clay Minerals, Hematite, Gossan Minerals, Ferric Iron, NDVI (Normalized Difference Vegetation Index), Iron Oxide NIR, and Mineral Alteration NIR. The script then saves the calculated index values as new GeoTIFF files and generates two types of visualizations for each index: one showing the full range of values and another highlighting areas with high concentrations (above the 95th percentile). This process is useful for geological and environmental remote sensing applications, such as identifying potential mineral deposits or assessing vegetation health.

## Libraries Used

* **numpy**: Used for efficient numerical operations and array manipulation, which is essential for performing calculations on the image data
* **rasterio**: A key library for reading and writing geospatial raster data. It handles the I/O of GeoTIFF files, including their crucial metadata like coordinate reference systems and transformations
* **matplotlib.pyplot**: Used for creating static, interactive, and animated visualizations of the index results
* **os**: Provides a way to interact with the operating system, allowing the script to manage file paths and create directories
* **pathlib**: An object-oriented filesystem path library used for handling file paths more cleanly and cross-platform

## Input and Output Datasets

### Input Dataset

* One or more GeoTIFF (.tif or .tiff) files containing multi-band satellite imagery
* The script is designed to read these files from the specified input\_dir (/data/COPERNICUS/)
* The band numbers b1, b2, b3, etc., in the expressions correspond to the bands in the input TIFF file

### Output Datasets

For each input TIFF file, the script creates a new directory within the output\_dir (/data/Australia\_rare\_earth\_mine\_output/).

**Two GeoTIFF files are generated for each calculated index:**

* **.tif**: A GeoTIFF file containing the calculated index values for the full range of data
* **\_HighConcentration.tif**: A GeoTIFF file containing only the top 5% of index values, with the rest of the data set to a "no data" value (NaN). This highlights high-concentration areas

**One PNG visualization file is generated for each index:**

* **\_visualization.png**: A single image file with two subplots: one showing the full-range index and another showing the high-concentration areas on a transparent background for easy identification

## Step-by-Step Implementation

### STEP-1: Sample Area Selection

The mine near Lenister area in Australia is taken as a sample using the geojson provided.

**Upload or create a new vector BBOX using DRAW function tab in Nika Map**

**Use data catalog to download the AOI as shown below**

The output is saved in `data/COPERNICUS`

### STEP-2: Code Execution

Run the code below:

Output saved in `/data/Australia_rare_earth_mine_output/S2_SR_HARMONIZED_composite_2025-08-20T04-01-49-420Z/`

**For each mineral profile:**

* The corresponding single channel TIF image is formed
* A second TIF image highlighting the highest concentration more than 95% percentile is saved separately (example: `ClayMineral_High_concentration.tif`)

**To make it more appealing:**

* Change the raster color to red using raster settings color
* A PNG image showing the scale of intensity is saved for each mineral component

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/b3a90269-8e48-406a-872e-4d05d38972b7">
      View Full Solution →
    </a>
  </div>
</div>


# River Corridor Urbanisation
Source: https://docs.nikaplanet.com/industrial-solutions/river-corridor-urbanisation

Multi-temporal geospatial analysis with buffer-based proximity assessment to quantify urban encroachment patterns within river corridors

# River Corridor Urbanisation

<img alt="River Corridor Urbanisation" />

## Methodology

The analysis employs multi-temporal geospatial analysis with buffer-based proximity assessment to quantify urban encroachment patterns within river corridors through statistical comparison of built-up surface densities across defined temporal intervals.

## Software & Libraries

### Google Earth Engine API

Cloud-based geospatial processing platform

### Python Environment with Essential Packages

* **earthengine-api** - Earth Engine Python client
* **geopandas** - Vector data processing and analysis
* **rasterio** - Raster data I/O and manipulation
* **numpy** - Numerical computing and array operations
* **matplotlib** - Visualization and plotting
* **seaborn** - Statistical data visualization
* **scipy** - Statistical analysis and KDE calculations

## Data Sources

* **WWF HydroSHEDS Free Flowing Rivers Dataset** - Global river network vector data
* **JRC/GHSL/P2023A/GHS\_BUILT\_S** - Built-up surface density raster collection (1990-2020)
* **Service Account Credentials** - JSON authentication file for Earth Engine API access

## Computational Requirements

### Google Earth Engine Quota

Processing credits for cloud computation

### Local Storage

Minimum 2-5 GB for exported datasets and outputs

### Memory

8+ GB RAM recommended for raster processing

### Processing Power

Multi-core CPU for local statistical computations

## Output Files

### Geospatial Data Exports

* **river\_buffer\_corridor.geojson** - 500m buffered river zones vector file
* **built\_up\_1990.tif** - Baseline built-up density raster (1990)
* **built\_up\_2020.tif** - Current built-up density raster (2020)
* **change\_raw\.tif** - Raw change in built-up density (2020-1990)
* **change\_percentage.tif** - Percentage change in built-up density
* **major\_development\_zones.tif** - High-impact development areas

### Analytical Outputs

* **encroachment\_statistics.csv** - Comprehensive statistical summary table
* **environmental\_impact\_categories.csv** - Pixel classification by impact levels
* **temporal\_analysis\_results.json** - Calculated metrics and trend indicators

### Visualization Products

* **comprehensive\_analysis\_dashboard.png** - Multi-panel analytical figure
* **spatial\_distribution\_maps.png** - Built-up density spatial comparisons
* **statistical\_distributions.png** - Histograms and KDE plots
* **trend\_projections.png** - Future urbanization scenario plots
* **environmental\_risk\_assessment.png** - Risk gauge and impact visualizations

## High-Level Steps

### 1. Geospatial Data Preparation

Initialize Earth Engine API, define AOI boundaries, configure output directories for data export

### 2. River Corridor Delineation

Extract river networks from HydroSHEDS dataset, apply 500m buffer zones, export corridor geometries as vector data

### 3. Built-up Surface Extraction

Acquire JRC/GHSL built-up datasets for target years (1990, 2020), clip to river corridors, normalize density values to percentages

### 4. Temporal Change Computation

Calculate raw change metrics (2020-1990), derive percentage change rates, identify major development zones through threshold analysis

### 5. Statistical Aggregation

Compute descriptive statistics (mean, median, standard deviation) for each temporal layer, mask NoData values, categorize environmental impact levels

### 6. Multi-dimensional Visualization

Generate comprehensive analytical dashboard with spatial maps, temporal comparisons, statistical distributions, trend projections, and risk assessment gauges

### 7. Environmental Impact Assessment

Synthesize quantitative metrics into urbanization rates, encroachment patterns, and future risk projections with detailed interpretative reporting

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/db6a68b4-a53a-4326-8422-d718465a4416">
      View Full Solution →
    </a>
  </div>
</div>


# River Ecology Stress Hotspot
Source: https://docs.nikaplanet.com/industrial-solutions/river-ecology-stress-hotspot

Identify river segments with highest urban development pressure and measure rapid urbanization areas along river corridors

# River Ecology Stress Hotspot

<img alt="River Ecology Stress Hotspot Analysis" />

## Hotspot Detection

Identify river segments with highest urban development pressure. Measure the rapid urbanization areas along the river corridor and highlight the region where the most massive urbanization has happened.

## Description

This project analyzes urbanization hotspot trends within river corridors of the Chennai Metropolitan Area between 1990 and 2020 using Google Earth Engine and the Global Human Settlement Layer (GHSL) data. It provides comprehensive spatial and statistical insights into built-up area changes, assessing environmental risks and projecting future trends.

## Resources Needed

### Google Earth Engine (GEE) Account

Access to the GEE platform is essential for data processing and analysis.

### GEE Service Account Credentials

A service account email and a corresponding JSON key file are required for programmatic authentication to GEE.

### Python Environment

A Python installation (3.8 or higher recommended) with the following libraries:

* **ee** - Google Earth Engine Python API
* **geemap** - Interactive mapping with Google Earth Engine
* **rasterio** - Geospatial raster data I/O
* **geopandas** - Geospatial data manipulation and analysis
* **numpy** - Numerical computing
* **pandas** - Data manipulation and analysis
* **matplotlib** - Plotting and visualization
* **seaborn** - Statistical data visualization
* **scipy** - Scientific computing
* **scikit-learn** - Machine learning algorithms
* **shapely** - Geometric operations

## Output

The script will produce the following outputs in a newly created directory named `[analysis_output_directory]`:

### GeoJSON Files

* **\[primary\_features].geojson**: Vector file representing the main geographic features or analysis zones
* **\[analysis\_regions].geojson**: Vector file containing processed spatial analysis regions

### GeoTIFF Files

* **\[baseline\_data].tif**: Raster image of baseline conditions for the specified time period
* **\[current\_data].tif**: Raster image of current conditions for comparison analysis
* **\[change\_analysis].tif**: Raster image showing change patterns between time periods
* **\[derived\_metrics].tif**: Raster image of calculated indices or composite metrics
* **\[classification\_results].tif**: Raster image showing classified categories or zones

### PNG Image Files

* **\[comprehensive\_analysis].png**: Multi-panel figure summarizing the analysis with spatial maps, statistical plots, and key findings
* **\[detailed\_analysis].png**: In-depth visualization showing specific patterns, trends, and additional statistical breakdowns

### CSV Files

* **\[analysis\_summary].csv**: Tabular summary of key statistical metrics and results
* **\[detailed\_statistics].csv**: Comprehensive statistical output with segment-wise or zone-wise metrics

### Console Output

Detailed progress messages, processing status, statistical summaries, and final analysis results.

## Methodology and High-Level Steps

### 1. Earth Engine Initialization

Authenticate Google Earth Engine API using service account credentials and configure cloud computing environment.

### 2. Configuration Setup

Define Area of Interest (AOI), establish output directory structure, and set analysis parameters including thresholds and buffer distances.

### 3. Data Processing (Google Earth Engine)

Load datasets from Earth Engine catalog, apply spatial/temporal filters, perform geometric operations, process raster imagery, calculate change metrics, and export GeoJSON/GeoTIFF files.

### 4. Local Data Integration

Load exported GeoJSON files into GeoPandas and GeoTIFF files using rasterio, then validate data integrity.

### 5. Statistical Analysis

Mask NoData values, calculate comprehensive statistics, perform zone-wise analysis, compute derived metrics, and apply statistical validation procedures.

### 6. Classification and Ranking

Develop scoring algorithms, apply threshold-based classification, rank features by calculated metrics, and perform spatial clustering analysis.

### 7. Comprehensive Visualization

Generate multi-panel matplotlib figures with spatial maps, statistical plots, comparative visualizations, and apply appropriate styling for clarity.

### 8. Results Compilation and Export

Compile analytical results into structured formats, generate CSV files and comprehensive reports, and organize outputs with clear naming conventions.

### 9. Quality Assurance and Validation

Implement error handling, perform validation checks, document processing steps, and generate processing logs for reproducibility.

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/6b209516-1187-4e18-8c3e-274867094483">
      View Full Solution →
    </a>
  </div>
</div>


# River Urbanisation With Major Cities Comparisons
Source: https://docs.nikaplanet.com/industrial-solutions/river-urbanisation-major-cities-comparisons

Process satellite imagery to analyze urban development patterns across multiple regions with statistical summaries and comparison plots

# River Urbanisation With Major Cities Comparisons

<img alt="River Urbanisation With Major Cities Comparisons" />

## River Basin Urban Development Analyzer

Processes satellite imagery (built-up, water, NDVI) to analyze urban development patterns across multiple regions, generating statistical summaries, comparison plots, and detailed land use classifications.

## Requirements

| Requirement | Details |
| - | - |
| **Software** | Python 3.x, rasterio, matplotlib, pandas, numpy |
| **Data Sources** | Pre-downloaded satellite imagery (Built-up, Water, NDVI, Satellite) |
| **Python Packages** | rasterio, numpy, pandas, matplotlib, seaborn, geopandas, shapely, pathlib |

## Input Data

TIF files for each region: `*_buildup.tif`, `*_water.tif`, `*_ndvi.tif`, `*_satellite.tif`

## Files Created

| Filename | Description | Format |
| - | - | - |
| **region\_summary.csv** | Statistical summary for all analyzed regions | CSV |
| **comparison\_analysis.png** | 4-panel comparison plots across all regions | PNG (300 DPI) |
| **\_detailed\_analysis.png** | Detailed 4-panel analysis for each region | PNG (300 DPI) |
| **analysis\_report.md** | Comprehensive markdown report with insights | Markdown |

## High-Level Workflow Steps

### 1. Region Discovery & Data Loading

Auto-discover regions from `*_buildup.tif` files in data directory

Load corresponding water, NDVI, and satellite imagery for each region

Handle nodata values and coordinate transformations

### 2. Statistical Analysis

Calculate built-up area coverage and intensity (hectares & percentages)

Analyze water occurrence (permanent vs seasonal water bodies)

Compute vegetation indices (NDVI-based green cover analysis)

Generate composite land use statistics

### 3. Urban Classification

* **Dense Urban**: >50% built-up coverage
* **Moderate Urban**: 25-50% built-up coverage
* **Low Urban**: 10-25% built-up coverage
* **Rural/Natural**: \<10% built-up coverage

### 4. Visualization Generation

**Comparison Plots**: 4-panel matplotlib figure with scatter plots, bar charts, and pie charts

**Regional Details**: Individual 4-panel analysis showing built-up, water, NDVI, and land use classification

**Static PNG Output**: High-resolution images suitable for reports and publications

### 5. Report Generation

Regional rankings (most urbanized, highest water coverage, most vegetated)

Key insights and development patterns

Comprehensive data tables with all calculated metrics

## Output Analysis Capabilities

This script generates comprehensive urban development assessment using:

* **Built-up Intensity Maps** - Identifies urban development patterns and density
* **Water Occurrence Analysis** - Distinguishes permanent vs seasonal water bodies
* **Vegetation Health (NDVI)** - Maps green cover and vegetation density
* **Land Use Classification** - Composite analysis of urban, water, vegetation, and other land uses

## Visualization Outputs

### Comparison Analysis (4-Panel Plot)

* **Built-up vs Water Coverage Scatter** - Shows relationship between urbanization and water presence (colored by NDVI)
* **Vegetation Distribution Bar Chart** - Compares green cover across all regions
* **Urban Development Intensity** - Color-coded by urban classification (Dense/Moderate/Low/Rural)
* **Average Land Use Pie Chart** - Overall composition of built-up, water, vegetation, and other land uses

### Detailed Regional Analysis (Per Region)

* **Built-up Areas Map** - Red intensity showing urban development density
* **Water Occurrence Map** - Blue gradient showing water body frequency (0-100%)
* **Vegetation Index (NDVI)** - Green-red gradient showing vegetation health (-0.2 to 0.8)
* **Land Use Classification** - Categorical map (Urban=Red, Water=Blue, Vegetation=Green, Other=Black)

## Key Metrics Calculated

| Category | Metrics |
| - | - |
| **Built-up** | Mean intensity, max intensity, total area (ha), high-density area (ha), percentage coverage |
| **Water** | Mean occurrence, permanent water area (>80%), seasonal water area (20-80%), percentage coverage |
| **Vegetation** | Mean NDVI, vegetation area (>0.3), dense vegetation (>0.5), bare soil area, percentage coverage |
| **Composite** | Total area, urban classification, development patterns, land use ratios |

## Analysis Insights Generated

* **Urban Pressure Assessment** - Identifies regions with high development pressure
* **Water Resource Mapping** - Quantifies permanent vs seasonal water availability
* **Green Space Evaluation** - Measures vegetation cover and ecological health
* **Development Patterns** - Reveals relationships between urbanization and environmental factors

## Result

Multi-scale urban development analysis with both regional comparisons and detailed local assessments for sustainable planning and environmental monitoring.

## Output

### Quick Summary

| region | buildup\_percentage | water\_percentage | urban\_class |
| - | - | - | - |
| ahmedabad\_sabarmati | 96.981293 | 5.442177 | Dense Urban |
| delhi\_yamuna | 84.551857 | 4.091872 | Dense Urban |
| kolkata\_hooghly | 93.197279 | 6.998953 | Dense Urban |
| pune\_rivers | 96.072101 | 2.199354 | Dense Urban |

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/b3a90269-8e48-406a-872e-4d05d38972b7">
      View Full Solution →
    </a>
  </div>
</div>


# Singapore MRT Yearly Visualisation
Source: https://docs.nikaplanet.com/industrial-solutions/singapore-mrt-yearly-visualisation

Process Singapore MRT rail network GeoJSON and split into separate files organized by year and rail line for historical development analysis

# Singapore MRT Yearly Visualisation

<img alt="Singapore MRT Yearly Visualisation" />

## Singapore MRT Rail Network GeoJSON Year-wise Line Splitter

### Description

This Python script processes a comprehensive Singapore MRT (Mass Rapid Transit) rail network GeoJSON file and splits it into separate files organized by year and rail line. It normalizes line names, assigns feature numbers, and creates individual GeoJSON files for each line's opening year, making it easier to analyze the historical development of Singapore's rail transit system.

## Data Sources

### Primary Input

**sg-rail\_with\_years\_patched.geojson** - A comprehensive GeoJSON file containing Singapore's entire rail network with temporal data

### Input Directory

`/data/singapore_mrt/main_source_folder/`

## Input Data Structure

### Geometry Types Processed

* **LineString/MultiLineString** (rail lines)
* **Point** (stations/stops)
* **Polygon/MultiPolygon** (areas/zones)

### Required Properties

* **year**: Opening year of the rail segment
* **name**: Name/identifier of the rail line

## Rail Lines Covered

* **North South Line (NSL)**
* **East West Line (EWL)**
* **North East Line (NEL)**
* **Circle Line (CCL)**
* **Downtown Line (DTL)**
* **Thomson-East Coast Line (TEL)**
* **Bukit Panjang LRT (BPLRT)**
* **Sengkang LRT with East/West loops (SKLRT)**
* **Punggol LRT with East/West loops (PGLRT)**

## Output

### Generated Files

**Year-Line Specific Files**: Numbered GeoJSON files for each line-year combination

**Format**: `XX_singapore_[LINE_CODE]_[YEAR].geojson`

**Example**: `01_singapore_NSL_1987.geojson`

### Aggregated Files

* **singapore\_all\_points.geojson** - All station/point features
* **singapore\_all\_polygons.geojson** - All polygon/area features

### Output Directory

`/data/singapore_mrt/year_wise_geojsons_new/`

## Output Enhancements

### Feature Numbering

Each feature gets a sequential number property

### Normalized Codes

Standardized line codes (NSL, EWL, etc.)

### Chronological Organization

Files sorted by opening years (1987-2020)

## Libraries Used

### Core Python Libraries

* **os**: File system operations and directory management
* **json**: JSON file reading, writing, and manipulation
* **collections.defaultdict**: Efficient nested dictionary creation for grouping features

### Geospatial Libraries

* **shapely.geometry**:
  * **shape**: Converting GeoJSON geometry to Shapely objects
  * **mapping**: Converting Shapely objects back to GeoJSON format
  * Used for potential geometric operations (imported but not actively used in current implementation)

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/08279572-a80e-4cca-a8d2-79c54817d35c">
      View Full Solution →
    </a>
  </div>
</div>


# Urban Construction Near Riparian Areas
Source: https://docs.nikaplanet.com/industrial-solutions/urban-construction-riparian-areas

Analyze riparian zone urbanization gradients and quantify built-up surface density changes with distance from river systems

# Urban Construction Near Riparian Areas

<img alt="Urban Construction Near Riparian Areas" />

## Riparian Zone Urbanization Gradients

This project performs an analysis of riparian zone urbanization gradients near the Amazon River, specifically focusing on a defined area near Manaus. It quantifies how built-up surface density changes with increasing distance from river systems, providing insights into human impact on riparian ecosystems.

## Resources Needed

### Software

* Python 3.x

### Libraries

* **earthengine-api**: For interacting with Google Earth Engine
* **pandas**: For data manipulation and analysis
* **matplotlib**: For creating static, interactive, and animated visualizations in Python
* **numpy**: For numerical operations
* **seaborn**: For statistical data visualization
* **Pillow (PIL)**: For image processing
* **requests**: For making HTTP requests (e.g., downloading images)

### Google Earth Engine Account

An active Google Earth Engine account is required to access the spatial datasets.

### Internet Connection

Essential for accessing Earth Engine data and services.

## Input Files

This project does not require explicit input files from your local machine. All necessary spatial data is accessed directly from the Google Earth Engine data catalog:

* **WWF/HydroSHEDS/v1/FreeFlowingRivers**: Global dataset of free-flowing rivers
* **JRC/GHSL/P2023A/GHS\_BUILT\_S**: Global Human Settlement Layer (GHSL) Built-up Surface dataset for 2020
* **FAO/GAUL/2015/level2** (Optional): Administrative boundaries used if the AOI is defined by an administrative name (not used in the provided code's default AOI)

## Output Files

The project generates output files within a newly created output folder:

* **riparian\_amazon\_analysis\_YYYYMMDD\_HHMMSS.png**: A high-resolution PNG image of the generated plots, visualizing the urbanization gradient and the spatial distribution of buffer zones
* **riparian\_amazon\_results\_YYYYMMDD\_HHMMSS.csv**: A CSV file containing the detailed urbanization metrics for each riparian buffer zone, including area, mean built-up percentage, and standard deviation
* **riparian\_amazon\_summary\_YYYYMMDD\_HHMMSS.txt**: A text file providing a summary report of the analysis, including key statistics, correlations, and a breakdown of built-up percentages per zone

## Step-by-Step Analysis

### 1. Initialize Earth Engine

Authenticate and initialize the Google Earth Engine API to enable data access.

### 2. Define Area of Interest (AOI)

Specify the geographical region for the analysis, in this case, a rectangle near Manaus, Amazon River.

### 3. Load Datasets

Import the HydroRIVERS dataset for river networks and the GHSL Built-up Surface dataset for urbanization data from Earth Engine.

### 4. Filter Rivers

Clip and filter the global HydroRIVERS dataset to retain only the river segments within the defined AOI.

### 5. Create Buffer Zones

Generate non-overlapping buffer rings around the filtered river segments at specified distances (e.g., 0-100m, 100-200m, etc.).

### 6. Extract Urbanization Metrics

For each buffer zone, calculate descriptive statistics (mean, standard deviation, min, max, pixel count) of the built-up surface percentage using the GHSL data.

### 7. Create Results DataFrame

Organize the extracted urbanization metrics into a pandas DataFrame, adding columns for distance ranges and midpoints for easier analysis.

### 8. Generate Buffer Map Image

Create a static thumbnail image from Earth Engine visualizing the defined buffer zones and rivers within the AOI, with distinct colors for each zone.

### 9. Visualize Gradient

Generate a multi-panel plot including a line plot of urbanization intensity vs. distance, a bar chart of built-up percentages per zone, a scatter plot of area vs. built-up, and the generated buffer map image.

### 10. Perform Statistical Analysis

Calculate key statistics, such as correlation between distance and built-up density, and the average gradient slope, to quantify the urbanization pattern.

### 11. Export Results

Save the detailed results DataFrame to a CSV file, and generate a comprehensive summary report as a text file in a dedicated output folder.

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/d97e260c-17ad-46d1-93bc-e179baea1eff">
      View Full Solution →
    </a>
  </div>
</div>


# Watershed Urban Impact Analysis
Source: https://docs.nikaplanet.com/industrial-solutions/watershed-urban-impact-analysis

Assess the degree of urbanization within individual watersheds and classify them based on urban impact levels

# Watershed Urban Impact Analysis

<img alt="Watershed Urban Impact Analysis" />

## Description

This analysis aims to assess the degree of urbanization within individual watersheds across a specified Area of Interest (AOI). By quantifying the percentage of built-up area within each watershed, we can classify them based on their urban impact level (e.g., Low, Moderate, High, Very High) and generate insights into human impact on these crucial hydrological units.

## Libraries Used

The script leverages several powerful Python libraries for geospatial analysis, data manipulation, and visualization:

* **ee** (Google Earth Engine Python API): Essential for accessing and processing vast amounts of satellite imagery and geospatial datasets on Google's cloud platform
* **geemap**: A Python package built on Earth Engine and Folium that simplifies Earth Engine data visualization and interaction, especially for converting Earth Engine objects to GeoPandas DataFrames
* **pandas**: A fundamental library for data manipulation and analysis, used here for working with tabular data extracted from the geospatial analysis
* **geopandas**: Extends pandas to allow spatial operations on tabular data, enabling the handling of geographic data types (like polygons for watersheds)
* **matplotlib.pyplot**: A widely used plotting library for creating static, interactive, and animated visualizations in Python
* **matplotlib.patches**: Used for creating custom shapes for plot legends
* **seaborn**: A data visualization library based on matplotlib that provides a high-level interface for drawing attractive and informative statistical graphics
* **numpy**: A core library for numerical computing, used for array operations, especially in statistical calculations
* **shapely.geometry.box**: For creating rectangular geometric objects
* **json**: For working with JSON data (though not explicitly used for direct JSON file handling in the main flow, often useful in geospatial contexts)
* **os**: For interacting with the operating system, particularly for managing file paths and creating directories
* **datetime**: For working with dates and times, used here to timestamp the analysis report

## Dataset Inputs

The analysis relies on publicly available datasets hosted on Google Earth Engine:

### HydroATLAS Basins (Level 8)

**Source**: `WWF/HydroATLAS/v1/Basins/level08`

This is a global dataset providing hierarchical hydrological basins (watersheds) at different levels of detail. Level 8 represents relatively detailed catchments. It provides the spatial boundaries of the watersheds for our analysis.

### Global Human Settlement Layer (GHSL) Built-up Surface (2020)

**Source**: `JRC/GHSL/P2023A/GHS_BUILT_S`

This dataset provides information on the presence and density of built-up areas. We specifically use the 2020 data to quantify urban extent within each watershed.

### HydroSHEDS Free Flowing Rivers

**Source**: `WWF/HydroSHEDS/v1/FreeFlowingRivers`

This dataset provides spatial information on rivers, used here primarily for contextual visualization, although not directly used in the urban impact calculation.

## Output Files

Upon successful execution, the script generates several output files in the specified `output_dir` (e.g., `watershed_urban_analysis_results`):

* **watersheds\_urban\_analysis.geojson**: A GeoJSON file containing the watershed geometries along with all calculated urban metrics and impact classifications
* **watersheds\_urban\_analysis.shp**: A Shapefile (a common geospatial vector data format) containing the same watershed data as the GeoJSON
* **watershed\_urban\_analysis\_comprehensive.png**: A high-resolution PNG image presenting a multi-panel visualization, including choropleth maps, histograms, pie charts, and scatter plots of the analysis results
* **watershed\_urban\_statistics.png**: A high-resolution PNG image focusing on detailed statistical visualizations, such as box plots, cumulative distributions, and a summary table
* **analysis\_report.txt**: A plain text file summarizing key statistics, impact classifications, and analysis details

## Step-by-Step Implementation

### 3.1. Initialization and Earth Engine Setup

Import libraries, authenticate Earth Engine using service account credentials, and create output directory structure.

### 3.2. Defining the Analysis Class

Create `WatershedUrbanAnalysis` class encapsulating data loading, metric calculations, classification algorithms, download operations, visualization generation, and comprehensive reporting functionality.

### 3.3. Executing the Data Processing & Download

Instantiate analyzer object with defined AOI and execute `run_complete_analysis()` to trigger cloud-based computations and local data downloads.

### 3.4. Generating Comprehensive Visualizations

Create multi-panel visual summaries including choropleth maps, impact classifications, statistical histograms, categorical distributions, and correlation scatter plots.

### 3.5. Generating the Analysis Report

Consolidate key findings, statistical summaries, and analytical insights into structured text-based report for documentation and interpretation.

## Analysis Results & Discussion

### Summary of Findings

Present average urban coverage metrics, watershed impact category distributions, spatial pattern analysis, and correlation insights from scatter plot relationships.

### Interpretation of Impact Classes

Define impact classification thresholds and contextualize low/moderate/high impact categories within urban coverage framework.

### Limitations

Acknowledge GHSL resolution constraints, HydroBASINS delineation accuracy limitations, and impact threshold definition assumptions.

***

<div>
  <div>
    <h3>🚀 Ready to implement this solution?</h3>
    <p>Access the complete code, step-by-step instructions, and interactive notebook in Nika Hub.</p>

    <a href="https://planet.nika.eco/en/hub/solutions/48654279-e3bc-48be-ae50-2645b1ed8dea">
      View Full Solution →
    </a>
  </div>
</div>


# Autonomous Analysis
Source: https://docs.nikaplanet.com/nika-desktop/autonomous-analysis

How NIKA plans, runs tools, inspects results, and iterates on its own until your geospatial task is complete.

## An Analyst, Not a Chatbot

Most AI tools answer a question and stop. NIKA Desktop works the way a human analyst does: it takes a goal, breaks it into steps, runs the tools needed to make progress, looks at what came back, and keeps going until the job is actually done. You describe the outcome you want in plain language — NIKA figures out and executes the path to get there.

<Frame>
  <img alt="NIKA Desktop running an autonomous, multi-step geospatial analysis with streaming tool calls" />
</Frame>

## The Agentic Tool Loop

NIKA operates in an **agentic tool loop** — it autonomously reads files, executes geospatial operations, inspects the results, and iterates until the task is complete.

<Steps>
  <Step title="Understand the goal">
    NIKA interprets your request in plain language and decides which data and operations the task requires — no menus, no scripting.
  </Step>

  <Step title="Read & inspect your data">
    It opens your files and inspects them — layers, coordinate reference systems, attribute schemas, raster bands and statistics — to ground the analysis in what's actually there.
  </Step>

  <Step title="Run the operations">
    NIKA calls the geospatial tools needed to make progress, from format conversion to spatial operations, and pulls in external or satellite data when the task calls for it.
  </Step>

  <Step title="Inspect the results & iterate">
    It reads the output of each step, checks whether it answers the question, and adjusts its plan — re-running or trying a different approach until the result holds up.
  </Step>

  <Step title="Deliver the artifact">
    When the work is done, NIKA hands back the answer along with the artifact you need — a map, dashboard, chart, or report — rendered directly in the conversation.
  </Step>
</Steps>

## Built for Real Work

<Columns>
  <Card title="Streaming tool calls" icon="bolt">
    Every tool the agent runs streams in real time, so you always know exactly what NIKA is doing and can verify each step of its reasoning.
  </Card>

  <Card title="Multi-step task management" icon="list-check">
    NIKA keeps track of long, multi-stage tasks on its own — chaining operations together and carrying context from one step to the next without losing the thread.
  </Card>

  <Card title="Location-aware reasoning" icon="location-dot">
    Unlike a generic agent, NIKA understands real coordinates and ties every intermediate result back to a real-world place, asset, or geometry.
  </Card>

  <Card title="Persistent sessions" icon="clock-rotate-left">
    Conversations are saved to disk, so you can pick any prior analysis back up exactly where you left off — including the steps the agent already ran.
  </Card>
</Columns>

## Grounded in Your Knowledge

Autonomous analysis gets sharper when the agent can draw on what your organization already knows. Connect [NIKA Memory Core](/nika-desktop/memory-core) and NIKA grounds its answers in your own reports, surveys, and records — so the analysis reflects your institutional knowledge, not just public data.


# Data & Conversion
Source: https://docs.nikaplanet.com/nika-desktop/data-and-conversion

Connect your files and external or satellite data sources, then inspect and convert across 100+ geospatial formats — all from chat.

## Bring Your Own Data

NIKA Desktop meets your data where it already lives. Point the agent at the files and systems your team uses every day, and it reads them in place — no migration, no reformatting, no manual tagging.

<Frame>
  <img alt="NIKA Desktop connecting to files and converting between geospatial formats from the chat" />
</Frame>

<Columns>
  <Card title="Your files" icon="folder-open">
    Reports, PDFs, drawings, field photos, spreadsheets, and raw geospatial datasets — drop them in and the agent works directly with them.
  </Card>

  <Card title="External & satellite data" icon="satellite">
    Pull in the external and satellite data sources your industry already relies on to enrich the analysis with up-to-date context.
  </Card>
</Columns>

## Data Inspection

NIKA includes built-in tools for inspecting geospatial data without leaving the chat.

* **Vector metadata** — read layers, coordinate reference systems, and attribute schemas from any supported vector format
* **Raster metadata** — read dimensions, band counts, CRS, and statistics from any supported raster format

## Format Conversion (100+ Formats)

Convert between formats with a single request to the agent — no GIS desktop software required.

| Category | Formats |
| - | - |
| **Raster** | COG, GeoTIFF, JPEG2000, ECW, MrSID, PNG, JPEG |
| **Vector** | GeoJSON, Shapefile, GeoPackage, FlatGeoBuf, GeoParquet, KML, KMZ, CSV, DXF |
| **Vector Tiles** | PMTiles, MBTiles |
| **3D** | LAS, LAZ, Cesium 3D Tiles, COPC, STL, OBJ, GLB, glTF |
| **Styles** | SLD, QGIS QML |

<Tip>
  Conversions happen inside the [autonomous tool loop](/nika-desktop/autonomous-analysis) — so a single request like *"convert these shapefiles to GeoParquet and map the result"* is handled end to end, with the output ready to [visualize](/nika-desktop/visualizations) immediately.
</Tip>


# NIKA Memory Core
Source: https://docs.nikaplanet.com/nika-desktop/memory-core

Turn your org-level geospatial data such as species distribution, soil analysis, etc into a knowledge base that any user with granted access can query using AI.

## Overview

**NIKA Memory Core** turns years of accumulated specialised knowledge into a queryable, spatially-aware knowledge base — the enterprise brain that remembers everything your organization has ever learned about the places it works. Ingest your documents and NIKA builds a knowledge layer that understands *what* your organization knows and *where* it applies geographically. Any team member — from a new graduate to a project director — can ask questions in plain language and get answers grounded in your organization's own data.

## Example Queries

<Tabs>
  <Tab title="Environmental">
    <div>
      <div>
        <div>
          <div>
            Have we done any Phase 1 habitat surveys within 2km of this site?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Phase 1 Habitat Surveys are used to identify habitats that may support protected species. To find out if your organization has previously surveyed a site, you would need to check your internal project records or document management system. Local ecological data may also be available through Natural England or your local records centre.
          </div>
        </div>

        <div>
          <div>
            That's not what I'm asking — I need to know if WE have already surveyed this specific location, not general advice on where to search.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              Yes — 3 Phase 1 surveys from your archive cover this area. The most recent was March 2022 for the Thornfield Solar Project (ref: TS-2022-HAB-01). Two species of concern were flagged: marsh harrier nesting habitat and great crested newt receptor zones. <span>Sources: TS-2022-HAB-01 p.14, BW-2019-EC-07 p.6</span>
            </div>

            <div>
              <div>SURVEYS FOUND WITHIN 2KM</div>

              <table>
                <thead>
                  <tr>
                    <th>Survey Ref</th>
                    <th>Date</th>
                    <th>Project</th>
                    <th>Species Flagged</th>
                  </tr>
                </thead>

                <tbody>
                  <tr>
                    <td>TS-2022-HAB-01</td>
                    <td>Mar 2022</td>
                    <td>Thornfield Solar</td>
                    <td><span>Marsh Harrier, GCN</span></td>
                  </tr>

                  <tr>
                    <td>BW-2019-EC-07</td>
                    <td>Jun 2019</td>
                    <td>Broadwood Residential</td>
                    <td><span>Water Vole</span></td>
                  </tr>

                  <tr>
                    <td>AM-2017-PH1</td>
                    <td>Sep 2017</td>
                    <td>Ashmill Road Upgrade</td>
                    <td><span>Bat Roosts, Otter</span></td>
                  </tr>
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </div>

      <div />

      <div>
        <div>
          <div>
            Can you show me where we've recorded great crested newts in the Thornfield area and map the survey points?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Great crested newts (Triturus cristatus) are a European Protected Species typically surveyed using torch, bottle-trap, and eDNA methods. To map your records, you would need to export survey coordinates from your ecology database into a GIS tool such as ArcGIS or QGIS, then visualise the points against a base map.
          </div>
        </div>

        <div>
          <div>
            I don't need a GIS tutorial — I need to see where OUR team has actually found them, mapped right now from our own survey files.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              4 GCN records in your Thornfield archive: 2 confirmed breeding ponds (Pond A: SU456214, Pond B: SU453219) and 2 terrestrial buffer habitat zones, both mapped Jun 2022. No confirmed presence in the northern field sections. <span>Sources: TS-2022-GCN p.8, TS-2022-HAB-01 p.12</span>
            </div>

            <div>
              <div>GCN SURVEY RECORDS — THORNFIELD AREA</div>

              <div>
                <div />

                <div />

                <div />

                <div />

                <div />

                <div>
                  <span>THORNFIELD LANE</span>
                </div>

                <div />

                <div />

                <div />

                <span>Pond A</span>

                <div />

                <span>Pond B</span>

                <div>
                  <div />
                </div>

                <span>SU456214</span>

                <div>
                  <div />
                </div>

                <span>SU453219</span>
                <span>No GCN records (northern fields)</span>

                <div>
                  <div>
                    <span>N</span>
                  </div>

                  <div>
                    <span>+</span>
                  </div>

                  <div>
                    <span>−</span>
                  </div>
                </div>

                <div>
                  <div>
                    <div>
                      <div />
                    </div>

                    <span>GCN confirmed record</span>
                  </div>

                  <div>
                    <div />

                    <span>Breeding pond</span>
                  </div>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Infrastructure & Engineering">
    <div>
      <div>
        <div>
          <div>
            I'm on site at the B4440/Millbrook Road junction. What buried services have our own surveys already recorded along this access road alignment?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Before any excavation, you should request a utility search through a service like LSBUD or Dial Before You Dig, and contact individual utility providers. On-site CAT scanning is also recommended. Always follow HSG47 safe digging practices to avoid utility strikes during groundworks.
          </div>
        </div>

        <div>
          <div>
            I know the standard process. My plant operator is here now — I need to know what OUR previous investigations already found on this specific corridor, not how to start a new search.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              Your 2019 Phase 1 ESA for this corridor recorded a 150mm water main (Severn Trent, laid 1987) crossing at chainage 340m, and a BT duct running parallel for \~180m from the junction. <span>Sources: ESA-2019-UTIL p.22, Drawing UTL-04</span>
            </div>

            <div>
              <div>ACCESS ROAD ALIGNMENT — UTILITY SCHEMATIC</div>

              <div>
                <div>
                  <div>Junction</div>

                  <div>
                    <div />

                    <div />

                    <div />
                  </div>

                  <div>End</div>
                </div>

                <div>
                  <div />

                  <div>
                    <div />

                    <div />

                    <div>ch. 340m</div>
                  </div>
                </div>
              </div>

              <div>
                <div><div /><span>BT duct (\~180m from junction)</span></div>
                <div><div /><span>150mm water main crossing (ch. 340m)</span></div>
              </div>
            </div>
          </div>
        </div>
      </div>

      <div />

      <div>
        <div>
          <div>
            What ground conditions were found in the boreholes along this route?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Borehole logs provide information on soil stratigraphy, groundwater levels, and potential contamination. To access specific borehole data for your route, check your project's geotechnical investigation reports. The British Geological Survey (BGS) also provides publicly available borehole records for many locations in the UK.
          </div>
        </div>

        <div>
          <div>
            The reports are back in the office. I'm the engineer and I need a synthesised answer from our own investigation data right now — not a pointer to go look it up myself.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              7 boreholes from the 2021 geotechnical investigation cover this route. Fill material (0.8–2.3m depth) was found in BH-03 to BH-06, likely from a demolished structure. Groundwater struck at 1.4m in 3 locations. Low-to-moderate contamination risk flagged. <span>Sources: GI-2021-GEOTECH p.18–24</span>
            </div>

            <div>
              <div>BOREHOLE SUMMARY — 2021 GEOTECHNICAL INVESTIGATION</div>

              <table>
                <thead>
                  <tr>
                    <th>BH</th>
                    <th>Fill Depth</th>
                    <th>Stratigraphy</th>
                    <th>GW Strike</th>
                  </tr>
                </thead>
              </table>

              <div>
                ⚠ BH-03 to BH-06: made ground present — low-to-moderate contamination risk flagged
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Natural Resources">
    <div>
      <div>
        <div>
          <div>
            What's the water quality trend at monitoring point WQ-07 over the last five years?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Water quality trends are assessed by comparing measured parameters — nitrate, phosphate, pH, dissolved oxygen — against baseline values over time. To analyse a specific monitoring point, compile readings from your monitoring records and plot them against relevant standards such as WFD targets. The Environment Agency's Water Quality Archive may also hold relevant data.
          </div>
        </div>

        <div>
          <div>
            I need the actual numbers from our monitoring files — not a description of methodology. What do OUR readings at WQ-07 actually show?
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              22 monitoring events at WQ-07 (2019–2024) show nitrate levels consistently above 50mg/L since Q3 2021. Peak was 78mg/L in autumn 2022, coinciding with high rainfall. <span>Sources: WQ-Annual-2022 p.11, WQ-Annual-2023 p.9, +2 more</span>
            </div>

            <div>
              <div>NITRATE (mg/L) AT WQ-07 — ANNUAL AVERAGE</div>

              <div>
                <div><div /> Below limit</div>
                <div><div /> Above 50mg/L limit</div>
                <div><div /> 50mg/L threshold</div>
              </div>
            </div>
          </div>
        </div>
      </div>

      <div />

      <div>
        <div>
          <div>
            I'm doing field work at OS grid SP234567. Which of OUR monitoring points are within 2km and what are their latest readings?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            To identify monitoring points near your current location, you would need to run a 2km buffer around your coordinates in a GIS tool such as ArcGIS or QGIS, then overlay this against your monitoring network dataset. Your data management team should be able to run this query and cross-reference the latest readings for you.
          </div>
        </div>

        <div>
          <div>
            I'm in the field without GIS access. I just need to know what OUR nearest monitoring points are and whether anything near me is flagged — right now.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              3 of your monitoring points are within 2km of SP234567: WQ-07 (1.2km NE) is flagged — nitrate above limit since 2021; WQ-12 (1.8km SW) is within WFD targets; WQ-03 (2.0km NW) has elevated phosphate flagged in the 2023 annual report. <span>Sources: WQ-Annual-2024 p.5, WQ-Annual-2023 p.11</span>
            </div>

            <div>
              <div>MONITORING POINTS WITHIN 2KM OF SP234567</div>

              <table>
                <thead>
                  <tr>
                    <th>Point</th>
                    <th>Distance</th>
                    <th>Latest Reading</th>
                    <th>Status</th>
                  </tr>
                </thead>

                <tbody>
                  <tr>
                    <td>WQ-07</td>
                    <td>1.2km NE</td>
                    <td>Nitrate 63 mg/L</td>
                    <td><span>Flagged ↑</span></td>
                  </tr>

                  <tr>
                    <td>WQ-12</td>
                    <td>1.8km SW</td>
                    <td>All params OK — Oct 2024</td>
                    <td><span>Within limits</span></td>
                  </tr>

                  <tr>
                    <td>WQ-03</td>
                    <td>2.0km NW</td>
                    <td>Phosphate 0.12 mg/L</td>
                    <td><span>Elevated ⚠</span></td>
                  </tr>
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Government & Public Sector">
    <div>
      <div>
        <div>
          <div>
            Has this site had any previous planning applications and what were the outcomes?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            Planning history for a site can be found on your local planning authority's online portal or the national Planning Portal at planningportal.co.uk. Search by address or coordinates to return all historical applications and decisions. For enforcement history, check the authority's published enforcement register.
          </div>
        </div>

        <div>
          <div>
            Our archive has internal officer notes and enforcement records not published on the public portal. I need what's in OUR files for this address.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              4 planning records in your archive: 2008 outline approval for 12 dwellings (08/0341/OUT), 2011 reserved matters approval, 2016 S73 variation (approved), and a 2019 enforcement notice for unauthorised storage use (resolved 2020). <span>Sources: Planning Register, Enforcement Log 2019–2020</span>
            </div>

            <div>
              <div>PLANNING HISTORY TIMELINE</div>
            </div>
          </div>
        </div>
      </div>

      <div />

      <div>
        <div>
          <div>
            I'm reviewing a new application at grid ref TL456789. What planning constraints and environmental objection history do OUR records show within 500m?
          </div>
        </div>

        <div>
          <div>
            <img alt="ChatGPT" />

            <span>ChatGPT</span>
          </div>

          <div>
            To check planning constraints for a specific location, use your local planning authority's online mapping portal or Natural England's MAGIC map for environmental designations. Most local authorities also publish constraint layers as part of their Local Plan evidence base, which can be queried by coordinate.
          </div>
        </div>

        <div>
          <div>
            I need what's in OUR internal records — our constraint maps, determinations we've made, and any objections we've received or issued in this area. Not public portals.
          </div>
        </div>

        <div>
          <div>
            <div>N</div>
            <span>NIKA</span><span>Memory Core</span>
          </div>

          <div>
            <div>
              Within 500m of TL456789 your records flag: Grade II listed building (The Old Mill) 0.2km NW; TPO area on eastern boundary (TPO-2018-07) 0.1km E; Zone 2 flood risk along southern edge. Adjacent Zone 4B consultation also drew 3 statutory objections — SSSI risk, flood plain, and heritage assessment. <span>Sources: TPO-Register-2018, Conservation-Map-2019, Zone4B-Summary-2022</span>
            </div>

            <div>
              <div>CONSTRAINTS WITHIN 500m OF TL456789</div>

              <table>
                <thead>
                  <tr>
                    <th>Distance</th>
                    <th>Constraint</th>
                    <th>Type</th>
                    <th>Source</th>
                  </tr>
                </thead>

                <tbody>
                  <tr>
                    <td>0.1km E</td>
                    <td>TPO Area — TPO-2018-07</td>
                    <td><span>Tree Preservation</span></td>
                    <td>TPO-Register-2018</td>
                  </tr>

                  <tr>
                    <td>0.2km NW</td>
                    <td>Grade II Listed — The Old Mill</td>
                    <td><span>Heritage</span></td>
                    <td>Conservation-Map-2019</td>
                  </tr>

                  <tr>
                    <td>S boundary</td>
                    <td>Flood Zone 2 along southern edge</td>
                    <td><span>Flood Risk</span></td>
                    <td>FloodMap-2022</td>
                  </tr>

                  <tr>
                    <td>Adjacent</td>
                    <td>Zone 4B — 3 statutory objections on record</td>
                    <td><span>Prior Objections</span></td>
                    <td>Zone4B-Summary-2022</td>
                  </tr>
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## What It Solves

### Before NIKA Memory Core

* A junior ecologist needs to know if a site was previously surveyed — they email three colleagues and wait two days for an answer
* A project manager needs historical soil data for a planning application — they dig through a shared drive with 15 years of nested folders
* A field team arrives on site with no context on prior work — they spend the first day re-discovering what was already known
* When the most experienced team member is unavailable, critical project questions stall

### With NIKA Memory Core

* The junior ecologist asks *"Have we done any Phase 1 habitat surveys within 2km of this site?"* and gets a sourced answer in seconds
* The project manager asks *"What geotechnical reports do we have for developments along this river corridor?"* and gets a summary with document links
* The field team asks *"What species were recorded here in previous seasons?"* and gets species lists with survey dates and locations
* Every team member has access to the collective experience of the entire organization

<img alt="NIKA Memory Core" />

## Key Features

### Ingest Any Format

Drop in the documents your team already has. Memory Core processes PDFs, Word documents, spreadsheets, CSVs, GeoJSON, shapefiles, and more. No reformatting or manual tagging required — the AI extracts structure, entities, and spatial references automatically.

### Spatial Awareness

Knowledge isn't just text — it's tied to places. Memory Core understands that a bat survey report relates to a specific site boundary, that a soil analysis covers a particular set of boreholes, and that a flood risk assessment applies to a defined catchment area. When you ask a question, it knows which knowledge is geographically relevant.

### Source Traceability

Every answer includes citations to the original documents — page numbers, report titles, and dates. Your team can always verify the AI's response against primary sources. This is critical for regulatory submissions and audits where provenance matters.

### Team-Wide Access

Memory Core is shared across your team. Documents ingested by anyone are available to everyone with access. Field teams, desk-based analysts, and project managers all draw from the same knowledge base — eliminating information silos and duplicated effort.

### Continuous Learning

Memory Core grows with your organization. As new surveys are completed, new reports filed, and new datasets acquired, they are ingested automatically. Your knowledge base stays current without manual curation.

## See How Indexing Works

When Memory Core ingests your files, it places everything on a shared spatial index — an [H3](https://h3geo.org/) hex grid — and links related documents into a knowledge graph. This interactive demo runs that index over a real file set: switch between the **Map** and **Graph** views, and change the H3 resolution to watch files cluster at different scales.

<div>
  <iframe title="NIKA Memory Core — spatial file indexing demo" />
</div>

<p>
  <a href="/nika-desktop/memory-core-indexing-demo.html">Open the demo full screen →</a> — the standalone view has a **Back to docs** button to return here.
</p>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I set up NIKA Memory Core?">
    Setting up Memory Core takes just a few steps. From the Nika Desktop sidebar, open the Memory Core panel and click **New Memory Core**. Give it a name, then upload your documents — PDFs, shapefiles, spreadsheets, or any supported format. Memory Core processes and indexes your files automatically. Once ingestion is complete (usually within minutes for most document sets), you can start querying straight away. No configuration of models or infrastructure is required.

    <img alt="NIKA Memory Core" />
  </Accordion>

  <Accordion title="How do I update Memory Core with new documents?">
    Memory Core learns continuously as your team works. After each session, you'll see a prompt asking whether you'd like to add that session's queries and insights to your knowledge base — you stay in full control of what gets retained.

    You can also manage Memory Core manually at any time, where you can browse all indexed content, add new documents, remove outdated entries, and reorganise your knowledge base as your data evolves.
  </Accordion>

  <Accordion title="How can team members access Memory Core?">
    Memory Core is shared at the organisation level. Any team member with access to your Nika Desktop workspace can open and query the same knowledge base. Permissions are managed through your organisation's Nika account — administrators can control who can add or delete documents, while read access can be granted more broadly. There is no seat limit on access.
  </Accordion>

  <Accordion title="What formats of data does Memory Core support?">
    Memory Core accepts a wide range of geospatial and document formats, including:

    * **Documents:** PDF, DOCX, XLSX, CSV, TXT
    * **Geospatial vector data:** Shapefile (.shp), GeoJSON, KML, GeoPackage (.gpkg), DXF
    * **Raster data:** GeoTIFF, ECW, JPEG2000
    * **Tabular data with coordinates:** CSV or Excel files containing latitude/longitude or easting/northing columns

    If you have a format not listed here, contact us — we can often add support for bespoke data types.
  </Accordion>

  <Accordion title="How does the location-awareness work?">
    When you upload geospatial files or documents that contain spatial references (coordinates, place names, grid references, or embedded geometries), Memory Core extracts and indexes the location metadata. When you ask a spatial question — for example, *"show me all site investigations within 500 m of this point"* — it uses that location index to filter and rank results geographically. You can also draw an area of interest directly on the map and Memory Core will scope its answers to that extent.
  </Accordion>

  <Accordion title="Is data stored in Memory Core secure?">
    It depends on how you use it:

    * **Single user (local):** Your Memory Core is created and stored entirely on your local machine. No data leaves your desktop — there is no cloud upload, no external server, and no network dependency. Your documents stay where you put them.

    * **Team sharing (cloud):** When you share Memory Core with your team, the data is synced to the cloud. All documents are encrypted at rest using AES-256 and in transit using TLS 1.3. Each organisation's knowledge base is stored in isolated, organisation-scoped storage — your data is never shared across organisations or used to train any model. You retain full ownership and can delete individual documents or the entire knowledge base at any time, with permanent deletion confirmed within 24 hours.
  </Accordion>
</AccordionGroup>

## Try NIKA Memory Core With Your Data

We'll take a sample of your organization's existing documents and turn them into a live Memory Core — so you can see exactly what your team would be able to query before committing to anything.

<Card title="Book a NIKA Memory Core Demo" icon="calendar" href="https://cal.com/lawrence-nika/nika-expert">
  30 minutes — bring your own documents. We'll handle the rest.
</Card>


# Overview
Source: https://docs.nikaplanet.com/nika-desktop/overview

NIKA Desktop is an autonomous AI location analyst — it reads your files, runs the geospatial analysis, and hands back interactive maps, dashboards, and reports.

<img alt="NIKA Desktop Agent" />

## Your Autonomous Location Analyst

NIKA — **<u>N</u>exus <u>I</u>nteractive <u>K</u>artographic <u>A</u>gent** — is a desktop application that puts an autonomous AI data analyst at the centre of your geospatial work. Point it at your files and the data sources your industry already uses; it reads them, searches external and satellite data, runs the spatial analysis on its own, and hands back the report, dashboard, or interactive map. For decision-makers without a GIS background, it's the entry point to location analysis — and it all happens in a single, chat-driven conversation.

<Frame>
  <img alt="NIKA Desktop autonomous location analyst — chat-driven geospatial analysis rendering an interactive map" />
</Frame>

## What NIKA Does

<Columns>
  <Card title="Autonomous analysis" icon="wand-magic-sparkles" href="/nika-desktop/autonomous-analysis">
    Works in an agentic tool loop — reads your files, runs geospatial operations, inspects the results, and iterates until the task is done, streaming every tool call in real time so you can watch the analysis happen.
  </Card>

  <Card title="Connect files & data sources" icon="database" href="/nika-desktop/data-and-conversion">
    Bring your own reports, PDFs, drawings, field photos, and spreadsheets, pull in external and satellite data, and inspect or convert across 100+ geospatial formats.
  </Card>

  <Card title="Live maps, dashboards & reports" icon="chart-column" href="/nika-desktop/visualizations">
    Interactive maps, charts, dashboards, 3D viewers, and shareable reports — all generated directly in the conversation as the agent works.
  </Card>

  <Card title="NIKA Memory Core" icon="brain" href="/nika-desktop/memory-core">
    Your organization's enterprise brain: ingest your documents once, then anyone can query decades of institutional knowledge in plain language, grounded in your own data.
  </Card>
</Columns>

## Location-Aware by Design

NIKA is a superset of general chat agents like ChatGPT, Claude, and Gemini. It does everything they do with text — then goes further, understanding real coordinates and tying every result back to real-world assets, places, and geometries, not just words on a page. That is what lets a plain-language question return a sourced answer *and* a map of exactly where it applies.

## Your Organization's Knowledge, On Tap

Enterprises accumulate vast amounts of geospatial data over years — environmental reports, survey PDFs, regulatory filings, satellite imagery metadata, field notes, and engineering documents — scattered across drives, databases, and inboxes. The institutional knowledge locked inside these files often lives only in the heads of senior staff.

**NIKA Memory Core** changes that. Ingest your organization's documents and NIKA transforms them into a spatially-aware knowledge base that any team member can query through natural language. Questions that previously required decades of experience to answer — *"Have we surveyed for protected species near this river corridor before?"* or *"What soil conditions were reported across our northern sites?"* — are now accessible to everyone on the team, instantly.

<a href="/nika-desktop/memory-core">Learn more about NIKA Memory Core →</a>

## Extensibility

### Plugin System

Drop plugins into the plugins directory with a `plugin.json` manifest. Each plugin registers tools with input schemas that the AI agent can discover and call automatically.

### MCP Server Integration

Connect external tools via the **Model Context Protocol (MCP)**. Configure MCP servers and NIKA dynamically discovers their tools, making them available to the agent alongside built-in capabilities.

### Skill Templates

Save reusable prompt templates as skills. Skills provide domain-specific instructions that guide the agent's behavior for recurring workflows — from standard data processing pipelines to compliance report generation.

## AI Chat with Multi-Provider Support

NIKA's chat interface connects to multiple LLM providers, so you can choose the model that best fits your task and budget.

| Provider | Models |
| - | - |
| **Anthropic** | Claude Sonnet 4.5, Claude Opus 4, Claude Haiku 4 |
| **OpenAI** | GPT-4.1, GPT-4.1 Mini, o3, o4-mini |
| **Google Gemini** | Gemini 2.5 Pro, Gemini 2.5 Flash |
| **Ollama (Local)** | Llama 3.3, Mistral, Mixtral, CodeLlama, Qwen 2.5 |

Multiple chat sessions are persisted to disk, so you can pick up any prior conversation exactly where you left off.


# Visualizations & Artifacts
Source: https://docs.nikaplanet.com/nika-desktop/visualizations

The interactive maps, charts, dashboards, 3D viewers, surveys, and shareable reports NIKA generates live in the conversation.

## Answers You Can See and Share

NIKA doesn't just describe results — it builds them. As the agent works, it generates rich, interactive artifacts directly in the conversation, so the output of an analysis is something you can explore, present, and hand to a decision-maker, not a wall of text.

<Frame>
  <img alt="NIKA Desktop rendering an interactive map and dashboard artifact in the conversation" />
</Frame>

## What NIKA Can Generate

<Columns>
  <Card title="Interactive maps" icon="map">
    Maps with raster, vector, and GeoJSON layer management — pan, zoom, toggle layers, and inspect features right in the conversation.
  </Card>

  <Card title="Charts" icon="chart-line">
    The agent generates interactive chart specifications from your data, so trends and comparisons are visible at a glance.
  </Card>

  <Card title="Dashboards" icon="table-columns">
    Compose multiple charts and views into a drag-and-drop dashboard canvas for a single, scannable overview.
  </Card>

  <Card title="3D viewer" icon="cube">
    Visualize 3D scans, point clouds, and terrain models without exporting to a separate tool.
  </Card>

  <Card title="Surveys" icon="clipboard-list">
    Design and preview field survey forms directly in the agent, ready to push out to field teams.
  </Card>

  <Card title="Web apps" icon="window-maximize">
    Generate and preview self-contained web applications built around your data and analysis.
  </Card>

  <Card title="Diagrams" icon="diagram-project">
    Automatic diagram rendering for architecture, flowcharts, and workflows when you need to explain a process.
  </Card>

  <Card title="Reports" icon="file-lines">
    Package the analysis and its artifacts into a shareable report you can hand to stakeholders.
  </Card>
</Columns>

## From Analysis to Artifact

Every visualization is the end of an [autonomous analysis](/nika-desktop/autonomous-analysis): you ask in plain language, NIKA runs the work across your [connected data](/nika-desktop/data-and-conversion), and the result arrives as an artifact you can explore and share — no handoff to a separate GIS or BI tool required.


# Use with ArcGIS Pro
Source: https://docs.nikaplanet.com/nika-geoengine/arcgis

Integrate NikaGeoEngine and NikaPlanet services directly inside ArcGIS Pro

# ArcGIS Integration

Our ArcGIS integration focuses on bridging the power of scalable cloud compute and isolated environments directly into the familiar interface of ArcGIS Pro. We provide powerful integrations for both developers building custom geospatial tooling and non-technical stakeholders looking to consume cloud infrastructure smoothly.

## 1. NikaGeoEngine Plugin (For Analysts & Developers)

The **GeoEngine Plugin for ArcGIS Pro** removes all barriers to getting your custom Python and R scripts running securely inside ArcGIS. Using Docker-based isolation, your scripts execute in clean, scalable container environments directly inside your desktop toolboxes.

### How it Works

Traditional ArcGIS Python toolsets require complex parameter handling, custom wrapper coding, and constant dependency conflicts with ArcGIS's internal Python interpreter (e.g. `arcpy` version lock-ins).

With NikaGeoEngine, your script's environment lives entirely separate:

* **No Wrapper Code**: GeoEngine dynamically reads your `geoengine.yaml` worker declaration and translates it to ArcGIS Pro Toolbox interfaces on the fly. No proxy services required.
* **Isolated Execution**: Since the code runs via the GeoEngine CLI as a subprocess (inside a Docker container), it never conflicts with the host `arcpy` ecosystem. ArcGIS Pro stamps local worker runs with `--actor "ArcGIS Pro"`, so CLI run history shows where each execution came from. You can run deep learning workloads with different PyTorch builds effortlessly.
* **Version Control**: Access all historical, immutable versions of your algorithm directly from the toolbox dropdown in ArcGIS.
* **Logs & Output**: Background logs smoothly stream out of the container to the ArcGIS Progress windows.

## 2. NikaPlanet Plugin (For GIS Users)

While the GeoEngine Plugin helps developers create containerized algorithms smoothly, the **NikaPlanet Plugin** focuses on seamless execution and cloud-infrastructure management for analysts.

### Getting Started

Open the Nika panel inside ArcGIS Pro and sign in with your NikaPlanet account. The plugin shares credentials with the GeoEngine CLI — if you're already logged in via the CLI, you'll be signed in automatically.

<img alt="NikaPlanet Plugin login screen in ArcGIS Pro" />

### Browse the Worker Catalog

After signing in, the plugin loads all GeoEngine workers published to your team. Workers are grouped by name and expandable to show individual versions. Click any version to open its configuration window.

<img alt="Worker catalog showing grouped workers and versions" />

### Configure and Run a Job

Select your input files, set any required parameters, and choose a compute tier. Click **Run** to submit the job to Nika's cloud — no local Docker or CLI required.

<img alt="Job configuration window with input fields and compute tier selector" />

### Monitor Live Progress

Once submitted, the plugin switches to a live log view. Status updates stream in as the job moves through cold start, execution, and completion. You can cancel at any time.

<img alt="Live log view showing job status and streaming output" />

### Job History

The Sessions tab shows all past and active jobs. Filter by worker or date range to find a specific run and review its logs or download outputs.

<img alt="Job history tab with filter controls and past job cards" />

### Expanding Desktop Capabilities

* **Manage Resource Deployment**: Start, monitor, and deploy configured NikaGeoEngine Workers and algorithms seamlessly from the ArcGIS interface directly to Nika's cloud without managing CI/CD pipelines.
* **Execute Cloud Jobs**: Run heavy processing on deployed algorithms, letting NikaPlanet handle the compute provisioning and sending the outputs securely back to your ArcGIS session.
* **Shared Ecosystems**: Consume shared team assets, vector maps, and algorithms stored globally on NikaHub.


# Overview
Source: https://docs.nikaplanet.com/nika-geoengine/overview

A Docker-based isolated runtime manager with GPU acceleration, GIS integration, and agentic AI support.

## Overview

NikaGeoEngine is an advanced runtime manager tailored for isolated execution of Python and R geospatial workloads. By seamlessly encapsulating functions in Docker containers, GeoEngine handles local testing, environmental dependencies, and tool execution—giving you fully reproducible workloads that can interact automatically with desktop GIS software and AI Agents.

<img alt="NikaGeoEngine Architecture" />

## Key Features

### Declarative Worker Management

* **Single-Command Deploy**: Use `geoengine apply` to automatically generate Dockerfiles, build Docker images, save configurations, and register the function as an available worker in your environment.
* **Dependency Management via Pixi**: Define environments precisely in a Pixi manifest. All GDAL, PyTorch, Conda-forge, and PyPI dependencies are isolated directly inside the Docker container.
* **Version Snapshots**: Track script versions using Semantic Versioning. Each applied build is snapshotted, meaning you can jump back and run `"v1.0.0"` of an algorithm months later with absolute reproducibility.

### Environment & Compute Execution

* **Seamless Local & Docker Execution**: Input parameters like `input-file` automatically resolve path mounting seamlessly from host to container boundary behind the scenes.
* **GPU Acceleration**: NVIDIA GPU passthrough supports CUDA-accelerated workloads (plus Apple Metal backend support) out of the gate.
* **Structured JSON Interface**: Run tools purely via CLI outputting rich JSON arrays detailing file outputs, logs, and system statuses.

### Ecosystem Integration

* **GIS Desktop Integration**: Execute your standalone geospatial functions directly from ArcGIS Pro and QGIS. GeoEngine workers appear in native toolboxes—no proxy services, extensive GUI programming, or wrapper code required.
* **Agentic AI Enablement**: Built-in AI Agent skills structure (for Claude, Google, and OpenAI models) allow Large Language Models to automatically scaffold, write `geoengine.yaml`, manage arguments, and deploy GeoEngine workers on your behalf.
* **NikaPlanet Integration**: Deployed tools will integrate securely as managed resources across NikaPlanet workflows and cloud environments.


# Use with QGIS
Source: https://docs.nikaplanet.com/nika-geoengine/qgis

Integrate NikaGeoEngine and NikaPlanet cloud services natively into QGIS

# QGIS Integration

Nika provides robust integration with QGIS. By bringing the isolated compute power of Docker-based scripting and the seamless cloud orchestration of NikaPlanet directly into the QGIS Processing Toolbox, you receive the ultimate hybrid workflow.

## 1. NikaGeoEngine Plugin (For Analysts & Developers)

The **GeoEngine Plugin for QGIS** instantly translates any local containerized scripts into native QGIS Processing tools.

### Modernizing QGIS Script Execution

Historically, creating a QGIS Plugin or Processing tool from a python algorithm requires learning QGIS's specific PyQt APIs and processing frameworks. This typically leads to massive wrapper code overhead and a dependency nightmare across your team's different devices.

NikaGeoEngine bypasses this barrier:

* **CLI-Native Subprocessing**: QGIS plugins execute your workers as pure subprocesses via the GeoEngine CLI without any proxy service. QGIS stamps local worker runs with `--actor QGIS`, so CLI run history shows where each execution came from. You write plain Python/R, declare its dependencies gracefully across `pixi.toml` and Docker configurations, and GeoEngine handles mapping parameters transparently to the container.
* **Automatic Discoverability**: The plugin executes `geoengine workers` to index your available algorithms automatically. Your tool populates directly into the QGIS Processing Toolbox with zero GUI code required.
* **Live Streams**: QGIS natively parses Docker container outputs, mounting output paths correctly back to the map workspace and streaming stderr output to visualize job progress.
* **GDAL/Environment Independence**: The tool uses exactly the GDAL and library versions specified within its container, keeping the QGIS host environment perfectly clean.

## 2. NikaPlanet Plugin (For GIS Users)

The **NikaPlanet QGIS Plugin** aims to expose advanced Nika cloud platforms without needing to leave the desktop application workflow.

### Streamline Your Team Workflow

The plugin installs as a standalone extension with no external dependencies beyond QGIS 3.0+, and pairs a dockable NikaPlanet panel with native QGIS Processing Toolbox entries so cloud jobs behave like any other algorithm.

<img alt="QGIS Workers" />

* **Unified Sign-In**: Authenticate via a browser-based authentication flow. Logins are persisted by your OS and shared with the GeoEngine CLI — sign in on either side and the session carries over, with automatic refresh and session restore on QGIS start-up.
* **Cross-Tenant Worker Catalog**: Browse every worker you can access across your owned team and any teams you've been invited to, all in one searchable panel. Filter by name, version, or job ID and refresh on demand to pull the latest catalogue from NikaPlanet.
* **Processing Toolbox Integration**: Workers deployed by your teammates show up both in the plugin UI (preferred) and the processing toolbox, so cloud jobs integrate seamlessly into your workflows without needing you to leave the application.
  <img alt="QGIS Toolbox" />
* **Rich Job Configuration**: The worker run dialog builds inputs directly from the worker's schema — file pickers, QGIS layer dropdowns, and string fields — and lets you pick a machine type (CPU or GPU tier) per run to match compute to workload.
  <img alt="QGIS Submit" />
* **Live Job Tracking**: Track the progress of your submitted jobs via a streaming log viewer. A persistent Sessions tab retains the full history of submitted jobs with status, timestamps, and worker metadata, and filters to allow for finer searching.
  <img alt="QGIS Job History" />
* **Automatic Result Ingestion**: On success, outputs are listed in a browsable file tree. Toggle *Download outputs* and *Add outputs as layers* and the plugin pulls rasters (`.tif`, `.jp2`, `.grd`), vectors (`.shp`, `.geojson`, `.gpkg`, `.gml`, `.gpx`), and vector tiles (`.pmtiles`) straight into the map canvas with deduplicated layer names.
  <img alt="QGIS Results" />


# NIKA GeoEngine Releases
Source: https://docs.nikaplanet.com/nika-geoengine/releases

Release notes synced from GitHub

<Update label="April 17, 2026" description="v0.7.1">
  ## What's Changed

  ### Minor Patches

  * Added worker website as push completion message.
  * Fixed QGIS Windows path issue.
  * Refactored `readonly` boolean param to `output` boolean param.

  ### Deprecations

  * `readonly` input params are now refactored. Previously `readonly: false` params will now be `output: true` params.
  * `local_dir_mounts` are no longer supported. Directly include the data folders into the worker directory, and refer to them with a `/app` prefix. e.g. To refer to a data file `./data/data.geojson`, use `/app/data/data.geojson` in the worker script instead.

  <Warning>
    **Big worker changes needed**

    Run `geoengine apply --dev` on every worker to update them. If any of them fail, delete the workers and re-apply them.

    *Applies when upgrading to version 0.7.1.*
  </Warning>
</Update>

<Update label="April 15, 2026" description="v0.7.0">
  ## What's Changed

  ### Major Changes

  * Added ability to cloud push to a Nika account. Users can now push versioned workers to their team.

  ### Minor Patches

  * Improved ArcGIS Pro plugin with layer loading and input.
  * Removed invasive Windows CMD behaviour.
  * Refactored auth commands to `geoengine auth login|logout|status`.

  ### Deprecations

  * Referencing workers by name is no longer supported. Use `--uuid` flags to reference workers by their UUIDs instead.
</Update>

<Update label="April 15, 2026" description="v0.6.5">
  ## What's Changed

  ### Minor Patches

  * Added ArcGIS Pro plugin layer selection.
  * Re-wired auth flow.
  * Added better error logging to QGIS plugin.
  * Improved shapefile handling in AI skills.
  * Code refactoring.
</Update>


# Agent Chat
Source: https://docs.nikaplanet.com/nika-mobile/nika-mobile-chat

AI-powered agent chat connected to your NIKA Memory Core for field Q&A.

## Overview

NIKA Mobile's Agent Chat brings your team's NIKA Memory Core into the field. Ask questions in natural language and get AI-generated answers grounded in your project's documents, reports, and survey data — right from your phone.

## How It Works

Agent Chat connects to the same NIKA Memory Core that powers NIKA's desktop agent. When a field team member asks a question, the AI retrieves spatially-relevant knowledge from your team's ingested documents and synthesizes an answer with source citations.

### Example Queries

* *"What habitat types were recorded in the northern parcel last season?"*
* *"Are there any bat roost records within 500m of this site?"*
* *"What does our ESIA baseline say about the community livelihoods in this area?"*

## Key Features

### Spatial Context

Your GPS location is automatically included as context, so the AI prioritizes knowledge relevant to where you are standing. No need to specify coordinates or site names.

### Source Citations

Every answer references the original documents — PDFs, survey reports, or prior field data — so you can verify and trace back to primary sources.

### Team Knowledge

All team members share the same knowledge vault. Ingested documents, survey results, and reports contributed by any team member are available to everyone in the field.

### Offline Queued

When working in areas without connectivity, messages are queued locally and sent when you're back online. Previously cached responses remain accessible offline.


# Field Survey
Source: https://docs.nikaplanet.com/nika-mobile/nika-mobile-survey

Compliance survey engine with voice recording, AI auto-fill, and GPS tracking.

## Overview

NIKA Mobile's survey engine is purpose-built for environmental field data collection. It combines a standards-compatible form renderer with voice recording, on-device transcription, and AI-powered auto-fill — so surveyors spend less time typing and more time observing.

## Survey Hierarchy

Surveys are organized in a three-level hierarchy designed for complex ecological assessments:

1. **Survey** — the top-level project (e.g., "BNG Habitat Assessment — Site A")
2. **Plan** — a spatial unit within the survey (a habitat parcel, transect route, carbon plot, or point location)
3. **Session** — a single data collection visit to a plan, capturing form responses, GPS tracks, photos, and audio

This structure supports repeat visits, seasonal monitoring, and multi-surveyor coordination across large sites.

## Form Engine

### Rich Field Types

The form renderer supports the full range of field types needed for compliance surveys:

* **Text & numeric** — free text, integer, decimal inputs
* **Selection** — single-select (radio) and multi-select (checkbox) with choice lists
* **Spatial** — geopoint, geotrace (line), and geoshape (polygon) capture via interactive map picker
* **Media** — photo capture and audio recording
* **Temporal** — date, time, and datetime pickers
* **Logic** — skip logic (relevant expressions) and constraint validation

### Compliance Schemas

Pre-built form schemas for industry-standard environmental methodologies:

| Schema | Standard |
| - | - |
| BNG Habitat Condition | DEFRA Biodiversity Metric 4.0 |
| Bat Emergence Survey | BCT 4th Edition |
| Tidal Wetland Carbon | Verra VM0033 |
| REDD+ Forest Carbon | Verra VM0007 |
| Social Baseline | IFC Performance Standards (ESIA) |
| Screening Assessment | EIA Screening |

### LLM Form Generation

Describe the survey you need in plain language and the AI generates a form schema for you — no spreadsheet editing required.

## Voice-to-Form AI

The standout feature for field productivity:

1. **Record** — tap the floating microphone button to start recording while you observe and narrate
2. **Transcribe** — on-device AI model converts speech to text in real time, entirely offline
3. **Auto-fill** — Claude analyzes the transcript against your form schema and extracts structured values into the correct fields
4. **Review** — auto-filled values are highlighted for quick review and manual adjustment before saving

The AI handles type coercion (matching spoken choices to select lists, parsing numbers, validating dates) so the extracted data is immediately usable.

## GPS Integration

### Position Capture

* Survey-grade position averaging from multiple GPS samples
* Accuracy-aware indicators (green/yellow/red) so you know when readings are reliable
* Multiple coordinate formats (DD, DMS, DDM, UTM)

### Trail Recording

Record a GPS breadcrumb trail for every survey session. Trails are stored as GeoJSON LineStrings with distance, duration, and sample count statistics — useful for verifying site coverage and documenting transect paths.

### Spatial Data Types

* **Geopoint** — single tap on map to capture a coordinate
* **Geotrace** — walk a route to capture a line geometry
* **Geoshape** — walk a boundary to capture a polygon geometry


# Team Maps
Source: https://docs.nikaplanet.com/nika-mobile/nika-mobile-team-maps

View and navigate shared project maps from NikaPlanet on your mobile device.

## Overview

Access your team's NikaPlanet project maps directly on your mobile device. NIKA Mobile syncs map layers, styles, and view states from the cloud so field teams always have the latest spatial context when heading to a site.

## Key Features

### Live Map Sync

Maps are synced from NikaPlanet with collaborative state management. Layers added or styled by your team on the desktop appear automatically on mobile. When connectivity is available, map changes propagate in real time.

### Layer Management

Toggle individual layers on and off to focus on the data that matters for your current task. Switch between multiple basemaps — street, satellite, topographic — depending on field conditions.

### GPS Navigation

Your live GPS position is overlaid on the map with accuracy indicators. Navigate to survey sites, plot stakes, and transect start points using the integrated location display with coordinate format options (DD, DMS, DDM, UTM).

### Offline Map Caching

Maps are cached to local storage for use in remote areas without connectivity. The app loads cached map snapshots instantly on startup and refreshes from the server when back online.

### Multi-Format Data

View vector polygons, raster imagery, and GeoJSON overlays. The same data your team visualizes in NikaPlanet is available at your fingertips in the field.


# Overview
Source: https://docs.nikaplanet.com/nika-mobile/overview

AI-first mobile app for environmental field surveys with voice-to-form automation, offline mapping, and team collaboration.

## Overview

NIKA Mobile is an AI-first field survey application built for environmental compliance teams. It combines on-device speech-to-text, LLM-powered form auto-fill, GPS tracking, and offline-first architecture into a single mobile app — so field teams can collect high-quality structured data without reliable connectivity.

Available on iOS and Android.

<img alt="NikaMobile Workflow" />

## Key Capabilities

### Voice-to-Form AI Auto-Fill

Stop typing in the field. Speak naturally about what you observe, and NIKA Mobile's AI automatically extracts structured values into 15+ form fields.

1. **Record** — tap the microphone to narrate your observations hands-free
2. **Transcribe** — on-device AI model converts speech to text in real time, with zero connectivity required
3. **Auto-fill** — Claude analyzes the transcript against your form schema and fills in the correct fields with validated values
4. **Review** — highlighted auto-filled values are ready for quick review before saving

<img alt="AI Auto-Fill" />

### Compliance-Ready Survey Schemas

Pre-built form templates for demanding environmental methodologies:

* **BNG Habitat Condition** — DEFRA Biodiversity Metric 4.0
* **Bat Emergence Survey** — BCT 4th Edition
* **Tidal Wetland Carbon** — Verra VM0033
* **REDD+ Forest Carbon** — Verra VM0007
* **ESIA Social Baseline** — IFC Performance Standards
* **EIA Screening Assessment** — generic environmental impact

Surveys support rich hierarchies — parent-child relationships, repeat groups, and nested plot structures needed for comprehensive ecological audits.

<img alt="Survey Session" />

### GPS & Field Mapping

* **Survey-grade positioning** with multi-sample averaging and accuracy indicators
* **GPS breadcrumb trails** recorded as GeoJSON for coverage verification
* **Spatial data capture** — geopoint, geotrace (line), and geoshape (polygon) via interactive map picker
* **Coordinate formats** — DD, DMS, DDM, UTM

<img alt="GPS Trail" />

### Team Maps

View your team's NikaPlanet project maps on mobile with live layer sync, multiple basemaps, and offline caching. Navigate to survey sites with your GPS position overlaid on the latest project data.

### Agent Chat with NIKA Memory Core

Ask questions in natural language and get AI answers grounded in your team's ingested documents, reports, and prior survey data. Your GPS location provides spatial context automatically — the AI prioritizes knowledge relevant to where you are.

### Offline-First Architecture

Every feature is designed for remote fieldwork:

* **Local database** stores all survey data on-device
* **Map caching** loads cached snapshots instantly, refreshes when online
* **Background sync** uploads completed sessions when connectivity returns
* **On-device transcription** works entirely without internet


# Changelog
Source: https://docs.nikaplanet.com/nika-planet/changelog

Product updates and announcements for NikaPlanet products

<Update label="September 23, 2026" description="v0.5.39">
  ## Nika Planet Downloader for Large Folder Exports

  ### New Features

  * **Download large folders from your terminal**: When a selected folder exceeds 2 GiB or 2,000 files, Nika Planet offers a command for the Nika Planet Downloader instead of trying to build the full ZIP in your browser. Install the tool on macOS, Linux, or Windows, then run the command from Active Operations. You can also pass `nikafs://` folder paths directly to download one or more folders.
  * **Resume and verify transfers**: The downloader transfers folder contents in parallel, writes directly to your chosen drive, verifies files against storage checksums, and resumes unfinished downloads when you rerun the same command.
  * **Keep workspace access controls**: Sign in with your Nika Planet account. The downloader checks your current workspace access when it requests files, and access can be revoked.
  * **Step-by-step setup guide**: See the [large folder download guide](/guides/manage-file-lake-per-workspace/large-folder-downloads) for installation, copying folder paths, choosing an output directory, and troubleshooting.

    <img alt="Nika Planet Downloader dialog for exporting a large folder" />

  Individual file selections continue to use the regular browser download.
</Update>

<Update label="August 14, 2026" description="v0.5.38">
  ## Queuing Feature for Remote Runs

  ### New Features

  * **Queuing runs that are waiting on compute**: When dedicated compute for a run submitted from [NikaNotebook](/nika-planet/nika-notebook) is not available within 5 minutes, the run will be queued and be shown as **Queuing** in the All Runs and Run Detail panels, alongside the time left before its queue timeout.
  * **Configurable queue timeout**: The [NIKA Python SDK](/guides/code-cloud-delegation/python-sdk) `@run` decorator accepts a new `queue_timeout_hours` option — the maximum time a run may wait for compute before it is failed. Left unset, a default of 24h will apply. A run that cannot be scheduled in time now either queues or fails with an explicit reason instead of waiting indefinitely. Pair this with the machine availability indicator and accurately estimate the maximum queue time to set for your runs.

  ### Breaking Changes

  * The `@run` decorator's `timeout` option is now `run_timeout_hours`, aligning with the new `queue_timeout_hours`. Rename it in existing scripts before running them.
</Update>

<Update label="August 13, 2026" description="v0.5.37">
  ## Machine Resource Availability

  ### New Features

  * **Machine Availability** indicator: Check the current availability of your preferred machines, especially for large runs on premium GPU machines.
</Update>

<Update label="July 10, 2026" description="v0.5.36">
  ## Batch Cancellation for Runs

  ### New Features

  * **Cancel runs in bulk**: In the [NikaNotebook](/nika-planet/nika-notebook) **All Runs** panel, select any active runs with the row checkboxes and cancel them together from the floating action bar. A type-to-confirm dialog guards against accidental cancellation — cancellation is requested for each selected run and can't be undone, and child runs that have already started are left untouched.

    <img alt="Batch cancellation confirmation dialog" />
</Update>

<Update label="July 2, 2026" description="v0.5.35">
  ## Run Metrics — Sized-for-Workload Insights

  ### New Features

  * **Metrics tab on Run Detail**: For every completed run submitted from [NikaNotebook](/nika-planet/nika-notebook), a new **Metrics** tab visualises CPU, memory, GPU utilisation, VRAM, and power draw over the run's lifetime, with peak headline cards and per-chart fit verdicts (*Well-utilised*, *Right-sized*, *Over-provisioned*, *Near limit*, *OOM risk*) that make it clear whether the machine matched the workload.
  * **Time-window focus**: drag on any chart to select a range — averages, peaks, and verdicts recompute for just that window so warm-up phases or transient spikes don't bias the picture.

    <img alt="Run Metrics tab" />
</Update>

<Update label="June 15, 2026" description="v0.5.34.1">
  ## Monitor Runs in the Workspace

  ### New Features

  * **Monitor Runs in the Workspace**: An **Active Runs** section on the Virtual Machine side panel, a searchable and status-filterable **All Runs** list, and a **Run Detail** panel with a fan-out run graph and Overview / Children / Logs tabs — so every submitted run is trackable from where you launched it.

    <img alt="Run Detail panel" />
</Update>

<Update label="May 25, 2026" description="v0.5.34">
  ## Remote Run Execution from NikaNotebook

  ### New Features

  * **Submit Runs with Dedicated Compute**: Delegate any Python function on a separate GPU or CPU machine directly from [NikaNotebook](/nika-planet/nika-notebook) using the [NIKA Python SDK](/guides/code-cloud-delegation/python-sdk). The notebook stays live while jobs execute in the background — no blocking, no waiting. Perfect for distributed ML or ETL runs.
</Update>

<Update label="May 12, 2026" description="v0.5.33">
  ## NikaWorkers — Run Geoprocessing Scripts in the Cloud

  ### New Features

  * **[NikaWorkers](/nika-planet/nika-workers)**: Run packaged geoprocessing workers directly from NikaPlanet — set and upload the inputs, and just submit, no extra setup needed. Choose a more powerful machine for compute-heavy geoprocessing worker.
  * **Community NikaWorkers**: Discover and run public workers published by other NIKA users from Nika Hub.
  * **Publish new Nikaworker**: Create and publish your own NikaWorker with [NikaGeoEngine](/nika-geoengine/overview) for team members to use on NikaPlanet without extra setup.
</Update>

<Update label="April 19, 2026" description="v0.5.32">
  ## In-App Documentation Links & Workspace Separation

  ### New Features

  * **Inline Documentation Links**: Every feature in NikaPlanet (files, maps, notebooks, workflows, databases, labeler, workspaces) now has an open-book icon that links directly to the relevant tutorial in the docs, so help is one click away from where you're working
  * **File Management Tutorial Series**: Added a new tutorial series covering file upload, download, and organization workflows for NikaPlanet
  * **Personal vs Team Workspace Separation**: Personal workspaces and workers are now clearly separated from team workspaces in the UI, with "Personal Account" labeling and member-invitation upsell prompts on personal tiers

  ### Feature Improvements

  * **Unified Plan Resolution**: Consolidated plan-based feature checks into a single effective-plan lookup so team members consistently inherit the workspace's plan capabilities (including LLM chat access) regardless of their personal plan
  * **Internationalized Guide Tooltip**: The bar header guide tooltip and button label are now translated across all supported languages
</Update>

<Update label="April 14, 2026" description="v0.5.31.1">
  ## Machine Resource Availability Handling

  ### New Features

  * **Resources Unavailable Status**: Machines now surface a dedicated "Resources Unavailable" state in the UI when the underlying cloud zone cannot fulfil the requested VM options, so users immediately understand why a machine won't start instead of seeing a generic spinning state
  * **Machine Status Reference Page**: Added a new documentation page explaining every possible machine status and what to do when a machine enters each state, making it easier to self-diagnose startup issues

  ### Bug Fixes

  * **Reliable VM Option Fallback**: Reworked the machine provisioning fallback so NikaKernel VMs reliably retry with an available machine type when the preferred configuration is unavailable in the target zone
</Update>

<Update label="April 13, 2026" description="v0.5.31">
  ## Newsletter & What's New

  ### New Features

  * **Newsletter Subscription**: Subscribe to the Nika newsletter directly from your account settings to receive product updates, tips, and news
  * **What's New Feed**: A new "What's New" dropdown in the sidebar lets you browse past product newsletters without leaving the app

  ### Feature Improvements

  * **Newsletter Opt-In on Sign Up**: New users can opt into the newsletter during onboarding
  * **Workspace Context in Top Bar**: The current workspace tenant name is now displayed in the top bar for better orientation

  ### Bug Fixes

  * Fixed empty legend appearing in publish dialog when no layers are present on the map

  <img alt="Newsletter Subscription" />

  <img alt="What's New Feed" />
</Update>

<Update label="April 11, 2026" description="v0.5.30.1">
  ## Favorite Workspaces & Platform Improvements

  ### New Features

  * **Favorite Workspaces**: Star your most-used workspaces to pin them at the top of your workspace list for quick access

  ### Feature Improvements

  * **Searchable Country Select**: The country selector in onboarding is now a searchable combobox for faster selection
  * **Content Moderation**: Published map thumbnails are now checked for inappropriate content before being shared
  * **Internationalization**: Standardized and completed translations across all 21 supported languages

    <img alt="Favorite Workspaces" />
</Update>

<Update label="March 24, 2026" description="v0.5.30">
  ## Persistent Draft Maps

  ### New Features

  * **Save Draft Maps**: Draft maps can now be saved as permanent shared maps directly from the map editor, so temporary map work is no longer lost when leaving the page

  ### Bug Fixes

  * Fixed map card height rendering in NikaHub
  * Fixed layer group buttons not updating properly when new children are added

  <img alt="Save Draft Map" />

  <img alt="Save Draft Map Dialog" />
</Update>

<Update label="March 20, 2026" description="v0.5.29">
  ## Free Plan Launch & Map Legends

  ### New Features

  * **NikaPlanet Free Plan**: NikaPlanet is now accessible to everyone under a free tier with storage tracking, seat management, and usage limits per product
  * **Map Legends**: Layer lists now display legends for both vector and raster symbology with collapsible layout per layer, including support for solid, gradient, and unique value colour modes

  ### Feature Improvements

  * **Plan Management**: Added plan deletion with confirmation dialog, no-expiry subscription option, and visual quota indicators for storage and seats
  * **Owner Column**: Added owner name to tenant and plan list views for better resource attribution
  * **Celebration Animation**: Added a celebratory animation when users complete the onboarding flow

    <img alt="Map Legends" />
</Update>

<Update label="March 13, 2026" description="v0.5.28">
  ## Vector Tile Rendering for Large Datasets

  ### New Features

  * **Automatic Vector Tile Optimization**: Large vector datasets are now automatically converted into vector tiles for fast, scalable map rendering — no manual processing required

  ### Feature Improvements

  * **Improved Email Delivery**: Migrated invitation emails to a more reliable provider for better deliverability
  * **Faster Load Times**: Updated the map rendering engine and removed unused components for improved application performance

    <img alt="Vector Tile Rendering" />
</Update>

<Update label="March 5, 2026" description="v0.5.27">
  ## Revamped Map Layer List

  ### New Features

  * **Layer Drag & Reorder**: Layers in NikaMap can now be reordered by dragging, giving users full control over draw order
  * **Selected Features Row**: Selected features now display alongside each layer with a feature count and quick actions to open the attribute table, clear selection, or export
  * **Collapsible Layer Groups**: Revamped the layer list UI with expand/collapse functionality and a zoom-to-layer action for faster navigation
</Update>

<Update label="February 28, 2026" description="v0.5.26">
  ## Notebook Import & Batch Segmentation

  ### New Features

  * **Jupyter Notebook Import**: Import existing .ipynb notebook files directly into NikaNotebook to continue working on your analysis seamlessly
  * **Batch Segmentation with "Find All"**: Introduced "Find All" in NikaLabeler to automatically detect and annotate similar objects across an image using AI-powered similarity search, with progress tracking and "Accept All" for rapid annotation

  ### Feature Improvements

  * **Labeler Performance**: Improved real-time collaboration performance in NikaLabeler for smoother annotation in larger sessions

  <img alt="Import IPYNB" />

  <img alt="Find All Segmentation" />
</Update>

<Update label="February 16, 2026" description="v0.5.25">
  ## Workflow Enhancements & Collaboration Fixes

  ### New Features

  * **Vector Tile Output in NikaFlow**: Added Vector Tile as a supported output format in the workflow editor
  * **Machine Type Selection**: Users can now choose specific machine types when configuring workflows in NikaFlow for optimized resource allocation
  * **DJI Zenmuse P1 Support**: Added sensor metadata support for DJI Zenmuse P1 camera data

  ### Bug Fixes

  * Fixed collaborator cursors remaining visible on the map after users left a session
  * Fixed custom icon naming conflicts that caused desynchronization between collaborators
  * Fixed a crash when loading layers with missing geometry data
</Update>

<Update label="February 5, 2026" description="v0.5.24">
  ## NikaLabeler Upload & Viewer Fixes

  ### Feature Improvements

  * **Improved Image Uploads**: Enhanced upload experience in NikaLabeler with desktop image upload support and upload timeout warnings
  * **Right-Click Drag Panning**: Right-click and drag to pan the canvas in NikaLabeler with a snap cursor for smoother navigation

  ### Bug Fixes

  * Fixed an issue where invited map viewers could not load maps when custom icons were unavailable, which was blocking the entire map from rendering
</Update>

<Update label="January 30, 2026" description="v0.5.23">
  ## COCO Export & Table Fixes

  ### New Features

  * **COCO Export Destination**: Export annotations in COCO format from labeling jobs with a file dialog to choose the export destination folder

  ### Bug Fixes

  * Fixed table rendering issues across the application
</Update>

<Update label="January 29, 2026" description="v0.5.22">
  ## Professional Vector Symbology & Custom Icons

  ### New Features

  * **Enhanced Vector Symbology**: Vector styling is now on par with ArcGIS Pro, supporting multiple modes—solid, gradient, and unique values—across all points, lines, and polygons.
  * **Advanced Styling Options**: Added support for dashed lines for linear features.
  * **Flexible Point Symbols**: Introduced preset icons and custom SVG upload options for points, giving users full control over spatial representation.

    <img alt="Vector Symbology" />

    <img alt="Custom Point Icons" />
</Update>

<Update label="January 28, 2026" description="v0.5.21">
  ## Workspace Role Refinement

  ### Feature Improvements

  * **Contributor Role**: Added the "Contributor" role to workspace permissions that can create/update but cant delete.
  * **Manager Role**: Renamed the "Editor" role to "Manager" while maintaining its delete permission.

    <img alt="Workspace Roles" />
</Update>

<Update label="January 19, 2026" description="v0.5.20">
  ## NikaLabeler Advanced Workflow & Performance Tracking

  ### New Features

  * **Launching NikaMap(Draft)**: Think of it like a temporary map in QGIS that is created but not saved at all until user chooses to make it a permenant one. It can be used for quick visualization of data on map for QA/QC.
  * **Geo-Referenced Image Loading**: Load current image from NikaLabeler with geo-references in NikaMap with satellite basemap for spatial context awareness to guide annotation precision
  * **Job Status Management**: Comprehensive job status tracking (Unassigned, In-Progress, Submitted, Rejected, Approved) for better workflow management
  * **Labeler Performance Dashboard**: New overview page showing individual labeler performance metrics including rejection rate and completion statistics
  * **Per-Image Instructions**: Added ability to attach instruction messages and caveats to specific images within jobs

  ### Feature Improvements

  * **Keyboard Shortcuts**: Introduced keyboard shortcuts for faster annotation workflow
  * **Real-Time Review Sync**: Approve/reject states and comments now sync in real-time across all collaborators
  * **Folder Upload**: Added support for image upload by folder directly from the desktop
  * **Batch Upload Fix**: Fixed the limit of 5 images per upload to the image labeler to allow for larger batch processing

    <img alt="NikaLabeler Workflow" />
</Update>

<Update label="January 13, 2026" description="v0.5.19">
  ## Real-Time Usage Dashboard & Advanced Analytics

  ### New Features

  * **Real-Time Usage Tracking**: The usage dashboard is now updated to be more accurate with real-time queries against compute and storage usage, as compared to the previous 24-hour log aggregation method.
  * **Extended Query Ranges**: Added support for various query ranges including last 1 week, last 1 month, last 3 months, last 1 year, and a custom date range selector.
  * **Interactive Data Filtering**: Ability to filter the usage table by column, with the chart dynamically updating to show the filtered results.
  * **Flexible Usage Aggregation**: Aggregate usage data in charts by month or by all resource types for granular analysis.
  * **Data Export Options**: Download the usage table in CSV or JSON formats for external use.

    <img alt="Real-Time Usage Dashboard" />
</Update>

<Update label="January 2, 2026" description="v0.5.18">
  ## NikaLabeler Collaboration & AI-Assisted Annotation

  ### New Features

  * **SAM 2.0 Interactor Tool**: Integrated AI-powered annotation tool with point prompts (left-click for positive, right-click for negative) for faster polygon creation
  * **Role-Based Assignment**: Assign and re-assign annotation tasks to specific Labeller roles for better task management
  * **Reviewer/Labeller Roles**: Introduced new role system with dedicated Reviewer and Labeller permissions for labeling jobs
  * **COCO 1.0 Export**: Export annotations in COCO 1.0 format for seamless integration with ML pipelines
  * **Real-Time Collaboration**: Synchronize annotations and cursor positions between users in real-time

  ### Feature Improvements

  * **Auto GeoTIFF Conversion**: Automatically batch convert GeoTIFF files (RGB channels) to JPEG for faster loading in annotation UI

    <img alt="NikaLabeler AI Tools" />
</Update>

<Update label="December 30, 2025" description="v0.5.17">
  ## Workspace Enhancements & Stability Upgrades

  ### New Features

  * **Resumable Uploads**: Enabled resumable and parallel file uploads to boost stability and throughput
  * **Advanced VM Options**: Added H100 machine type for VM (available for subscribed customers)
  * **Workspace Search**: Introduced name search functionality and improved layout margins in workspace list

  ### Feature Improvements

  * **Hub Navigation**: Added redirect from Nika Hub's app pages to studio.nika.eco
  * **VM Stability**: Improved Nika VM availability
  * **Security**: Applied CVE patches for enhanced security

  ### Bug Fixes

  * Fixed an error occurring when clicking the list of workspaces in workspace page

    <img alt="Workspace Search" />

    <img alt="Resumable Uploads" />
</Update>

<Update label="December 17, 2025" description="v0.5.16">
  ## Launching Nika Studio - AI Map Dashboard Builder

  ### New Features in ([Nika Studio](/nika-planet/nika-studio))

  * **Follows the "Lovable for Maps" philosophy** - it is designed solely for generating interactive map dashboards from natural language prompt
  * **Image Support** - It can read images from screenshot to build the same map interface from other applications easily
  * **Layer URL Support** - It can take in layer URLs such as XYZ tile url from existing server to use in the application directly
  * **Version Switching** - It can switch between different versions of the same map interface upon prompted edits so that user can switch between Ai edited versions to regain control

  <img alt="NikaStudio Interface" />

  <img alt="NikaStudio Chat" />
</Update>

<Update label="December 5, 2025" description="v0.5.15">
  ## Launching NikaLabeler

  * Geospatial Image Annotation Platform

  ### New Features

  in [NikaLabeler](/nika-planet/nika-labeler)

  * **Annotation Job Creation**: Create annotation tasks directly from folders in Nika Files for streamlined workflow setup
  * **Polygon Drawing & Editing**: Draw and edit polygon annotations with intuitive tools
  * **COCO 1.0 Import**: Load existing annotations in COCO 1.0 format as input for continued work
  * **Multi-Format Image Support**: Direct support for JPEG and PNG images from Nika Files
  * **Interactive Annotation UI**: Full-featured annotation interface with pan and zoom navigation controls

    <img alt="NikaLabeler Interface" />
</Update>

<Update label="November 12, 2025" description="v0.5.14">
  ## Real-Time Map Collaboration with NikaMap Sync

  ### New Features

  * **NikaMap Sync**: Introduced real-time map collaboration feature that allows multiple users to work on the same map simultaneously with instant synchronization of changes

    <img alt="NikaMap Sync" />

  ### Feature Improvements

  * **Left-Hand Keyboard Shortcuts**: Redesigned keyboard shortcuts to be easily reachable by the left hand for improved workflow efficiency
  * **Zoom Scale UI**: Added a new bottom bar in the map panel featuring intuitive zoom scale controls for better map navigation

    <img alt="Zoom Scale UI" />
</Update>

<Update label="October 14, 2025" description="v0.5.13">
  ## Enhanced ETL Conversion Formats Support in NikaFlow

  ### New Features

  * **Expanded Vector Format Support**: Added support for additional vector formats including FlatGeobuf, GeoParquet, and enhanced KML/KMZ handling
  * **Advanced Raster Format Support**: Extended raster format support to include HFA, JPEG2000, and CADRG formats
  * **3D Point Cloud Processing**: Added comprehensive support for LAS, LAZ, XYZ, PLY, and PNTS point cloud formats
  * **3D Tiled Data Support**: Added support for 3D Tiles and I3S formats for advanced 3D visualization workflows
  * **Style Format Integration**: Added support for LYRX, SLD, and QML style formats for enhanced cartographic workflows

  ### Feature Improvements

  * **Enhanced Coordinate System Conversion**: Improved CRS detection and transformation capabilities with more projection systems supported
  * **Better Data Validation**: Enhanced data validation tools with direct visualization in Nika Web UI
  * **Improved Format Detection**: More accurate automatic format detection and conversion path optimization

    <img alt="Enhanced ETL Flow" />
</Update>

<Update label="September 22, 2025" description="v0.5.12">
  ## Nika App Hub & Enhanced User Experiences

  ### New Features

  * **Nika App Hub**: Added demo apps in Nika App Hub for user exploration at [https://planet.nika.eco/en/hub/apps](https://planet.nika.eco/en/hub/apps)
  * **Download Form Integration**: Implemented download forms for Nika Hub's Solution page and Notebook page (Map page upcoming) so that visitor can fill in the form to download the content there
  * **Notebook Export**: Added export functionality for each notebook
  * **300GB RAM Compute Option**: Introduced high-memory compute option for large-scale data processing for some enterprise users

  ### Feature Improvements

  * **Enhanced File Management**: Added item count display in left panel lists for better navigation
  * **Improved File Upload**: Fixed upload limitations to handle >100 files in folders properly
  * **Better File Handling**: Enhanced raster file support during drag-and-drop operations

  ### Bug Fixes

  * Fixed layer name display issue when names are too long (now shows proper titles)
  * Resolved JPEG missing data layer issue that was causing application crashes
  * Fixed rename folder bug that was creating unwanted subfolders
  * Resolved machine stop status update issue that showed incorrect running status
  * Improved file upload reliability for large folder operations

  <img alt="Nika App Hub" />

  <img alt="300GB RAM Compute Option" />

  <img alt="Notebook Export" />
</Update>

<Update label="September 17, 2025" description="v0.5.11">
  ## Realtime File System Sync

  ### New Features

  * **Realtime File System Sync**: Introduced real-time file system synchronization that auto refreshes your files quickly when upstream changes

  ### Feature Improvements

  * **Enhanced File Operations**: All file operations (create, delete, rename, duplicate, move) now provide instant feedback
  * **Improved Folder Management**: Faster folder deletion and better handling of folder creation dialogs
  * **Better User Experience**: Create folder dialog now auto-focuses on open and no longer freezes the UI after closure

  ### Bug Fixes

  * Fixed bug where create folder dialog would freeze the UI after closure
  * Replace the "Open file" option from folder context menus with "Open folder" option
  * Fixed bug where uploading folders would land in the wrong directory if user navigated to other folders
  * Resolved issue with file operations not reflecting immediately in the UI

    <img alt="Realtime File System Sync" />
</Update>

<Update label="September 10, 2025" description="v0.5.10">
  ## Enterprise-Level GIS Processing Tools

  ### New Features

  * **Acolite for Jilin Satellite Images**: Extended water turbidity modeling capabilities to Jilin satellite images (previously available only for Sentinel-2)
  * **6S Atmospheric Correction**: Added 6S atmospheric correction tool for both Sentinel-2 and Jilin satellite images
  * **Pansharpening Tool**: Introduced pansharpening functionality for any GeoTIFF images using the Graeme Schmidt algorithm

    <img alt="Enterprise GIS Processing Tools" />
</Update>

<Update label="September 6, 2025" description="v0.5.9">
  ## Nika DBMS (Public Beta)

  ### New Features

  * Support external PostgreSQL and MotherDuck connections
  * Support creation and query on DuckDB instances managed by Nika
  * Support direct query from the managed DuckDB on all files in the same workspace
  * Added SQL generator with LLM capability
  * Added direct schema and preview on databases in the list

    <img alt="Nika DBMS Public Beta" />
</Update>

<Update label="August 31, 2025" description="v0.5.8">
  ## Nika Map Server Performance Improvements

  ### Bug Fixes

  * Resolved the JPEG in NikaMap that has missing gimbal yaw or pitch error

  ### Feature Improvements

  * Increased speed and load for Nika Map server handling larger files and concurrent requests
</Update>

<Update label="August 25, 2025" description="v0.5.7">
  ## Password Protected Publish and Social Sharing

  ### Feature Improvements

  * Added password-protected access for published Solutions, Notebooks, and Maps
  * Social share uses a new default thumbnail for preview in social media platforms

  ### Bug Fixes

  * Published solution has unnecessary text truncation resolved
  * Fixed GAIA edit notebook id error
  * Fixed Nika Hub content page opening with sub header hidden under main header
  * Fixed thumbnail update bug for publish dialog

    <img alt="Password Protected Publish" />
</Update>

<Update label="August 21, 2025" description="v0.5.6">
  ## Enhanced Nika Hub and Mobile Experience

  ### Feature Improvements

  * Nika Hub now shows description and thumbnail for better content discovery
  * Added direct share on social media button for easy content sharing
  * Nika Hub is now properly optimized for mobile phone browser viewing
  * Nika Hub for maps now supports basemap switching functionality

  ### Bug Fixes

  * Fixed JPEG image orientation issue when added to map with roll close to 180 degrees - now correctly displays orientation on map

  <img alt="Nika Hub on mobile" />

  <img alt="Nika Hub on mobile 2" />

  <img alt="Nika Hub social media share" />
</Update>

<Update label="August 12, 2025" description="v0.5.5">
  ## Drone Image Support

  ### New Features

  * Added support for drone JPEG images in Nika Map, specifically designed for images taken in shooting down angle

    <img alt="Nika Map JPEG" />
</Update>

<Update label="August 3, 2025" description="v0.5.4">
  ## Enhanced Raster Layer Controls

  ### New Features

  * Raster layer now supports adaptive min/max to window view across all bands for highlighting features
  * Uses one button instead of many steps required in QGIS for the same functionality

  ### Feature Improvements

  * Nika Map now shows invalid layers as greyed out (e.g., due to invalid source) for better user experience

    <img alt="Nika Map Raster Window Min/Max" />
</Update>

<Update label="July 31, 2025" description="v0.5.3">
  ## Nika Hub Launch and Team Collaboration

  ### New Features

  * Launched Nika Hub for users to view and publish industry solutions, maps and notebooks in its first version
  * Launched Team Hub for teams to publish and view internal assets
  * Added thumbnail AI generation tool for publishing content to Nika Hub

  ### Bug Fixes

  * Fixed geopackage export action stalling Nika Maps
  * Fixed team invitation bug
  * Fixed export layer group as geopackage functionality

  <img alt="Nika Hub" />

  <img alt="Team Hub" />

  <img alt="Nika Hub Publish Dialog" />
</Update>

<Update label="July 20, 2025" description="v0.5.2">
  ## Enhanced Notebook and Vector Toolbox

  ### Feature Improvements

  * Notebook add block is now switched to using horizontal list instead of vertical list of options for better UX
  * Vector toolbox now includes search function for improved tool discovery

  <img alt="Notebook horizontal add" />

  <img alt="Vector toolbox search" />
</Update>

<Update label="July 15, 2025" description="v0.5.2">
  ## Persistent Maps and Collaborative Editing

  ### New Features

  * Persistent Nika Map that auto-saves on user changes

  ### Feature Improvements

  * Map layers are blocked if another user is editing to prevent change conflicts
  * Layer list now shows as a tree that allows drag and drop to reorder layers
  * Multiple maps can now be opened simultaneously to sync their view together
  * Initial map bounds can now be set for better map initialization
  * Vector layer edits in Nika Map now support keyboard shortcuts for quicker switching between edit modes

  <img alt="Multiple Persistent Maps" />

  <img alt="Layer Tree" />

  <img alt="Map Shortcuts" />
</Update>

<Update label="July 6, 2025" description="v0.5.1">
  ## Enhanced Notebook Experience

  ### Feature Improvements

  * Nika Notebook now has automatic Python linter upon code changes
  * Nika Notebook now features a line-by-line accept and reject mechanism instead of the previous accept-all/reject-all approach

  <img alt="Notebook python linter" />

  <img alt="Notebook accept/reject line by line" />
</Update>

<Update label="June 22, 2025" description="v0.5.0">
  ## Flexible Workspace Layout and Enhanced Format Support

  ### New Features

  * Better workspace layout that allows flexible drag and drop of any assets to the centre for viewing or editing
  * Support for more formats to view in the centre: CSV, IMG, PDF

  ### Feature Improvements

  * Better Data search tool for Nika GAIA that now completes search 3 times faster with improved accuracy of 91% (up from 49% previously)

  ### Bug Fixes

  * Fixed scroll down in notebook list causing overflow outside of UI boundaries

    <img alt="New Workspace UI" />
</Update>

<Update label="June 3, 2025" description="v0.4.5">
  ## Nika GAIA (Alpha) v4 and Enhanced AI Capabilities

  ### Feature Improvements

  * Nika GAIA (Alpha) v4 introduces `Analyst` mode that will automatically apply your changes, even execute your code in the VM to get work done
  * Now remembers your `last used LLM type`, and if your analyst mode is on
  * Will now work on files in both the Nika File Storage as well as files dragged from your desktop. The UI now shows you the `upload progress` of files dragged in
  * Now can `list/read` your notebooks or files if prompted (if file privacy from LLM providers is a concern to you, let's discuss how we can support your use case further)
  * Now can read your raster `GeoTIFF` directly
  * Now has better apply and revert mechanism by keeping the snapshot of your notebook/file before changes applied

  <img alt="Nika GAIA v4 Analyst Mode" />

  <img alt="Nika GAIA v4 Interface" />
</Update>

<Update label="May 28, 2025" description="v0.4.4">
  ## Enhanced AI Models and In-Block Coding

  ### Feature Improvements

  * Nika GAIA (Alpha) now supports Claude 4, Gemini 2.5, and Grok 3 too
  * Can stop running at any stages of response generation via the stop button
  * Will automatically track modified item states
  * In-block Coding AI receives huge UI and functional updates:
    * AI model selection
    * Smaller but more intuitive buttons for send, stop, accept change, reject change
    * Input for improving on code change suggestion with follow-up message

  <img alt="AI Model Selection" />

  <img alt="In-Block Coding UI" />

  <img alt="AI Model Selection Interface" />
</Update>

<Update label="May 26, 2025" description="v0.4.3">
  ## Nika GAIA Stability and Notebook Enhancements

  ### Feature Improvements

  * Nika GAIA more stable on notebook edit/create, file edit/create:
    * Add python linter to GAIA output so that it checks its own code before marking the task complete
    * Allow long notebook with long execution output to be added to context for GAIA
    * Attachments UI looks nicer
    * File preview and notebook preview uses new UI with diff mode
    * After apply, there is a revert button
  * Notebook blocks can now be:
    * Dragged and dropped onto the white line marker
    * Left hand side handle now has SHIFT UP or SHIFT DOWN
    * Notebook remembers your latest cursor position when you opens it again
  * Better integration between Notebook and GAIA:
    * New GAIA button on codeblock to add it to GAIA directly for query
    * New Resolve in GAIA button on code execution error to add it to GAIA directly for fix query

  ### Bug Fixes

  * Support .geoparquet extension add to map
  * Support most shapefile extension add to map: .shp, .shx, .dbf, .prj, .cpg, .fix, .sbn, .sbx, .fbn, .fbx, .ain, .aih, .atx, .qix, .qmd

  <img alt="Notebook Block Management" />

  <img alt="File Preview Interface" />

  <img alt="GAIA Integration" />
</Update>

<Update label="May 8, 2025" description="v0.4.2">
  ## File Organization Improvements

  ### Feature Improvements

  * Make files and folders with numbers human-friendly or naturally ordered: `"1", "2", "10", "11", "100"` instead of lexicographically ordered:`"1", "10", "100", "11", "2"`

    <img alt="File Organization" />
</Update>

<Update label="April 26, 2025" description="v0.4.1">
  ## Enhanced Map Visualization and Vector Handling

  ### New Features

  * Drag and drop from Nika file storage or desktop can both add vector or raster layer to map now

  ### Feature Improvements

  * Nika map now can handle visualization of large vector with size up to 15 Million data (points or polygon vertices) without losing details nor chunking
  * Left click a geometry will now select it, while double click it will enter edit mode

  <img alt="Large Vector Visualization" />

  <img alt="Vector Handling" />
</Update>

<Update label="April 24, 2025" description="v0.4.0">
  ## Nika GAIA Alpha and Usage Dashboard

  ### New Features

  * Nika GAIA (Geospatial AI Agent) Alpha is introduced with notebook and file generating/modification capabilities
  * Add a usage dashboard under settings page for user to keep track of their account/team's compute and storage usage (click `Settings` at top right --> click `Usage` on the left panel to access it)

  ### Bug Fixes

  * Fix a bug causing notebook code output to freeze the app when output is too long (e.g. print(geojson))

  <img alt="Nika GAIA Alpha" />

  <img alt="Usage Dashboard" />
</Update>

<Update label="March 27, 2025" description="v0.3.23">
  ## Bug Fixes and Stability Improvements

  ### Bug Fixes

  * Fixed the notebook's code block insertion bug that auto scrolls down unnecessarily when it is inserted before another non-text block
  * Fixed the tab switch bug that the last closed tab of notebook or file editor is still opened again after close
  * Fixed the cursor sharing position deviation issue

    <img alt="Bug Fixes Demo" />
</Update>

<Update label="March 25, 2025" description="v0.3.22">
  ## Cursor Sharing and Comment Capabilities

  ### New Features

  * Cursor sharing when other users are working in the same project and their cursors hover on locations over map
  * Comment capability is available in notebooks now

  ### Feature Improvements

  * File editor also has a suspense loading state to prevent mistake in overriding the content while loading (similar to notebook's release in v0.3.18)

  ### Bug Fixes

  * Fixed 2 notebook bugs:
    * Hyperlink will not contain a wrong https\:// prefix
    * Drag and drop image will be at the correct position of the flat line now
    * Unsupported image types such as .tif will throw a warning when user tries to insert it to notebook

  <img alt="Cursor Sharing" />

  <img alt="Comment Capabilities" />
</Update>

<Update label="March 21, 2025" description="v0.3.21">
  ## Chart Creation and Vector CRS Improvements

  ### New Features

  * Chart creation on attribute table (pie/line/bar charts available now) via manual selection of columns or AI automation

  ### Feature Improvements

  * Operations tracker list is reversed in order to show the most recent action tracker on top such as file upload

  ### Bug Fixes

  * Fixed some vector files added to map becoming a line issue due to incompatible CRS. Now every vector layer added to map is auto converted to 4326 for visualization
  * Fixed the issue when renaming/moving a folder with many subfolders/files in it
  * Fixed file search flashing the results bug and made search faster now

    <img alt="Chart Creation" />
</Update>

<Update label="March 20, 2025" description="v0.3.20">
  ## Auto COG Conversion and Raster Server Fixes

  ### New Features

  * Auto COG conversion when adding raster file to map so that it will be loaded much faster. This happens if GeoTIFF is > 20MB, and it will create a new COG version of the same GeoTIFF in the same folder without changing the source GeoTIFF

  ### Bug Fixes

  * Fixed raster server's existing internal server error that caused adding GeoTIFF to map to fail sometimes
</Update>

<Update label="March 16, 2025" description="v0.3.19">
  ## Layer Tree Format and User Visibility

  ### Feature Improvements

  * Layers are now represented in tree format instead of a list, so that KML or GeoPackage files with more sub groups will be able to shown properly in our UI
  * List of users in the current project will be shown at the top right

  ### Bug Fixes

  * Fixed the issue that KML or GeoPackage were only loading the first sub geometry instead of all of its sub groups of geometries

    <img alt="Layer Tree Format" />
</Update>

<Update label="March 14, 2025" description="v0.3.18">
  ## Notebook and File Storage Enhancements

  ### Feature Improvements

  * Notebook improvements:
    * Hyperlink is shown properly in blue
    * New code block button to stop the running code (the same place as the run code button)
    * New button to clear all outputs at top right of notebook
    * Drop image or past image into notebook is fixed for all
    * Opening notebook will have a loading state to avoid mistakes overriding old content that is not loaded properly yet
  * File storage improvements:
    * Multiple file actions (refresh, change folder, move files, rename files etc) can happen simultaneously now
  * Data catalog improvement:
    * Download dataset will auto refresh progress now every 10 seconds, instead of user having to click to refresh manually

  ### New Features

  * Added more powerful CPU instances with bigger vCPU and Memory size to overcome large compute needs

  ### Bug Fixes

  * Large notebooks that cause crash won't have issue crashing anymore
  * Fixed the proj.db not found when user uses GDAL command or libraries like rasterio that relies on the georeference function of GDAL. Now all georeferencing should work properly when you use pre-installed GDAL in NikaColab notebooks

  <img alt="CPU Instance Selection" />

  <img alt="CPU Instance Details" />
</Update>

<Update label="March 9, 2025" description="v0.3.17">
  ## Notebook and File Management Improvements

  ### Feature Improvements

  * Notebook improvements:
    * Right click duplication in the same project
    * Right click create sharing token across projects with expiry time config
    * Add multi-select checkboxes for notebook list
  * File storage improvements:
    * Add multi-select checkboxes for file list that works for moving/renaming/deletion/dragging of file items

  ### Bug Fixes

  * Downloading data from Data Catalog no longer results in large files caused by wrong resolution previously

  <img alt="Notebook Management" />

  <img alt="File Management" />

  <img alt="Multi-select Interface" />
</Update>

<Update label="February 17, 2025" description="v0.3.15">
  ## Vector Geometry Drawing Fix

  ### Bug Fixes

  * Fix one bug that disallowed users to draw vector geometries on map

  <img alt="Vector Geometry Drawing" />

  <img alt="Share Notebok via Link" />
</Update>

<Update label="February 25, 2025" description="v0.3.16">
  ## Vector Layer Performance and UI Enhancements

  ### Feature Improvements

  * Changed vector layer's attribute table into a table that works with million rows of data (see demo below)
  * Added user name on hover over to user avatar at top right
  * Redesigned the files path UI with more spaced breadcrumb and a "back to previous layer" button (see screenshot below)
  * Added search and scrollable region for notebooks
  * Now download a file will auto start downloading process

  ### Bug Fixes

  * Downloading complex folder no longer results in incomplete ZIP file to local
  * Machine startup no longer spins forever until force refresh the window
  * Notebook tab will sync after notebook rename now
  * Default machine type is no longer blank for new project created but now the CPU type
  * Not every file has a right click add to map option and then some may fail, now only those supported file extensions have that option

  <img alt="Vector Layer Performance" />

  <img alt="UI Enhancements" />
</Update>

<Update label="February 17, 2025" description="v0.3.14">
  ## Shareable Links and AI Dataset Integration

  ### New Features

  * Add create shareable link to allow copying notebooks
  * Add dataset to map via AI

  ### Bug Fixes

  * Fix one bug on unable to load GPKG

  <img alt="Shareable Links" />

  <img alt="AI Dataset Integration" />
</Update>

<Update label="January 28, 2025" description="v0.3.13">
  ## CPU Machine Upgrade and Data Catalog UI

  ### Feature Improvements

  * Default CPU machine size is increased from 11 GB to 24GB, while maintaining the same speed of 15s to have one running successfully
  * Data Catalog now has support for bound visualization on hover over

  ### Features Removal

  * Data Catalog has a new UI as a columnar list on the right instead of the dialog covering the entire center of the page before this

  ### Bug Fixes

  * Fix one bug that causes KML files to not be addable to map to visualize

    <img alt="Data Catalog UI" />
</Update>

<Update label="January 23, 2025" description="v0.3.12">
  ## Extended Dataset Support and AI Search Improvements

  ### New Features

  * Added another 54 datasets to be supported in Data Catalog, Including SRTM DEM, Copernicus CORINE, Global ALOS, WAPOR, MODIS etc

  ### Feature Improvements

  * Most of the datasets in Data Catalog have a more accurate data catalog to begin with
  * The AI search is now producing better results than before

  ### Feature Removal

  * Remove the need for some datasets in Data Catalog to require an Area of Interest to visualize with, so now every dataset with AOI is optional

  ### Bug Fixes

  * Fix one where date range slider allows end-date to be earlier than start-date
  * Fix local raster added to map with one band can use multibands mode error
  * Fix new dataset from Data Catalog added to map with global bound has some displaced until user zooming in

    <img alt="Extended Dataset Support" />
</Update>

<Update label="January 20, 2025" description="v0.3.11">
  ## Role-Based Access Control Implementation

  ### New Features

  * Project-level role access control: Editor, Commentator, Viewer (e.g. viewer cannot create/edit notebook but can only list/read notebooks)
  * Team-level role access control: Admin, Member (e.g. member cannot delete project, modify team name or description, while admin can)

  ### Feature Improvements

  * In the list of projects to switch to, they are sectioned by team and team name cannot be clicked

  ### Bug Fixes

  * Sharing a project as project editor while not yet verified team invitation had led to app crash, now fixed
  * Shared project's team avatar is correct now

    <img alt="Role-Based Access Control" />
</Update>

<Update label="January 14, 2025" description="v0.3.9">
  ## Code/Notebook Integration and File Editor Enhancements

  ### Feature Improvements

  * Code/Notebook section merged into the same area with tabs so that user can switch between opened ones
  * Added close all tabs
  * Support more file types for edit in NikaPlanet: *sh|bash|xml|yaml|yml|vue|dockerfile|toml|r|lua|perl|pl|kt|maven|pom|scala|dart|svelte*
  * Dark theme for file editor is more visible now
  * New notebook created comes with an initial content that guides user on how to use it
  * Make all files in edit autosaving by default

  ### Bug Fixes

  * Indentation with TAB key is fixed for file editor

    <img alt="Code/Notebook Integration" />
</Update>

<Update label="December 28, 2024" description="v0.3.8">
  ## Enhanced Data Catalog Layer Customization

  ### Feature Improvements

  * Added layer customization of data from Data Catalog:
    * Select display modes: Single-channel, RGB, or spectral indices
    * Switch between dataset bands seamlessly
    * View histogram statistics with rescaling options
    * Customize color maps for improved visualization
    * Clip datasets to your desired Area of Interest (AOI) or remove clip (which defaults back to max bound of dataset)

  ### Bug Fixes

  * Resolved issues with visualizing global datasets (e.g., Copernicus LC100). The new clipping feature now supports visualization of both global and non global datasets

    <img alt="Data Catalog Layer Customization" />
</Update>

<Update label="December 19, 2024" description="v0.3.7">
  ## Team Management and Data Download Enhancements

  ### New Features

  * Teams page is added for user to manage team members (invite/remove/resend invitation) which is accessible from top right of the project main page
  * During new project creation, user can specify which team to create the project under. Projects created under a team will by default shared with the team

  ### Feature Improvements

  * Added min, max, mode, mean, mosaic compositing options for downloading raw data

  ### Bug Fixes

  * Fixed geodesic projections for clipped visualizations for dataset from Data Catalog used with AOI. Before this, some result image on map is clipped with curved line, which is now resolved

  <img alt="Team Management" />

  <img alt="Team Management Interface" />
</Update>

<Update label="December 16, 2024" description="v0.3.6">
  ## AOI Selection and SkySat Dataset Support

  ### New Features

  * Select AOI from a map geometry layer to clip one-click visualized datasets, or for downloading datasets

  ### Feature Improvements

  * Supported new high-res SkySat Datasets
  * Added scale field for download, to enable high-res
  * Removed choice of raw/processed download, automatically selected based on dataset type

  ### Features Removal

  * Upload geojson to clip area for downloading data from Data Catalog is removed. But user can simply upload to Files on the left and add the geojson to map as a layer to clip
</Update>

<Update label="December 13, 2024" description="v0.3.5">
  ## Point Labeling and GeoSAM Integration

  ### New Features

  * Label points as positive or negative directly
  * Run GeoSAM version 1 with labelled points on GeoTIFF images directly

  ### Feature Improvements

  * Add feature name which uses attribute field name to show on UI

  ### Bug Fixes

  * Fixed status name at top right after running certain actions to not show weird characters

    <img alt="Point Labeling and GeoSAM" />
</Update>

<Update label="December 9, 2024" description="v0.3.4">
  ## Vector Operations and Layer Management

  ### New Features

  * User could run dissolve and clip on polygon geojson on map layer to created dissolved or clipped geojson layer

  ### Feature Improvements

  * User could reorder the list of layers to make one layer show on top of another
  * User could reorder the features within geojson layer
  * User could move features between geojson layers by drag and drop

  <img alt="Vector Operations" />

  <img alt="Layer Management" />
</Update>

<Update label="December 6, 2024" description="v0.3.3">
  ## Project Sharing and Collaboration

  ### New Features

  * Project sharing by email to invite specific user to work on the same project
  * Project sharing to allow anyone in the public to access by link to work on the same project

    <img alt="Project Sharing" />
</Update>

<Update label="December 3, 2024" description="v0.3.2">
  ## File Editing and Performance Improvements

  ### New Features

  * Ability to double click or right click to edit files directly in NikaWorkspace (supports .py, .js, .jsx, .ts, .tsx, .txt, .java, .cpp, .c, .h, .css, .geojson, .html, .json, .md, .sql, .php, .rb, .go, .rs, .swift)

  ### Feature Improvements

  * Machine creation time shortened from 4-5 mins to 2.25 mins on average with key architectural improvements

    <img alt="File Editing" />
</Update>

<Update label="November 27, 2024" description="v0.3.1">
  ## Python Version Update and Bug Fixes

  ### Feature Improvements

  * Downgraded nika VM to use Python 3.10 as default to support more libraries such as Numba

  ### Bug Fixes

  * Fixed error when raster image is selected, user cannot draw vectors on it
  * Fixed bug causing download public dataset in data catalog to not work
</Update>

<Update label="November 25, 2024" description="v0.3.0">
  ## Major Vector Features Release

  ### New Features

  * Add vector to map by right click a GeoJSON/KML/SHP/GPKG/GeoParquet file
  * Vector select and edit
  * Vector feature attribute view and edit
  * Vector functions and measurements
  * Change the AI function in the floating panel to a Search + AI
  * Vector layer export as a geojson to nika file storage or local desktop
  * Vector style changes: fill color, fill opacity, line color, line opacity

  > **Note**: Raster/vector layers do not persist across sessions (feature in progress)

  <img alt="Vector Features 1" />

  <img alt="Vector Features 2" />
</Update>

<Update label="November 19, 2024" description="v0.2.12">
  ## Enhanced File Management and Data Catalog

  ### New Features

  * Drag and drop multiple files folders directly from local devices for seamless uploads
  * Move files and folders anywhere within the platform
  * Added option to select a composite band to process and visualize raw data in the data catalog

  ### Bug Fixes

  * Improved upload time estimation for better reliability
  * Fixed drag-and-drop within NikaWorkspace; no more cell shifting issues
  * Resolved flickering when dragging files from the local OS
  * Fixed bug when downloading datasets in data catalog by removing QA bands from band selection

  <img alt="File Management 1" />

  <img alt="File Management 2" />
</Update>

<Update label="October 30, 2024" description="v0.2.11">
  ## Enhanced File Search

  ### New Features

  * Search Files now works for everything in all subfolders in current folder
  * When user scrolls down, it will search everything until all files fully exhausted

  ### Bug Fixes

  * Fixed bug that caused file to be moved to outside of the project root folder
  * Fixed flickering issue with the drop file to upload from Windows OS

    <img alt="Enhanced File Search" />
</Update>

<Update label="October 29, 2024" description="v0.2.10">
  ## Data Catalog Improvements

  ### Bug Fixes

  * Fixed many issues in Data Catalog:
  * Added form validations for maxCloudCover, maxImages, bands
  * Added button for select all / clear all bands
  * Added bound for each data visualized on map (RIGHT CLICK to zoom to fit to layer)
  * Download dataset can show error message at bottom right if download failed
</Update>

<Update label="October 28, 2024" description="v0.2.9">
  ## Notebook Resizing and Multi-Language Support

  ### New Features

  * Allow user to resize the NikaColab notebook by dragging the edge between opened notebook and map
  * Added most popular language support for UI: English, Español, Français, Deutsch, Italiano, Português, Nederlands, Polski, Русский, 日本語, 한국어, 中文, العربية, עברית, Türkçe, Bahasa Indonesia, தமிழ், ไทย, Filipino, Tiếng Việt, Bahasa Melayu
  * Added copy output for html table (e.g., print table from duckdb in output)

  ### Bug Fixes

  * Fixed wrong UpdatedAt for notebooks in its menu on right click
  * Fixed root dir of NikaColab notebook that now uses /data (PLEASE UPDATE YOUR CODE ACCORDINGLY)
  * Fixed display data for dataframe table (e.g., print table from duckdb in output)
  * Added ... to the lists so that iPad users can click too

    <img alt="Notebook Resizing" />
</Update>

<Update label="October 22, 2024" description="v0.2.8">
  ## Data Catalog Introduction

  ### New Features

  * Added Data Catalog to allow users to visualize public datasets from GEE data catalog to map or download them to project file storage
  * Expect some bugs as we are continuously upgrading this feature in future releases

  ### Bug Fixes

  * Fixed issue that caused the file list to fail
  * Updated the task manager at bottom right to accommodate more task types
</Update>

<Update label="October 14, 2024" description="v0.2.7">
  ## Enhanced Machine Types and File Management

  ### New Features

  * Added Downloader class of machine type with bigger CPU and network throughput
  * Updated files UI to follow the new UI library while retaining all past capabilities
  * Added .TIF and .TIFF as allowed extensions for GeoTIFF files for add to map

  ### Bug Fixes

  * Fixed behavior that some TIF files cannot be added to map due to server issue
</Update>

<Update label="October 6, 2024" description="v0.2.6">
  ## AI Enhancement and UI Improvements

  ### New Features

  * Made the nika AI buttons in notebooks more obvious with `Modify` and `Query` text
  * Upgraded generative AI for coding to a more intelligent version
  * Added demo videos to tutorial steps and each target section: `project`, `machine`, `file`, `notebook`, `layer`
  * Added button for Fix Code with AI

  ### Bug Fixes

  * Fixed behavior that clicking range input box in layer control close menu
  * Fixed hvplot not showing up
</Update>


# NikaDashboard
Source: https://docs.nikaplanet.com/nika-planet/nika-dashboard

Real-time analytics dashboard builder for geospatial data visualization and business intelligence

## Overview

NikaDashboard is a powerful real-time analytics dashboard builder designed specifically for geospatial data visualization and business intelligence. Built for teams and organizations that need to create interactive dashboards with live data feeds, NikaDashboard provides an intuitive drag-and-drop interface for building custom analytics dashboards without coding.

<img alt="NikaDashboard Interface" />

## Why NikaDashboard for Spatial Dashboards?

NikaDashboard offers unique advantages over traditional BI tools like **Tableau** or **Databricks SQL/BI**, and GIS-specific platforms like **ArcGIS Dashboards**:

* **Custom Widget Generation**: Generate custom widgets that work exactly as needed, providing flexibility beyond standard chart libraries.
* **Direct NikaMap Integration**: Native integration with the powerful NikaMap engine enables advanced geospatial visualizations that are deeply synchronized with your dashboard data.
* **Complete Theme Control**: Create your own styles and themes. Every element—from buttons to color palettes—can be customized to align perfectly with your brand kit.
* **Layout Versatility**: Switch between a classic side-by-side canvas layout (classic style) or an overlay mode where widgets sit on top of a single, interactive map.

## Key Features

### Visual Dashboard Builder

* **Drag-and-Drop Interface**: Build dashboards visually with no coding required
* **Real-time Preview**: Switch between Edit and Preview modes to see how dashboards appear to end users
* **Customizable Layouts**: Flexible grid system for arranging widgets and components on blank canvas or over a map
* **Mobile Support**: Responsive design for viewing dashboards on mobile or tablet devices

### Real-time Data Integration

* **Live Data Feeds**: Connect to real-time data sources for up-to-the-minute analytics
* **Multiple Data Sources**: Support for databases and CSV/GeoJSON imports
* **Auto-refresh**: Configurable refresh intervals for different data sources
* **Data Validation**: Built-in data quality checks and error handling

### Collaboration & Sharing

* **Team Dashboards**: Create and share dashboards across your organization
* **Permission Controls**: Granular access control for different user roles
* **Version History**: Track changes and maintain dashboard edit history

## Dashboard Components

### Data Sources

* **Enternal API**: External API integration as data influx
* **Enterprise Database**: Historical data warehouse connectivity
* **CSV Data Import**: Upload and process CSV data files
* **IoT Data Stream**: Real-time IoT device data integration via MQTT

### Widget Types

* **Data Filter**: Filter data by various column and expressions so that map and table are updated
* **AOI Upload**: Upload GeoJSON or Shapefile to define the area of interest for the dashboard
* **Bar Chart**: Comparative analysis and category breakdowns with customizable styling
* **Line Chart**: Time series visualization for temporal data analysis and trends
* **Graph Chart**: Network and relationship visualization for complex data structures
* **Map**: Interactive geographic visualization with custom styling and overlays
* **Icon Board**: Visual display with icons, metrics, and status indicators
* **Text Board**: Rich text display for annotations, descriptions, and contextual information

### Common Use Cases

* **Traffic Monitoring**: Real-time visitor analytics and traffic source analysis
* **Geographic Insights**: Visitor distribution by region and location
* **Location Analytics**: Geographic distribution of users, customers, or assets
* **Movement Analysis**: Traffic flow patterns and movement visualization
* **Regional Performance**: Location-based performance metrics and comparisons
* **Spatial Correlation**: Geographic relationships and spatial analysis

## Integration

NikaDashboard integrates seamlessly with other Nika products:

* **NikaWorkspace**: Use workspace data as source directly in dashboards
* **NikaMap**: Embed interactive maps in dashboard widgets
* **NikaGeoEngine**: Use serverless functions for custom data processing
* **NikaDBMS**: Use database data directly as source in dashboards


# NikaDBMS
Source: https://docs.nikaplanet.com/nika-planet/nika-dbms

Advanced geospatial database management system for data science with AI-powered SQL generation and seamless workspace integration

# NikaDBMS

<img alt="NikaDBMS Interface" />

## Powerful Geospatial Database Management

NikaDBMS is a comprehensive database management system designed specifically for geospatial data science workflows. Connect to multiple database types, leverage AI-powered SQL generation, and seamlessly integrate with your NikaWorkspace data lake.

## Key Features

### AI-Powered SQL Generation

* **Intelligent Query Builder** - Natural language to SQL conversion
* **Geospatial Function Support** - ST\_READ, ST\_AsText, spatial joins, and more
* **Context-Aware Suggestions** - AI understands your schema and suggests optimal queries
* **Multiple AI Models** - Choose from GPT-4, Claude, and other leading models

### Workspace Integration

* **Direct Data Lake Access** - Query files directly from your NikaWorkspace
* **File Format Support** - KML, GeoJSON, Shapefile, Parquet, and more
* **Map Integration** - Use query results as map layers instantly
* **Collaborative Features** - Share queries and results with your team

### Multi-Database Support

NikaDBMS supports a wide range of geospatial databases, from lightweight local solutions to enterprise-grade cloud platforms.

### Core Databases

<Columns>
  <Card title="PostgreSQL" icon="🐘">
    Full spatial extensions support with PostGIS for advanced geospatial operations and analysis.
  </Card>

  <Card title="DuckDB (Managed)" icon="🦆">
    High-performance analytical database with built-in spatial functions for fast geospatial queries.
  </Card>

  <Card title="MotherDuck" icon="☁️">
    Cloud-native DuckDB service with serverless architecture and seamless scalability.
  </Card>
</Columns>

### Enterprise Solutions (Upon Request)

<Columns>
  <Card title="Oracle DB" icon="🏢">
    Enterprise spatial database with advanced analytics and high-performance geospatial processing.
  </Card>

  <Card title="Snowflake" icon="❄️">
    Cloud data warehouse with native geospatial support and massive scalability.
  </Card>

  <Card title="BigQuery" icon="🔍">
    Google's serverless data warehouse with built-in geospatial functions and ML capabilities.
  </Card>

  <Card title="Amazon Redshift" icon="🔴">
    AWS data warehouse with spatial extensions for large-scale geospatial analytics.
  </Card>

  <Card title="Esri GeoDatabase" icon="🗺️">
    Geographic information system with comprehensive spatial analysis and mapping capabilities.
  </Card>

  <Card title="SQLite (SpatiaLite)" icon="🗃️">
    Lightweight spatial database perfect for mobile and embedded geospatial applications.
  </Card>
</Columns>

## Core Capabilities

### Geospatial Query Processing

* **Spatial Functions** - Full support for PostGIS and DuckDB spatial functions
* **File Direct Access** - Query KML, GeoJSON, and other formats directly
* **Coordinate System Support** - Automatic CRS detection and transformation
* **Performance Optimization** - Spatial indexing and query optimization

### Data Science Workflows

* **Statistical Analysis** - Built-in functions for spatial statistics
* **Machine Learning Integration** - Export data for ML pipelines
* **Visualization Ready** - Results formatted for immediate mapping
* **Reproducible Research** - Save and version control your queries

### Enterprise Features

* **Multi-User Support** - Role-based access control
* **SQL Query History** - Track and replay previous queries
* **Performance Monitoring** - Query execution analytics
* **Data Security** - Encrypted connections and secure data handling

## Getting Started

### 1. Connect Your Database

Choose from supported database types and configure your connection:

* **PostgreSQL**: Standard connection with spatial extensions
* **DuckDB Managed**: Instant setup with Nika's managed service
* **MotherDuck**: Cloud-native with enterprise features

### 2. AI-Powered Querying

Use natural language to generate complex spatial SQL queries with AI assistance that converts your requests into optimized SQL statements.

### 3. Visualize Results

* **Instant Mapping(To be built)** - Query results appear as map layers
* **Interactive Tables** - Explore data with built-in table viewer
* **Export Options** - Download as CSV, GeoJSON, or other formats

## Use Cases

### Environmental Monitoring

* **Satellite Data Analysis** - Process large raster datasets
* **Change Detection** - Compare temporal geospatial data
* **Habitat Mapping** - Analyze species distribution patterns

### Urban Planning

* **Population Analysis** - Demographic data with spatial context
* **Infrastructure Planning** - Network analysis and optimization
* **Zoning Analysis** - Land use pattern recognition

### Research & Academia

* **Spatial Statistics** - Advanced analytical functions
* **Data Integration** - Combine multiple data sources
* **Publication Ready** - Export results for research papers

## Integration Benefits

### With NikaWorkspace

* **Seamless Data Access** - Query files directly from your workspace
* **No Data Duplication** - Work with original data sources
* **Version Control** - Track changes to your datasets

### With NikaMap (To be built)

* **Live Data Layers** - Query results as interactive map layers
* **Real-time Updates** - Refresh data without re-querying
* **Spatial Analysis** - Perform complex spatial operations

### With NikaNotebook (To be built)

* **Code Generation** - Export queries as Python/SQL code
* **Reproducible Workflows** - Document your analysis process
* **Collaborative Analysis** - Share notebooks with your team

## Performance & Scalability

* **High-Performance Queries** - Optimized for large geospatial datasets
* **Parallel Processing** - Multi-threaded query execution
* **Memory Management** - Efficient handling of large result sets
* **Caching** - Intelligent query result caching

## Security & Compliance

* **Encrypted Connections** - All database connections are encrypted
* **Access Control** - Role-based permissions and user management
* **Data Privacy** - Client data remains under your control

## Getting Started

Ready to supercharge your geospatial data science workflows? Start with NikaDBMS today and experience the power of AI-assisted geospatial database management.


# NikaFlow
Source: https://docs.nikaplanet.com/nika-planet/nika-flow

Visual ETL conversion engine for geospatial and 3D formats - like FME Flow but built for modern cloud workflows

## Overview

NikaFlow is a visual ETL (Extract, Transform, Load) conversion engine designed specifically for geospatial and 3D data formats. Built like FME Flow but optimized for modern cloud workflows, NikaFlow provides an intuitive drag-and-drop interface for creating data transformation pipelines without coding.

<img alt="NikaFlow Interface" />

## Key Features

### Visual Workflow Designer

* **Drag Interface**: Build ETL workflows visually with no coding required
* **Pre-built Transformers**: Extensive library of geospatial and 3D transformation tools
* **Real-time Preview**: See data transformations as you build
* **Multi-user Edit**: Built and modify together with your team members, nothing missed!

### Geospatial Format Support

* **Vector Formats**: Shapefile, GeoJSON, GeoPackage, KML, KMZ, FlatGeobuf, GeoParquet
* **Raster Formats**: GeoTIFF, COG, ECW, HFA, JPEG, JPEG2000, CADRG
* **3D Point Cloud**: LAS, LAZ, XYZ, PLY, PNTS
* **3D Mesh/Scene**: STL, OBJ, DAE, GLB, GLTF, B3DM (to be built)
* **3D Tiled**: 3D Tiles, I3S
* **Style Formats**: LYRX, SLD, QML

*More format support can be added upon request, you can contact [sales@nikaplanet.com](mailto:sales@nikaplanet.com) to discuss more*

### Advanced Transformations

* **Coordinate System Conversion**: CRS detection and transformation options available
* **Data Validation**: Data visualization directly in Nika Web UI

### Data Integration

* **NikaWorkspace Data Lake**: Direct integration with data already uploaded to NikaWorkspace

## Common Use Cases

### Data Transformation

* **Legacy System Migration**: Convert old GIS data formats such as CADRG to modern formats

### Data Processing (to be built)

* **Coordinate System Conversion**: Transform data between different CRS
* **Compression**: Choose different supported compression algorithm during conversion (lossy or lossless)
* **Split/Merge Operations**: Use wildcard filename to merge multiple sources into one or use split flag to separate each object from the source

### 3D Data Processing

* **Point Cloud Processing**: Convert and process LiDAR data
* **3D Mesh/Scene Conversion**: Transform between different 3D model formats (to be built)
* **3D Tiles Generation**: Create optimized 3D tile formats for web visualization

### Source Trigger Pipeline

* **Upload Trigger**: Set the source to be a folder, so that every new batch of uploaded files there will be auto converted based on prior configuration (to be built)


# NikaHub
Source: https://docs.nikaplanet.com/nika-planet/nika-hub

Showcase and discover published apps, solutions, maps, and notebooks from our community

## Overview

NikaHub is a vibrant community platform where users can discover, share, and showcase their geospatial applications, data visualizations, maps, and analysis notebooks. It serves as a central hub for the Nika community to learn from each other and find inspiration for their own projects.

<img alt="NikaHub Interface" />

## Key Features

### Discovery

* **Browse by Category**: Filter content by type (apps, maps, notebooks, solutions)
* **Search & Filter**: Advanced search with tags, technologies, and data types

### Publishing

* **Easy Publishing**: One-click publishing from NikaWorkspace and NikaStudio
* **Access Control**: Either for public, for team-only, or for specific audience with password protection option
* **Thumbnail**: Use uploaded image or AI generated image as thumbnail for relevancy

## Content Types

### Applications

* **Web Applications**: Interactive web apps built with NikaStudio
* **Mobile Apps**: Cross-platform mobile applications

### Maps & Visualizations

* **Interactive Maps**: Dynamic, feature-rich maps
* **Data Dashboards**: Comprehensive data visualization dashboards

### Notebooks & Analysis

* **Jupyter Notebooks**: Data analysis and research notebooks
* **Tutorials**: Step-by-step guides and tutorials
* **Research Papers**: Academic and research publications
* **Case Studies**: Real-world application examples

### Solutions

* **Industry Solutions**: Sector-specific applications
* **Templates**: Reusable project templates
* **Workflows**: Automated analysis pipelines

## Getting Started

### Browsing Content

Visit the [NikaHub](https://planet.nika.eco/hub) to explore community content:

1. **Use the search bar** to find specific content
2. **Filter by category** to narrow down results
3. **Sort by date, or rating**
4. **Click on items** to view details and interact

### Publishing Your Work

#### From NikaWorkspace

After completing your analysis in NikaWorkspace, easily publish your work to the gallery with custom titles, descriptions, categories, and tags.

#### From NikaStudio

After building your application in NikaStudio, publish it to the gallery with detailed descriptions and appropriate categorization for community discovery.

## Hub Categories

### Applications

* **Urban Planning**: City planning and development tools
* **Environmental Monitoring**: Climate and environmental applications
* **Transportation**: Traffic and logistics solutions
* **Real Estate**: Property and market analysis tools
* **Public Health**: Health and epidemiology applications

### Maps & Visualizations

* **Point Maps**: Location-based data display
* **Raster Maps**: Satellite based imagery display
* **Time Series Maps**: Temporal data visualization
* **Local Maps**: Using high res drone JPEG directly to display

### Analysis & Research

* **Spatial Analysis**: Geographic data analysis
* **Statistical Analysis**: Statistical modeling and inference
* **Machine Learning**: AI and ML applications
* **Remote Sensing**: Satellite and aerial data analysis
* **Survey Analysis**: Field data collection and analysis

## Industry Solutions

with some examples below:

#### [ADSB Flight Data Processing](/industrial-solutions/adsb-flight-data)

Comprehensive data pipeline for downloading, processing, and visualizing ADS-B flight tracking data with regional GeoJSON generation. Process flight traces from GitHub releases into DuckDB database and generate regional GeoJSON files for flight path visualization.

#### [Singapore MRT Yearly Visualization](/industrial-solutions/singapore-mrt-yearly-visualisation)

Process Singapore MRT rail network GeoJSON and split into separate files organized by year and rail line for historical development analysis. Normalizes line names and creates individual GeoJSON files for each line's opening year.

#### [Watershed Urban Impact Analysis](/industrial-solutions/watershed-urban-impact-analysis)

Assess the degree of urbanization within individual watersheds and classify them based on urban impact levels using satellite imagery and geospatial analysis. Quantifies built-up area within watersheds and generates comprehensive visualizations.

## Integration

NikaHub integrates with other Nika products:

* **NikaWorkspace**: Publish analysis results and notebooks
* **NikaStudio**: Share applications and dashboards
* **AI Agent**: Get recommendations for similar projects


# NikaLabeler
Source: https://docs.nikaplanet.com/nika-planet/nika-labeler

World's first geospatial-friendly labeler for annotating satellite and drone images with real-time collaboration, SAM 2.0 AI assistance, and seamless NikaWorkspace integration

## Overview

NikaLabeler is the world's first and only geospatial-friendly image annotation platform designed specifically for top-down satellite and drone imagery. Built for efficiency and collaboration, it enables teams to annotate geospatial datasets with real-time synchronization, AI-powered assistance, and seamless integration with NikaWorkspace's data lake.

<img alt="NikaLabeler Interface" />

## Key Features

### Real-time Co-annotation

* **Live Collaboration**: Multiple users can annotate simultaneously with real-time sync
* **Cursor Synchronization**: See team members' cursor positions in real-time
* **Live State Updates**: Approve/reject states and comments sync instantly across all users
* **Progress Tracking**: Real-time progress bar at the top showing annotation completion

### Annotation Format Import/Export

* **Import/Export**: Support for various annotation formats including COCO 1.0
* **COCO 1.0 Compatible**: Full support for importing and exporting in standard COCO 1.0 format
* **Format Compatibility**: Seamless integration with existing ML pipelines

### Show Image Bound in NikaMap

* **Geographic Context**: Load current image in a [NikaMap](/nika-planet/nika-map) for geo-referencing
* **Spatial Navigation**: Navigate between images with geographic awareness
* **Coordinate Reference**: Maintain spatial accuracy throughout annotation process

### SAM2 Smart Segmentation

* **Interactive Segmentation**: Left-click for positive prompts, right-click for negative prompts
* **Intelligent Suggestions**: AI-powered object detection and segmentation
* **Faster Annotation**: Speed up annotation workflow with smart AI assistance

### SAM3 Text-Prompted Segmentation

* **Text-Based Segmentation**: Leverage SAM3's cutting-edge text prompting to segment objects by simply describing them
* **Boost Efficiency**: Dramatically accelerate annotation workflows by using natural language instead of manual clicks
* **Smart Object Detection**: Automatically identify and segment complex objects using descriptive text prompts

### Team Management

* **Role-Based System**: Reviewer and Labeler roles with distinct permissions
* **Task Assignment**: Assign and re-assign annotation tasks to specific labelers
* **Approval Workflow**: Built-in review process with approve/reject action
* **Performance Tracking**: Labeler overview page showing percentage rejected/total for individual performance

## Data Integration

### NikaWorkspace Integration

* **Direct Data Lake Access**: Load JPEG and PNG images directly from NikaWorkspace's data lake filesystem
* **Task Creation**: Create annotation tasks directly with folders in NikaWorkspace's data lake
* **Seamless Workflow**: No need to download/upload files - work directly with TBs of images in Nika's cloud platform

### Image Processing

* **Auto Batch Conversion**: Automatically convert GeoTIFF (RGB channels) to JPEG for faster UI loading
* **Format Support**: Native support for GeoTIFF, JPEG, PNG, and other common formats
* **Optimized Performance**: Efficient image loading and rendering for large datasets

## User Interface

### Annotation Tools

* **Polygon Drawing**: Draw and edit precise polygon annotations
* **Navigation Controls**: Pan and zoom functionality for detailed annotation work
* **Keyboard Shortcuts**: Efficient annotation with customizable keyboard shortcuts
* **Intuitive Design**: Clean, geospatial-focused interface optimized for satellite imagery

### Job Management

* **Job States**: Track progress with states (pending, in-progress, submitted for review, rejected, approved)
* **Image Instructions**: Add instruction messages per image as caveats for specific annotation requirements
* **Batch Operations**: Process multiple images efficiently with batch tools


# NikaMap
Source: https://docs.nikaplanet.com/nika-planet/nika-map

High-performance WebGL-based map framework for large-scale geospatial data. NikaMap Sync adds real-time collaboration with auto-save like Google Docs for maps

## Overview

NikaMap is a high-performance WebGL-based large-scale map framework designed to handle massive geospatial datasets with unprecedented efficiency. Leveraging advanced GPU-accelerated rendering techniques, NikaMap delivers desktop-class GIS performance directly in the browser.

<img alt="NikaMap Interface" />

## Core Capabilities

### High-Performance Rendering

* **Large-Scale Vector Data**: Efficiently render millions of vector features with GPU-accelerated processing
* **Massive Raster Support**: Handle gigabytes of raster imagery with intelligent tiling and streaming
* **Advanced Symbology**: Rich styling capabilities including data-driven visualizations, custom color ramps, and complex symbology rules
* **3D Visualization**: Native 3D rendering support for terrain, buildings, and volumetric data
* **Smooth Performance**: WebGL-powered rendering ensures fluid interactions even with complex datasets

### Data Format Support

* **Vector Formats**: GeoParquet, GeoPackage, FlatGeobuf, GeoJSON, Shapefiles, KML/KMZ
* **Raster Formats**: GeoTIFF, Cloud Optimized GeoTIFF (COG), JPEG2000, ECW, HFA
* **Drone Imagery**: Native support for JPEG with EXIF metadata and aerial photography

### Visualization Features

* **Multiple Layer Types**: Vector, raster, point cloud, and 3D layers
* **Custom Styling**: Advanced styling options for all data types
* **Interactive Features**: Popups, tooltips, and dynamic interactions

## NikaMap Sync

<img alt="NikaMap Sync" />

NikaMap Sync is a collaborative variant of NikaMap that brings real-time collaboration and cloud-native capabilities to large-scale mapping. With NikaMap Sync, you get a desktop-native GIS experience in the cloud with seamless access to massive datasets.

### Real-Time Collaboration

* **Multi-User Editing**: Multiple users can edit maps simultaneously with live cursor tracking
* **Auto-Save Like Google Docs**: Every change is automatically saved in real-time—never lose your work
* **Instant Synchronization**: See changes from collaborators appear instantly on your map
* **Conflict Resolution**: Intelligent conflict detection and automatic resolution for concurrent edits

### Cloud-Native GIS Experience

* **Desktop Performance in Browser**: Full-featured GIS capabilities without installing desktop software
* **Seamless Data Access**: Tap into large-scale datasets stored in the cloud without local downloads
* **Version History**: Track all changes with complete edit history and rollback capabilities
* **Collaborative Permissions**: Granular control over who can view, edit, or manage map layers

### Enterprise Features

* **Team Workspaces**: Organize maps and data within shared team environments
* **Change Tracking**: Audit trail of all edits with user attribution and timestamps
* **Branching & Merging**: Create map variants and merge changes back to main version
* **Real-Time Notifications**: Get notified when collaborators make changes to shared maps

## Getting Started

### Creating Your First Map

Initialize NikaMap with your container element and configure center, zoom, and visualization options. Add various layer types including vector layers with millions of polygons, raster layers with gigabytes of data, and drone imagery with automatic georeferencing.

For NikaMap Sync, simply enable the `sync` option to activate real-time collaboration and auto-save features.

## Integration

NikaMap integrates seamlessly with other Nika products:

* **[NikaWorkspace](/nika-planet/nika-workspace)**: Use workspace data directly in maps
* **[NikaStudio](/nika-planet/nika-studio)**: Embed maps in custom applications
* **[NikaHub](/nika-planet/nika-hub)**: Share and publish maps
* **[NikaNotebook](/nika-planet/nika-notebook)**: Analyze map data with Python notebooks

*There are more real-life examples published by Nika community at [https://planet.nika.eco/en/hub/maps](https://planet.nika.eco/en/hub/maps)*


# NikaNotebook
Source: https://docs.nikaplanet.com/nika-planet/nika-notebook

Collaborative Python notebooks for geospatial data analysis with real-time sharing and AI-powered assistance

## Overview

NikaNotebook is a collaborative Python notebook environment designed specifically for geospatial data analysis. Built on Jupyter technology with real-time collaboration features, it enables teams to work together on spatial analysis projects with AI-powered assistance and seamless integration with Nika's data ecosystem.

<img alt="NikaNotebook Interface" />

## Key Features

### Collaborative Notebooks

* **Real-time Collaboration**: Multiple users can edit notebooks simultaneously
* **Live Cursor Tracking**: See where team members are working in real-time
* **Comment System**: Add comments and discussions directly in notebooks

### Geospatial-Focused Environment

* **Pre-installed Libraries**: GDAL, CUDA, Python, Linter
* **Team preferred Libraries**: Add a list of your usual library (to be built)
* **Data Integration**: Direct access to NikaWorkspace data lake
* **AI Assistance**: Get intelligent code modification suggestions from NikaGAIA

### Server-Based Processings

* **Offline Processing Enabled**: Even if your internet is cut, your code that is running will run until completion on the server side and update the results for you to see when you reconnects back the next monitoring to continue your work
* **Auto Shutoff Enabled**: To save compute resources, the VM that is in idle state and no user is connected to it will auto shut off in 15 minutes

### Flexible Compute Options

* **CPU-Only VMs**: High CPU-to-RAM ratio configurations (CPUx3: 3 cores/24GB, CPUx7: 7 cores/53GB, CPUx21: 20 cores/156GB, CPUx42: 42 cores/326GB) optimized for memory-heavy geospatial processing and large dataset analysis
* **GPU-Enabled VMs**: NVIDIA Tesla T4 configurations (T4x1: 6 cores/24GB/16GB GPU, T4x2: 14 cores/50GB/32GB GPU, T4x4: 30 cores/100GB/64GB GPU) designed for machine learning and AI workloads
* **Custom Configurations**: Even larger VMs with more RAM or H100 GPUs available upon request for enterprise-scale processing
  <img alt="NikaNotebook Interface" />

### Remote Cloud Execution

Run compute-heavy functions on dedicated VMs. Decorate any Python function with `@run(compute=...)`, call `.submit()` to dispatch it to a separate runner pod, and keep working in the notebook while the job executes in parallel.

* **Background execution and non-blocking**: the notebook stays live while runs execute on their own machines, shutting down the VM does not cancel in-flight jobs
* **Flexible compute per run**: customize the run to use CPU-only or GPU-enabled VMs, independent of the notebook VM
* **Results and logs**: poll status, view logs, and retrieve results anytime after the run is completed

**[Python SDK reference →](/guides/code-cloud-delegation/python-sdk)**

<Note>
  **Output retention:** Outputs from any run will only be kept for a maximum of
  **180 days**. For reliability, write large files to `/data` (your persistent
  workspace storage) instead of returning them as run outputs.
</Note>

### Monitoring Runs

Every run you submit with `@run(...).submit()` is tracked in the workspace, so you can follow its progress and read its logs in the UI.

* **Active Runs**: a section at the top of the Virtual Machine side panel that lists runs still in progress, each with a status dot, name, status, and elapsed time. A run waiting on compute shows **Queuing** with the time left before its queue timeout. It refreshes automatically; **See all runs** opens the full list.

* **All Runs**: every run submitted in the workspace, grouped by time and filterable by status (Pending, Queuing, Initializing, Running, Succeeded, Failed, Cancelled). Search by name or run ID, and expand a fan-out run to see its children.
  <img alt="All Runs panel" />

* **Cancel runs in bulk**: tick the checkbox on any active runs in the All Runs list — a floating bar shows how many are selected, with **Clear** and a **Cancel N runs** action. Confirm in the dialog by typing the highlighted phrase. Cancellation is requested for each selected run and can't be undone, so in-progress work may be lost; child runs that have already started are not affected and can be cancelled individually.
  <img alt="Batch cancellation confirmation dialog" />

* **Run Detail**: opens from any run. A fan-out **run graph** shows the run tree (a parent run and its child runs), and **Overview**, **Children**, **Logs**, and **Metrics** tabs cover the run's status, configuration (name, run ID, resource, queue timeout, run/execution timeout, and submitted, started, finished and duration times), child runs, logs, and resource usage.
  <img alt="Run Detail panel" />

* **Metrics tab**: for completed runs, see CPU, memory, and (when the machine has one) GPU utilisation, VRAM, and power draw sampled across the run. Peak headline cards summarise the run at a glance, and each chart carries a fit verdict — *Well-utilised*, *Right-sized*, *Over-provisioned*, *Near limit*, *OOM risk* — so it's obvious whether the machine size matched the workload.
  * **Focus stats on a time window**: drag on any chart to highlight a range. Averages, peaks and verdicts recompute for just that window — useful for excluding warm-up, setup, or a spike you want to inspect. Click elsewhere on the chart or press <kbd>Esc</kbd> to clear the selection and return to full-run stats.
    <img alt="NikaNotebook - Run Metrics" />

## Python Notebook Examples in NikaNotebook

### Spatial Analysis

```python theme={null}
import geopandas as gpd
import pandas as pd
from shapely.geometry import Point, Polygon
from shapely.ops import voronoi_diagram
import folium

# Buffer analysis - Create 1km buffers around points
points_gdf = gpd.read_file('points.geojson')
buffers = points_gdf.geometry.buffer(1000)  # 1000 meters

# Intersection operations - Find overlapping areas
layer1 = gpd.read_file('layer1.geojson')
layer2 = gpd.read_file('layer2.geojson')
overlaps = gpd.overlay(layer1, layer2, how='intersection')

# Distance calculations - Calculate distances between features
points = gpd.read_file('points.geojson')
polygons = gpd.read_file('polygons.geojson')
distances = points.geometry.apply(lambda x: polygons.geometry.distance(x).min())

# Spatial joins - Join attributes based on location
joined = gpd.sjoin(points, polygons, how='left', predicate='within')

# Voronoi diagrams - Create service areas
from scipy.spatial import Voronoi
import numpy as np
coords = np.array([[p.x, p.y] for p in points.geometry])
voronoi = Voronoi(coords)
```

### Statistical Analysis

```python theme={null}
import numpy as np
from scipy import stats
import pandas as pd
from libpysal.weights import Queen
from esda.moran import Moran

# Descriptive statistics for spatial data
stats = spatial_data[['population', 'area']].describe()

# Spatial autocorrelation - Moran's I test
w = Queen.from_dataframe(spatial_data)
morans_i = Moran(spatial_data['value'], w)

# Hot spot analysis - Getis-Ord Gi* statistic
from esda.getisord import G_Local
g_local = G_Local(spatial_data['crime_rate'], w)
hotspots = spatial_data[g_local.p_sim < 0.05]

# Regression analysis with spatial variables
from sklearn.linear_model import LinearRegression
X = spatial_data[['distance_to_center', 'area']]
y = spatial_data['price']
model = LinearRegression().fit(X, y)
```

### Machine Learning

```python theme={null}
from sklearn.cluster import KMeans
from sklearn.ensemble import RandomForestClassifier
from sklearn.preprocessing import StandardScaler
import pandas as pd

# Spatial clustering - Group similar locations
coords = spatial_data[['longitude', 'latitude']].values
kmeans = KMeans(n_clusters=5, random_state=42)
clusters = kmeans.fit_predict(coords)

# Classification - Predict land use from satellite imagery
X = raster_data.reshape(-1, raster_data.shape[-1])
y = training_points['land_use']
rf = RandomForestClassifier(n_estimators=100, random_state=42)
rf.fit(X, y)
land_use_pred = rf.predict(X)

# Time series analysis - Analyze temporal patterns
data['date'] = pd.to_datetime(data['date'])
monthly_trends = data.groupby(data['date'].dt.to_period('M'))['temperature'].mean()

# Anomaly detection - Find unusual spatial patterns
from sklearn.ensemble import IsolationForest
iso_forest = IsolationForest(contamination=0.1, random_state=42)
anomalies = iso_forest.fit_predict(spatial_data[['value1', 'value2']])
```

*There are more real-life examples published by Nika community at [https://planet.nika.eco/en/hub/notebooks](https://planet.nika.eco/en/hub/notebooks)*

## Getting Started

Learn how to perform geospatial analysis with NikaNotebook in 7 easy steps. This comprehensive tutorial will guide you from creating your first notebook to publishing your analysis results.

**[Start the Geospatial Analysis Tutorial →](/guides/tutorials/geospatial-analysis)**


# NikaStudio
Source: https://docs.nikaplanet.com/nika-planet/nika-studio

AI-powered dashboard and visualization builder for data scientists and engineers to illustrate their research outcomes

## Overview

NikaStudio is an AI-powered map dashboard builder designed specifically for data scientists and data engineers who need to illustrate their work outcomes. When you finish your scientific research (remote sensing based or not), NikaStudio helps you create interactive dashboards and visualizations to communicate your findings effectively to managers, stakeholders, or the broader community.

<img alt="NikaStudio Interface" />

<img alt="NikaStudio Page Interface" />

### Flexible Prototyping Tool

After completing scientific research, data scientists and engineers often struggle to effectively communicate their findings. Traditional presentation methods fall short when you need to show:

* Moving buoy data that drifts around on a map
* Interactive visualizations that let stakeholders explore the data
* Custom dashboards that illustrate complex scientific concepts
* Dynamic interfaces that adapt to different research requirements

## Key Features

### AI-Powered Dashboard Generation

* **Natural Language Interface**: Describe your visualization needs in plain English
* **Custom UI Generation**: AI creates tailored interfaces for your specific research requirements
* **Flexible Design**: Unlike rigid drag-and-drop builders, AI adapts to your unique visualization needs
* **Code Quality Control**: Built-in linting and UI consistency checks to minimize AI hallucinations

### Geospatial Data Backend (WIP)

* **Data Hosting Service**: Built-in support for most geospatial formats
* **ETL Integration**: Seamless data conversion through NikaFlow
* **Easy Data Access**: AI can work with your data without complex parsing steps
* **Real-time Visualization**: Live data updates for dynamic research presentations

## Community Examples

### Real Applications Built with NikaStudio

Explore these live examples at [https://planet.nika.eco/en/hub/apps](https://planet.nika.eco/en/hub/apps):

* **Global Deforestation**: Interactive visualization of deforestation patterns worldwide
* **Land Use GFW**: Global Forest Watch land use change analysis dashboard
* **Global Geospatial Companies**: Map of geospatial companies and their locations
* **Earthquake Map**: Real-time earthquake data visualization and analysis
* **COG Overlay Example**: Cloud Optimized GeoTIFF overlay demonstration
* **Thailand Flood Map**: Flood risk and impact visualization for Thailand

## How Our AI Reduces Hallucination

### Focused AI Capabilities

Rather than having AI handle everything, we focus AI on what it does best - UI/UX generation - while handling data parsing and hosting through dedicated services:

* **Data Hosting Service**: Pre-processed geospatial data in formats AI can easily work with (to be built)
* **Code Quality Control**: Built-in linting on each code generation step
* **UI Consistency Checks**: Reinforcement loops to maintain design consistency


# NikaWorker
Source: https://docs.nikaplanet.com/nika-planet/nika-workers

Run and share packaged geoprocessing scripts in the cloud

## Overview

NikaWorkers lets your team run packaged geoprocessing scripts in the cloud directly from the NikaPlanet. Workers are built with [NikaGeoEngine](/nika-geoengine/overview) and pushed to your workspace — once published, anyone on the team can run them without additional setup.

Public workers from the community are also available to browse and run in [Nika Hub](/nika-planet/nika-hub).

## Key Features

### Run Workers from the Browser

* **Input files/folders**: Upload files or folders as inputs directly

<img alt="Worker Inputs" />

* **Machine selection**: Choose a CPU or GPU machine type per job based on your workload

<img alt="Worker Compute Selection" />

### Worker Jobs Monitoring

* **Job history**: See all past jobs for any worker, including machine type, duration, and exit status
* **Logs and Output access**: When a job succeeds, logs and output files are available for viewing or download for 3 days

### Library of Community Workers

Browse and run public workers published by other NIKA users in Nika Hub. Public workers run against your own workspace plan and compute quota.

<img alt="Community Workers" />

### Worker Visibility & Management

* **Team workers** (default): visible and runnable by all members of your workspace
* **Public workers**: discoverable in Nika Hub by any NIKA user
* **Worker Management**
  * Rename workers, change icons, update visibility, and delete specific versions from the Workers page
  * Deleting a worker or a version also removes its associated job history

## Building and Deploying Workers

You can build your own NikaWorker locally with your custom geoprocessing script. Simply use the **[NikaGeoEngine](/nika-geoengine/overview)** to build and [push to NikaPlanet](/guides/custom-geoprocess-deployment/cloud-push) for your team members to use the NikaWorker you've built.

**[Build your first worker →](/guides/custom-geoprocess-deployment/step-by-step)**

**[Push a worker to the cloud →](/guides/custom-geoprocess-deployment/cloud-push)**

**[Collaborate on workers →](/guides/custom-geoprocess-deployment/worker-collaboration)**


# NikaWorkspace
Source: https://docs.nikaplanet.com/nika-planet/nika-workspace

Advanced geospatial data analysis platform with PBs of dataset, directly integrated with AI agent

## Overview

NikaWorkspace is our flagship geospatial data lake platform designed for handling petabytes of spatial data with direct AI agent integration. Built for data scientists, analysts, and developers who need powerful tools for large-scale geospatial processing, visualization, and insights.

<img alt="NikaWorkspace Interface" />

## Key Features

### Petabyte-Scale Data Processing

* **Massive Dataset Support**: Handle petabytes of geospatial data efficiently
* **Optimized Storage**: Advanced database management for large geospatial workloads
* **Distributed Computing**: Parallel processing across multiple nodes
* **Memory Optimization**: Intelligent caching and data streaming

### AI Agent Integration

* **Direct AI Assistance**: Seamless integration with Nika's AI agent for intelligent analysis
* **Natural Language Queries**: Ask questions about your data in plain English
* **Automated Insights**: AI-powered pattern recognition and anomaly detection
* **Smart Recommendations**: Get suggestions for analysis approaches and visualizations

### Advanced Geospatial Analysis

* **Spatial Operations**: Complex spatial analysis and transformations
* **Statistical Analysis**: Comprehensive statistical modeling for spatial data
* **Machine Learning**: Built-in ML algorithms for spatial predictions
* **Real-time Processing**: Live data analysis and streaming capabilities

## Key Features

### Enterprise-Grade Data lake

* **TB-size Storage**: Upload TBs of data to NikaWorkspace as your team repository to collaborate on
* **Real-time Filesystem**: Any changes to the selected folder will be synced in real time between the Web UI and the connected VM
* **High Speed Performance**:

### Data Processing

* **NikaNotebook**: Import data from CSV, GeoJSON, Shapefiles, and more to Nika's collaborative python notebook to run analysis on with GDAL pre-installed for you
* **NikaDBMS**: Perform spatial SQL query with connected database or Nika managed DuckDB instances

### Visualization

* **NikaMap**: Create dynamic, interactive maps with multiple layers
* **Web Preview**: Double click a file to directly preview in a panel without having to download it to preview else where (more extensions will be supported iteratively)
* **NikaDashboard**: Drag your file or database or map to create an interactive dashboard for operation and presentation

### AI-Powered Insights

* **Pattern Recognition**: AI algorithms to identify patterns in spatial data
* **Predictive Analytics**: Machine learning models for spatial predictions
* **Anomaly Detection**: Automatic detection of unusual patterns in data
* **Recommendation Engine**: AI-powered suggestions for data analysis

## Getting Started

### Basic Usage

Create a new NikaWorkspace is as easy as click the + Create button and choose the team to create under. Each workspace is then a logical separation of project storage, compute and workloads.

## Data Sources

NikaWorkspace supports a wide variety of data sources:

* **File Formats**: GeoJSON, Shapefile, KML, CSV, Excel and any format you upload directly
* **Databases**: PostgreSQL/PostGIS, DuckDB, and many other enterprise DBs to come
* **Cloud Storage**: AWS S3, Google Cloud Storage, Azure Blob

## Visualization Options

NikaWorkspace integrates seamlessly with other Nika products:

* **NikaMap**: Create a powerful map that supports both vector, raster and jpeg layers natively
* **NikaDashboard**: Drag and drop to create Tableau-looking operation dashboards with filters on Charts, Maps in NikaWorkspace directly
* **NikaHub**: Share and publish the results of your work to your team and others
* **NikaStudio**: Use current workspace data to quickly build custom map prototypes
* **NikaNotebook**: Use collaborative Python notebooks for advanced geospatial analysis
* **Nika GAIA**: Get intelligent suggestions for your analysis

## Best Practices

1. **Data Preparation**: Always clean and validate your data before analysis
2. **Performance**: Use appropriate data structures for large datasets
3. **Visualization**: Choose the right visualization type for your data
4. **Documentation**: Document your analysis workflow for reproducibility
5. **Version Control**: Use version control for your analysis scripts


# Overview
Source: https://docs.nikaplanet.com/nika-planet/overview

Learn about how NikaPlanet works and how to get started

<img alt="NikaPlanet Interface" />

NikaPlanet is a cloud GIS platform for geospatial data analysis, visualization, and application development. Build powerful maps, dashboards, and data-driven applications with intelligent AI agent.

<div>
  <div>
    <iframe title="Nika Geospatial Highlights" />
  </div>

  <p>
    Watch this video to learn more about Nika's powerful geospatial capabilities
  </p>
</div>

## Get Started

<Steps>
  <Step title="Sign Up">
    Create your account at [planet.nika.eco](https://planet.nika.eco) with your email.
  </Step>

  <Step title="Create Your First Workspace">
    Set up a workspace to organize your geospatial projects and collaborate with your team.
  </Step>

  <Step title="Explore the Guides">
    Follow the [step-by-step guides](/guides/tutorials/getting-started-with-nikaworkspace) to learn how to use each feature.
  </Step>
</Steps>

## Product Offerings

Nika provides 10 powerful tools to transform your geospatial and data analysis workflows.

<Columns>
  <Card title="NikaWorkspace" icon="book-open" href="/nika-planet/nika-workspace">
    Advanced geospatial data analysis platform for with PBs of dataset, directly integrated with AI agent.
  </Card>

  <Card title="NikaNotebook" icon="book" href="/nika-planet/nika-notebook">
    Scalable Jupyter notebook alternative for teams to work together to build and test forefront geospatial workloads with pre-installed GDAL and CUDA.
  </Card>

  <Card title="NikaHub" icon="images" href="/nika-planet/nika-hub">
    Showcase and discover published apps, solutions, maps, and notebooks from our community.
  </Card>

  <Card title="NikaMap" icon="globe" href="/nika-planet/nika-map">
    World's first multi-user editable map that can visualize millions of vector polygons, GBs of raster images, even drone images out of box.
  </Card>

  <Card title="NikaDBMS" icon="database" href="/nika-planet/nika-dbms">
    Advanced geospatial database management system with AI-powered SQL generation and seamless workspace integration.
  </Card>

  <Card title="NikaFlow" icon="water" href="/nika-planet/nika-flow">
    One click deploy python script as serverless function, and use AI agent to create a flow diagram using these functions for data processing engineering.
  </Card>

  <Card title="NikaLabeler" icon="pencil" href="/nika-planet/nika-labeler">
    Annotate, preprocess imaged based datasets team labelling capability. with direct support of GEOTIFF format on top of traditional images.
  </Card>

  <Card title="NikaStudio" icon="computer" href="/nika-planet/nika-studio">
    Build map and dashboard applications with Nika's AI agent with brilliant UI and automated serverless backend.
  </Card>

  <Card title="NikaGeoEngine" icon="code" href="/nika-geoengine/overview">
    One-click deploy Python scripts as geoprocessing functions to multiple platform at once.
  </Card>

  <Card title="NikaDashboard" icon="chart-line" href="/nika-planet/nika-dashboard">
    Drag widget and file to create an operational dashboard that bridges both reliability and performace upon large amount of data to showcase.
  </Card>
</Columns>

## Key Features

Everything you need to create world-class geospatial applications.

<Columns>
  <Card title="AI Agent" icon="brain">
    Nika's intelligent AI assistant that understands your data and helps you build faster.
  </Card>

  <Card title="Maps & Visualization" icon="map">
    Create interactive maps and powerful data visualizations with ease.
  </Card>

  <Card title="Analytical Databases" icon="database">
    Build comprehensive dashboards to monitor and analyze your data.
  </Card>

  <Card title="Geospatial Analysis" icon="location-dot">
    Advanced spatial analysis tools for location-based insights.
  </Card>
</Columns>

## Enterprise Features

Built for organizations that need enterprise-grade geospatial solutions.

<Columns>
  <Card title="Advanced Geoprocessing" icon="tree">
    Built-in functions that match ArcGIS tools, including pansharpening, superresolution, SAM2, acolite, buffer, centroid, and 200+ more geoprocessing operations for professional GIS workflows.
  </Card>

  <Card title="Single Sign-On (SSO)" icon="shield-check">
    Seamless integration with your organization's Active Directory, LDAP, or other identity providers. Enable secure team collaboration with centralized authentication and role-based access control.
  </Card>

  <Card title="Data Migration Support" icon="cloud-arrow-up">
    Dedicated support engineers to help migrate terabytes of data from any cloud service provider (AWS, Azure, GCP) or desktop systems. Get expert assistance for complex data transfers and format conversions.
  </Card>

  <Card title="On-Premise Deployment" icon="server">
    Deploy Nika on your own infrastructure for maximum data sovereignty and compliance. Full control over your geospatial data with enterprise-grade security, backup, and disaster recovery capabilities.
  </Card>
</Columns>


# Authoring Model
Source: https://docs.nikaplanet.com/onlymap/authoring

The OnlyMap manifest: elements, expression accessors, data sources, widgets, interactions, and the validation loop.

## The Manifest

A small set of elements follows one rule. An attribute is the kebab-case form of a deck.gl prop (`radius-units` → `radiusUnits`). A `get-*` attribute is a data-driven accessor.

* **`<om-map>`** — the root element. Give it a height. A custom element is inline by default and collapses to zero size, so a bare map shows nothing. Set `om-map { display: block; height: 100vh }` (with `html, body { height: 100% }`), or put the map in a sized container. Without a height the library fills a sized parent or falls back to a 400px default, and it warns in the console if the map still has no size. It takes `center`, `zoom`, `pitch`, and `bearing`; `max-pitch` and `min-zoom` <sup>0.8.1 / 0.8.3</sup> cap the tilt and floor the zoom-out for a kiosk or embedded map, and are never applied automatically. `crs="EPSG:5070"` <sup>0.10.0</sup> draws the whole map in a real projection — see [Cartographic Maps](#cartographic-maps). `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, `satellite` <sup>0.11.10</sup>, …), a style URL, or `"none"`, and it switches live. `satellite` is keyless imagery of the whole world — EOX's Sentinel-2 cloudless mosaic (2016), commercial use allowed with the credit it shows — detailed to about zoom 13–14; for street-level or recent imagery use the keyed `maptiler-satellite`. The 3D scene is also attributes: `terrain="terrarium"` (or a DEM tile URL) adds elevation, and `lighting="daylight|studio|flat|custom"` with `lighting-*` attributes lights it. Add `validate` for an error panel on the page while you author.
* **`<om-layer>`** — any registered deck.gl layer type, by name. `id` is required. `label` and `color` feed the legend. Under active terrain, a geographic layer drapes onto the surface by default (set `terrain="drape|offset|off"` per layer).
* **`<om-widget>`** — a UI panel: `legend`, `layer-switcher`, `basemap-switcher`, `lighting`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `time-slider`, `vega-lite`, `draw`, `player`, `widgets-toggle` — or your own HTML with a `<script type="om/widget">` block. You can theme every built-in widget with `--om-widget-*` CSS custom properties from plain page CSS. The library manages placement (see below).
* **`<om-overlay>`** — HTML anchored to a coordinate, the current selection, or a feature's geometry. `{{field}}` inserts a value from the picked feature, HTML-escaped by default.
* **`<om-behavior>`** — a declarative interaction: `on="click|hover|drag|load|data-loaded"` runs a named action.
* **`<om-story>` / `<om-step>`** — a storyboard. Each step fires actions on a timeline. The `player` widget plays, pauses, and scrubs it.
* **`<om-fallback>`** — content that shows where scripts do not run (chat-app and email file previews). The library hides it after the map starts.

Always write explicit closing tags (`<om-layer …></om-layer>`). Do not self-close a custom element. Give every layer a stable `id`.

## Widget Placement & Adaptive Layout

`position` puts a widget in one of 8 logical slots: `top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`. The slots flip left-to-right for right-to-left languages. Old corner names such as `top-right` still map to these slots. The library sets the pixel position for you. You do not position the widgets and map controls by hand.

* **Widgets in the same slot stack together** with a shared gap. The `order` attribute sets their sequence in the slot.
* **Small controls next to each other join into one group** (`zoom-controls`, `undo-redo`, `widgets-toggle`). Set `cluster="false"` to keep a control separate.
* **The map attribution goes in `bottom-end`** and the license badge in `bottom-start`. They are part of the slot flow, so they do not cover a widget. The map always shows one attribution, because the license needs it.
* **Folding on narrow maps**: when the map is 640px wide or less, the widgets move into a drawer on each side. Set `fold="never"` to keep a control always visible. Set `widgets-fold="off"` to stop the folding. Change the width limit with `--om-widget-fold-breakpoint`.
* **Dimming under popups**: a slot becomes dim when an open popup covers it. Set `widgets-dim="off"` to stop this. Slots with the attribution or the badge do not dim.
* **Hide all widgets**: `<om-map widgets-hidden>`, the `set-widgets-visible` action, or a `widgets-toggle` widget hide your widgets but keep them in the page. The attribution and the badge stay visible.
* **Turn off management**: set `position="manual"`. The widget becomes a plain block that you style yourself. You can put it outside the map.

You can also set colors (`--om-widget-bg`, `-fg`, `-muted`, `-border`, `-hover-bg`, `-accent`) and spacing (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) with CSS custom properties. For a quick option without CSS, use `<om-map widget-style="gap:10 opacity:0.9">`.

## Accessors Without JavaScript

A `get-*` attribute takes a small, safe expression language. `$field` reads a field from a datum, for any data shape — flat JSON, GeoJSON properties, or Arrow columns:

```html theme={null}
get-position="[$lon, $lat]"
get-radius="$population * 0.001"
get-fill-color="$value > 100 ? [255,0,0] : [0,128,255]"
get-fill-color="scale($depth, sequential, ['#ffffcc','#800026'], domain=[0,700])"
get-text="formatDate($time, 'datetime', 'UTC')"
```

The built-in functions include `scale()`, `colorRamp()`, `clamp()`, `lerp()`, `formatDate()`, and `Math.*`. `scale()` needs an explicit `domain=`, and its kind must match its range: `sequential`/`diverging` interpolate color stops, `linear`/`sqrt`/`log`/`pow` interpolate numbers (sizes, radii, widths), and `threshold` maps either — a mismatch is a compile error rather than an invisible layer. `pow` takes a trailing `exponent=` (`scale($v, pow, [0, 30], domain=[0, 100], exponent=2)`); for a straight line use `linear`. The compiler is an AST whitelist, not an eval, so untrusted, agent-written expressions are safe by design. To use arbitrary JavaScript, you must add an explicit `js` opt-in on the layer.

When the class boundaries should come from the data itself rather than a hand-written `domain=`, use classification attributes instead of an expression: `classify-by="magnitude"` on a layer computes class breaks from the loaded rows and colors the fill. `classify-scale` picks the method — `quantile` (the default, equal counts per class), `equal-interval` (equal spans), or `jenks` (natural breaks) — `classify-classes` sets 2–12 classes (default 5), and `classify-ramp` names one of 14 built-in color ramps (`viridis`, `plasma`, `turbo`, `blues`, `reds`, `ylorrd`, `rdbu`, `spectral`, …). The legend shows the computed class rows automatically. A hand-authored fill color always wins over classification, and `OmMap.validate` names the conflict. A URL-backed layer classifies when its data arrives.

```html theme={null}
<om-layer id="quakes" type="ScatterplotLayer" data="./quakes.csv"
          get-position="[$longitude,$latitude]" radius="6" radius-units="pixels"
          classify-by="mag" classify-scale="jenks" classify-classes="5"
          classify-ramp="viridis"></om-layer>
```

Dashed lines are a single attribute — `dash="[6, 3]"` (or SVG-style `dash="6 3"`, plus optional `dash-justified`) on a line layer (`PathLayer`, `GeoJsonLayer`, `PolygonLayer`, `TripsLayer`). The values are `[dashLength, gapLength]` in the same units as the line width; you do not wire deck.gl's `PathStyleExtension` yourself.

`formatDate(value, style?, timeZone?)` formats epoch-millisecond numbers or ISO strings without exposing JavaScript's `Date` or `Intl` objects. Its styles are `date`, `datetime` (the default), `time`, and `iso`. The default time zone is `UTC`; use `local` for the viewer's zone or an IANA name such as `Asia/Singapore`. Numeric timestamps always mean milliseconds—multiply Unix seconds by 1000 first. Invalid values produce an empty label rather than stopping layer rendering.

## Data Sources

| Source | Manifest |
| - | - |
| JSON / GeoJSON | `data="./points.json"` |
| Inline rows | `<script type="application/json">` child |
| CSV / TSV | `data="./quakes.csv"` — parsed to typed columns |
| Apache Arrow / GeoArrow | `data="./big.arrow"` — points stay columnar; zstd IPC supported |
| Shapefile | `data="./countries.shp"` — `.dbf` attributes joined automatically |
| KML | `data="./tour.kml"` |
| GPX | `data="./hike.gpx"` — waypoints/tracks/routes → features tagged `_gpxKind`; `#waypoints`/`#tracks`/`#routes` selects one part |
| FlatGeobuf | `data="./cities.fgb"` — cloud-native binary vector, whole-file decode |
| GeoParquet | `data="./data.parquet"` (or `.geoparquet`) — cloud-native columnar vector; all-Point files stay columnar, lines/polygons → features; needs `geo` metadata + CRS84/EPSG:4326 (projected CRS errors — reproject first) |
| CityJSON / CityJSONSeq | `data="./tile.city.json"` (or `.city.jsonl`, streamed) — 3D city models; see below |
| WebSocket stream | `data="wss://feed" key="id" flush="250ms"` — upsert-by-key live entities |
| Polled REST snapshot | `data="/api/fleet.json" refresh="5s"` |
| Drawing store | `data="draw:sketch"` + `<om-widget type="draw" target="sketch">` |
| GeoTIFF / COG raster | `<om-layer type="COGLayer" src="./dem.tif" min="0" max="1900" colormap="viridis">` |
| Zarr / GeoZarr raster | `<om-layer type="ZarrLayer" src="./x.zarr" variable="temp" select="time=0" colormap="viridis" min="…" max="…">` — chunked N-D arrays; see below |
| Drone JPEG image | `<om-layer type="ImageOverlay" src="./DJI_0123.jpg" georeference="exif">` — georeferenced photo overlay; see below |

`data` is always an address, never the rows themselves: `data='[{…}]'` draws nothing, and the validator reports it as an error <sup>0.11.9</sup>. Put inline rows in a `<script type="application/json">` child instead. A `data` address that fails to load (a typo, a missing file, a blocked request) is reported in the map's validation panel and diagnostics until it loads <sup>0.11.9</sup>.

You can add custom formats and stream decoders with `OmMap.registerFormat` and `OmMap.registerSource`. For an authenticated endpoint, use `OmMap.configureData({ headers, credentials, fetch })`. Credentials do not belong in the markup.

A raster is the one exception to the `data` attribute. The layer's own reader streams a GeoTIFF as tiles, with HTTP Range requests against a Cloud-Optimized GeoTIFF. It does not parse the raster into rows, so you use `src`. Set `min` and `max` for float or 16-bit data; the default stretch is 0–255. A single-band source takes a bundled `colormap` (`viridis`, `terrain`, `rdbu`, …). A source with 3 or more bands composites as RGB, with no attributes. A restretch or a recolor is a GPU uniform update, so the tiles are not fetched again. The legend shows the colormap ramp automatically.

## Clustering Overlapping Points <sup>new in 0.11.0</sup>

Thousands of points that pile up when zoomed out become count bubbles that split apart as the reader zooms in. It is one attribute on the layer, not a different layer type — the layer keeps its id, its data, its own colours and sizes for the points that stand alone, its popups and its actions:

```html theme={null}
<om-layer id="plants" type="ScatterplotLayer" data="./plants.csv"
          get-position="[$lon, $lat]" color="#2563eb" radius="4" radius-units="pixels"
          cluster="true" cluster-properties="sum:capacity_mw,mode:fuel"
          get-cluster-fill-color="$mode_fuel == 'Hydro' ? '#0ea5e9' : '#64748b'"
          pickable></om-layer>
```

`cluster="true"` works on `ScatterplotLayer`, `GeoJsonLayer` (Point features only — lines and polygons refuse with a structured error) and `IconLayer`. `cluster-radius` (screen pixels, 50), `cluster-max-zoom` (16) and `cluster-min-points` (2) use the names MapLibre users already know.

**Bubbles can say more than a count.** `cluster-properties="op:field,…"` with `sum`, `min`, `max`, `mean`, `mode` (the commonest value) or `first` <sup>0.11.1</sup> (the earliest member's value in data order — any type, a URL or a name) puts `$sum_capacity_mw`, `$mode_fuel`, `$first_photo`, … on every bubble beside `$count`. Style bubbles with `get-cluster-radius`, `get-cluster-fill-color`, `get-cluster-line-color` and `get-cluster-label` — the same expression language as the rest of the map.

**A bubble can carry an image** <sup>new in 0.11.1</sup>. `get-cluster-icon="$first_photo"` draws the image as a circular thumbnail cropped to the bubble and ringed in the bubble's colour — the photo of the first place in the cluster. A name instead of a URL draws a glyph from `cluster-icon-atlas` / `cluster-icon-mapping` (or an `IconLayer`'s own atlas). Images must be same-origin or served with CORS headers, as any image a map draws must; a bubble whose image is still loading, or could not load, stays a plain circle.

**The count as a badge** <sup>new in 0.11.2</sup>. `cluster-label-position="top-right"` (or any edge or corner) moves the number onto the bubble's rim, off a photo; `cluster-label-background="#111827"` draws a pill behind it; `cluster-label-color` and `cluster-label-size` set its colour and size. `cluster-label="false"` hides it. The default is unchanged — centred, white, with a thin dark halo.

**Sizes that survive zoom.** Every bubble also carries `$count_max` and `$<aggregate>_max`, the largest value among all clusters at the *current* zoom. Divide by them and a ramp stays meaningful whether the reader is looking at a continent or a county; the default radius, `scale($count / $count_max, sqrt, [12, 36], domain=[0, 1])`, keeps the biggest bubble at 36 px at every zoom. (`scale()` domains are literals, so this is the way to get a zoom-adaptive ramp.)

**Picks.** A click on a bubble flies, eased, to the zoom where it splits (`cluster-click="none"` opts out; the `expand-cluster` action does it by hand). A bubble pick carries `cluster: true`, `cluster_id`, `count` and the aggregates, so `{{count}}` works in overlays. Give points and bubbles their own cards with `pick="point"` / `pick="cluster"` on `<om-behavior>` — a template cannot branch, and one shared card would open half-empty for bubbles:

```html theme={null}
<om-behavior on="click" layer="plants" pick="point"   action="show-overlay" target="detail"></om-behavior>
<om-behavior on="hover" layer="plants" pick="cluster" action="show-tooltip" template="#bubble-tip"></om-behavior>
```

`map.clusterLeaves(layerId, clusterId)` returns the rows inside a bubble; the legend adds a bubble row under a clustered layer. A widget button can switch clustering on and off at runtime with `set-layer-attribute` (`{ layer, name: "cluster", value: "true" | "false" }`); `ctx.layers[i].cluster` reports the state.

**Bubbles far out, icons close in**: two layers over the same file with complementary `visible-zoom-range`s — the clustered layer on `[0, 12]` with `cluster-max-zoom="11"`, an `IconLayer` on `[12, 24]`. Clustering is not applied on a projected (`crs=`) sheet; the layer renders unclustered with a warning.

## CityJSON 3D City Models

Point `data` at a CityJSON `.city.json` file (or a `.city.jsonl` sequence, which fills the map as it downloads). CityJSON is the format of national building datasets such as 3DBAG, PLATEAU, and swisstopo. There is no CityJSON layer type — the `data` URL decodes to one of two shapes:

* **Extruded footprints** (default): one row per building. Use `type="GeoJsonLayer"` with `extruded` and `get-elevation="$roof_height"`.
* **Per-face surfaces** (`?om-surfaces=1`): one row per face, each at its own real height, so a pitched roof looks pitched. Use `type="SolidPolygonLayer"` with `get-polygon="$polygon"` and `full3d`. Each row carries a `surface_type` (RoofSurface / WallSurface / GroundSurface) and a default `fill_color`, which `get-fill-color` reads automatically — so the buildings render in sensible colors with no styling.

Both modes add derived properties: `roof_height`, `eaves_height`, `ridge_height`, `ground_height`, `roof_area`, `surface_count`, `lod`, and the CityObject ids. Surfaces mode also adds `polygon` and `outline` — bind a companion `type="PathLayer"` with `get-path="$outline"` for visible face edges, because surfaces mode is flat-shaded.

National grids (NL, CH, DE, JP, AT, SG) reproject automatically, axis order included; any other EPSG code fails with an error that names it. The highest LoD is used — pin one with `?om-lod=1.2` (combine as `?om-lod=1.2&om-surfaces=1`). Surfaces mode costs about 30× the rows, so it reaches the free-tier 25,000-row cap at a few hundred buildings; past that the layer renders its first 25,000 rows with an on-map notice.

## Georeferenced Image Overlays

`type="ImageOverlay"` drops a geotagged drone photo onto the map. It is the OnlyMap-owned preprocessing path over deck.gl's `BitmapLayer`: the browser reads the JPEG's EXIF + DJI XMP, computes an axis-aligned WGS84 footprint, bakes the camera yaw and any upside-down roll correction into the pixels, and renders the processed image at those bounds.

```html theme={null}
<om-layer id="survey-photo" type="ImageOverlay"
          src="./DJI_0123.jpg" georeference="exif" opacity="0.8"></om-layer>
```

The JPEG must carry GPS latitude/longitude, a positive `RelativeAltitude`, image dimensions, and gimbal yaw/pitch. Known DJI and Parrot cameras use a bundled sensor database; focal length comes from EXIF and is never guessed. For an unlisted camera, supply the physical sensor size (and focal length if EXIF omits it):

```html theme={null}
<om-layer id="survey-photo" type="ImageOverlay"
          src="./survey.jpg" georeference="exif"
          sensor-width-mm="13.2" sensor-height-mm="8.8" focal-length-mm="8.8"></om-layer>
```

The source follows `OmMap.configureData` for authenticated endpoints, and `map.ready` waits for the image to resolve; a failed image is logged and skipped rather than rendering wrong.

**Persist once, reconstruct cheaply.** For saved or collaborative maps, preprocess a file once with `OmMap.resolveImageOverlay(file)` → `{ image, bounds, metadata }`, upload the returned image, and store its bounds. Reconstructing with explicit `bounds` skips all fetching and EXIF work:

```html theme={null}
<om-layer id="survey-photo" type="ImageOverlay"
          src="./processed/0123.png" bounds="[103.841,1.286,103.845,1.290]"></om-layer>
```

This is a visualization-grade flat-ground estimate (pinhole camera, pitch-adjusted center, axis-aligned bbox), not orthorectification. Terrain relief, lens distortion, and a perspective-correct four-corner footprint are not modeled; large orthomosaics belong in a Cloud-Optimized GeoTIFF via `COGLayer`.

## Zarr / GeoZarr Rasters

`type="ZarrLayer"` renders chunked, N-dimensional array data (climate and weather grids, datacubes) on the GPU. It is built on `@developmentseed/deck.gl-zarr` and zarrita, and loads on first use. Styling — `min`, `max`, `colormap`, `nodata` — and the legend work exactly like `COGLayer`.

```html theme={null}
<om-layer id="temp" type="ZarrLayer"
          src="https://example.com/store.zarr"
          variable="temperature" select="time=0"
          bounds="[-30, 25, 40, 72]" crs="EPSG:4326" spatial-dims="latitude longitude"
          colormap="turbo" min="-35" max="40"></om-layer>
```

* `src` (required) — the `.zarr` store URL. Like `COGLayer`, chunks stream through the layer's own reader; they are never parsed rows.
* `variable` — the array within the store to render.
* `select` — pin every non-spatial dimension: `"time=0"`, `"init_time=0, lead_time=0, ensemble_member=0"`. The two spatial dimensions are handled for you; a 2-D array needs no `select`. Changing `select` re-slices without reopening the store, so you can animate a time axis by rewriting the attribute.
* A **GeoZarr**-compliant store georeferences itself. A **plain Zarr** needs manual `bounds="[west,south,east,north]"`, `crs="EPSG:4326"`, and `spatial-dims="<yName> <xName>"` (the two spatial dimension names).

**External / remote stores.** `src` can be any absolute URL, and a remote store needs no server setup — a static host (S3, GCS, a CDN, any object store) serves Zarr's chunk files natively. Two current constraints: the store is fetched directly from the browser, so it must be **CORS-enabled** (`Access-Control-Allow-Origin`); and it must be **public** — authenticated stores that need a header or token are not yet supported (the layer does not route through `OmMap.configureData`). Also mind the store's chunking: a dataset chunked coarsely over its non-spatial dimensions (for example, every forecast step in one chunk) decodes far more than the single pinned frame needs.

## BIM / IFC Models

`type="BIMLayer"` loads an `.ifc` file entirely in the browser — no pre-conversion, no server. The web-ifc WASM parser is fetched from a CDN on first use (integrity-pinned, never bundled), and the model renders as 3D Tiles with a companion edge-outline layer.

```html theme={null}
<om-layer id="clinic" type="BIMLayer" src="./Clinic_Architectural.ifc"
          pick-features pickable
          site-origin="[-71.059776, 42.358429]" site-heading="32"></om-layer>
```

For interactive loading, `<om-widget type="ifc-loader">` is a drop zone that parses the file and builds the layer pair for you; add `federate` and one drop zone accepts several discipline models into a co-registered scene (the first model fixes the shared origin), each with its own visibility toggle and remove button.

**Per-element picking and styling** works on any 3D Tiles layer, not just IFC. Add `pick-features` to a `Tile3DLayer` (or `BIMLayer`) and picks resolve individual elements — a wall, a window, one IFC product — with their `EXT_structural_metadata` properties. On top of that, everything is attributes:

* **Isolate / hide / ghost**: `feature-filter-field="component"` plus `isolate-features='["Wall"]'` / `hide-features` / `ghost-features` (JSON arrays of values). Isolate is exclusive scope; hiding is a shader discard, so a hidden element also stops blocking picks.
* **Color by property**: `feature-color-by="material"` (categorical, colour-blind-safe palette; override with `feature-palette`) or `feature-color-scale="netVolume"` (graduated). `feature-color-strength` below 1 tints instead of replacing. Setting neither is the default and renders the model's own IFC surface colours.
* Being attributes, all of this is undoable and story-steppable.

**Widgets**: `ifc-browser` groups the model by any property field with per-value isolate/hide/ghost buttons; `feature-inspector` shows the picked element's properties; `ifc-clash` flags interpenetrating element pairs across two co-registered models and flies to each clash.

**Placement**: `site-origin="[lng, lat]"`, `site-heading` (degrees clockwise from north), and `site-scale` position the model — they override what the file declares. A model with real georeferencing (`IfcMapConversion`) places itself, but do not trust a declared position without looking: most IFC2x3 exports carry an authoring-tool default location that is indistinguishable from a survey.

**Terrain is yours to author.** The library never writes scene attributes as a side effect: a model that resolves real-world elevation loading on a map with no `terrain` attribute raises a validation **error** (any value satisfies it, including an explicit `terrain="off"`), and a georeferenced model landing on a map with no basemap and no terrain raises a "no spatial context" warning — instead of the map switching either on for you.

## Cutting, Exporting, and Picking a 3D Scene

These tools operate on whatever 3D content is already loaded — 3D Tiles, `BIMLayer` models, extruded vector geometry alike — and they compose: cut a box open, outline what is inside, export it.

**Clip box.** An axis-aligned 3D box cuts the whole scene. It is map-level scene state, so it is undoable and story-steppable like `terrain` and `lighting`:

```html theme={null}
<om-map terrain="mapterhorn"
        clip-box-min="[6.145, 46.201, 380]"
        clip-box-max="[6.149, 46.204, 440]">
  <om-widget type="clip-box"></om-widget>
</om-map>
```

Every layer is clipped by default; `clip="off"` on an `<om-layer>` opts one out (a basemap, usually). `clip-box-invert` shows what is *outside* the box instead of inside. `clip-box-highlight` dims the clipped-away geometry rather than discarding it, which makes it a non-destructive preview. The `clip-box` widget renders the box as a draggable cuboid, and its "Show face gizmos" toggle adds a handle on each of the six faces so you can resize by dragging. The `set-clip-box` action takes `{min, max, invert?, highlight?}`, or `{clear: true}` to remove it. v1 is axis-aligned only.

**Region export.** Outline a footprint with the draw widget, then export the 3D content inside it:

```html theme={null}
<om-widget type="draw" export-3d></om-widget>          <!-- GLB (default) -->
<om-widget type="draw" export-3d="b3dm"></om-widget>   <!-- b3dm, for Cesium and 3D Tiles pipelines -->
```

Every triangle of every loaded, *visible* 3D Tiles or BIM layer inside the ring is clipped exactly and downloaded. Positions are re-framed to a local coordinate frame at the footprint's own centroid, so the file opens correctly in Blender or three.js without ECEF-scale support. Each triangle carries its source colour as vertex colours; there are no textures, because BIM and IFC materials are flat colours. A layer hidden with `visible="false"` is skipped. The clip and pack run synchronously, which is fine at single-model scale — keep footprints to the region you actually want.

**Depth picking.** An ordinary `pickable` layer resolves a click against the ground plane, so clicking a building face reports the point *behind* it. `pickable="3d"` opts the layer into the depth-pick pass instead:

```html theme={null}
<om-layer id="city" type="Tile3DLayer" tileset="…/tileset.json" pickable="3d"></om-layer>
```

The resolved coordinate then carries a real elevation, available as `{{z}}` in an `<om-overlay>` or `show-tooltip` template and as `ctx.selection.coordinate` in a widget script. `terrain` sets this on itself. `{{z}}` is **absent, not `0`**, when no layer ran the depth pass for that pick, so a missing elevation never reads as sea level.

**Snapping.** `<om-map snap="vertex edge midpoint" snap-tolerance="12">` refines a click or hover to the nearest vertex, edge, or edge midpoint of whichever feature is already under the cursor — including a `BIMLayer`'s real wall corners, converted from the model's local mesh coordinates automatically. Vertex beats midpoint beats edge when more than one is in range, and holding Space places a point without snapping. `snap="off"` opts a layer out. Snapping is horizontal: a snapped vertex takes the matched feature's position, and drawn geometry still drapes onto terrain normally.

## Measuring, Including Cut/Fill Volume

Distance and area work on any map. `volume` mode reads cut and fill against the map's elevation surface, so it needs `terrain` on `<om-map>` — validation warns when you author it without one.

```html theme={null}
<om-map terrain="mapterhorn">
  <om-widget type="measure" modes="distance area volume"
             units="metric" base-surface="custom"
             density="1.8" swell="1.25" shrink="0.9" profile></om-widget>
  <om-widget type="dynamic-chart" on="om-measure" series-field="profileSeries" width="320"></om-widget>
</om-map>
```

Click to place points; distance and area read out live. In `volume` mode you outline a footprint, close it, and drag the elevation gizmo. The result is a **real per-cell integration** of the terrain DEM against a base surface — not a flat approximation — so one footprint on sloping ground reports cut *and* fill simultaneously, each with a published ± error quoted against the DEM's own ground-sample distance rather than the grid spacing. The readout also carries the cell size and the fraction of cells with no DEM data, so you can tell when to distrust a number.

`base-surface` picks what the terrain is measured against:

| Value | Base surface |
| - | - |
| `custom` (default) | The draggable gizmo's target plane. By default it grades *parallel* to the terrain, so volume is depth × area and reads exactly zero at rest; the widget's "flat target plane" toggle switches it to one level plane, which produces mixed cut and fill on a slope. |
| `triangulated` | A TIN over the footprint's own boundary elevations — the usual choice for a stockpile, since it follows the pile's toe all the way round. |
| `plane` | A least-squares plane fit through the boundary elevations. |
| `lowest` / `highest` / `average` | A level plane at the boundary's minimum, maximum, or mean elevation. |

Switching strategies re-integrates against the already-fetched tiles, with no new network requests.

Reporting factors are separate attributes, and they never change the raw geometric volumes — those always answer "does this reach target elevation":

* `density` (t/m³ metric, lb/yd³ imperial) adds tonnage, computed from the raw volume, because swell and shrink change volume through air voids rather than mass.
* `swell` and `shrink` populate *separate* adjusted figures on the standard Bank/Loose/Compacted convention: adjusted cut = raw × swell, adjusted fill = raw ÷ shrink.
* `deadband` (m³) zeroes a figure below the threshold, filtering drag noise near zero.
* `profile` samples an elevation profile around the footprint's own perimeter and puts it on the `om-measure` event for a chart to plot — there is no second line to draw.

Everything is dispatched on the `om-measure` DOM event, so you can render your own readout instead of the widget's. The `dynamic-chart` widget above is deliberately generic: it reads `event.detail[seriesField]` on every matching event and redraws, and a feature "freezes" the chart for free by simply omitting that field on a later event.

## Interactions and State

Every built-in action uses one payload contract, across every trigger: behaviors, widget `data-emit` buttons, `ctx.emit`, and story steps. The actions include `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `set-layer-attribute` <sup>0.11.0</sup> (write any layer attribute at runtime — the switch behind a widget button), `expand-cluster` <sup>0.11.0</sup>, `highlight-feature`, `zoom-to-feature`, `filter-layer`, `fly-to`, `set-basemap`, `set-lighting`, `set-terrain`, `set-clip-box`, `export-region-3d`, the `measure-*` family (`measure-mode`, `measure-units`, `measure-clear`, `measure-config`, `measure-flat-target-plane`), `undo`, and `redo`. Add your own with `OmMap.registerAction`.

A card that carries an image or a link — `<img src="{{photo}}">` — goes inside a `<template>` child of the `<om-overlay>` <sup>0.11.1</sup>: a template is inert when the page loads, so the browser never requests the literal `{{photo}}`; tokens stay blank until a pick fills them, and tooltips behave the same way.

A tooltip opened by a click closes when the selection clears — a click on empty map, or a pick that moves off every feature <sup>0.10.2</sup>. A popup carrying its own `data-emit` controls keeps pointer events and stays until it is dismissed. Nothing needs a hand-wired `hide-tooltip`. A popup that a click behavior opens with `show-overlay` stays open while the pointer moves on <sup>0.11.8</sup>: hovering another feature neither moves nor closes it, and the next click moves it to that feature or, on empty map, closes it. Before 0.11.8 this needed `selection-type="click"` on the `<om-overlay>`; that attribute still works and still wins.

GPU filtering is declarative (`filter-field="magnitude" filter-range="[4,10]"`). It updates live from the `filter` widget, and the widget statistics match what the map renders. For an epoch-millisecond field, the built-in widget can show readable labels:

```html theme={null}
<om-layer id="quakes" type="GeoJsonLayer" data="./quakes.geojson"
          filter-field="time" filter-range="[1782889284760,1785480717910]"></om-layer>
<om-widget type="filter" layer="quakes" field="time"
           format="date" date-style="datetime" time-zone="UTC"></om-widget>
```

`format` is `number` (the default) or `date`; `date-style` and `time-zone` use the same contract as `formatDate()`. The manifest is the state, so all of this is undoable. Scene state (basemap, lighting, terrain) is attributes on `<om-map>`, so a story step can change it, and a scrub restores it exactly.

A layer can filter on several fields at once. `filter-fields` takes up to 4 numeric `{field, range}` dimensions as a JSON array, and `filter-category-fields` takes up to 4 categorical `{field, categories}` keep-lists — a row must pass every active dimension of both kinds. Place one `filter` widget per field: the widget renders a range slider for a numeric field and a checkbox list (with per-value counts) for a categorical one, and each widget moves only its own dimension. `ctx.stats` and the built-in statistics respect whichever filters are active.

For temporal playback, the `time-slider` widget animates a filter over a time field instead of making you scrub it by hand:

```html theme={null}
<om-widget type="time-slider" layer="quakes" field="time" duration="20s" loop
           format="date" date-style="datetime" time-zone="UTC"></om-widget>
```

Play sweeps the layer's filter from the field's minimum to its maximum over `duration` of wall time — cumulative by default, or a sliding interval with `window="86400000"` (in field units, here one day of milliseconds). It drives the ordinary `filter-layer` action, so `ctx.stats`, the statistics readouts, and undo stay coherent with what the map renders, and any external filter edit (a story step, another widget, a script) moves the thumb rather than fighting it. `format`/`date-style`/`time-zone` label the current value with the same contract as the `filter` widget.

## Routes and Live Tracking

`<om-layer type="Route">` draws a styled A-to-B route — casing, colored line, and origin/destination markers — and `<om-layer type="Tracking">` renders one moving entity that glides between position updates. Both expand into ordinary deck.gl layers, so `pickable`, `opacity`, and the other layer attributes work unchanged.

```html theme={null}
<!-- You already have the path: resolves instantly, no network -->
<om-layer id="trip" type="Route" follow="fit-route"
          geometry='{"type":"LineString","coordinates":[[-122.42,37.77],[-122.41,37.79]]}'></om-layer>

<!-- A routing engine computes the path -->
<om-layer id="trip" type="Route" follow="fit-route" provider="osrm"
          origin="[-122.4194,37.7749]" destination="[-122.4130,37.7805]"></om-layer>

<!-- A moving marker over a live feed -->
<om-layer id="rider" type="Tracking" get-position="[$lng,$lat]"
          follow="follow" interpolate-ms="1200"
          data="wss://feed.example/rider" source="my-decoder" key="id"></om-layer>
```

A `RoutingProvider` is a small adapter you register once — `OmMap.registerRoutingProvider(name, { computeRoute })` — and reference by name in the `provider` attribute. A \~15-line adapter covers OSRM's keyless public demo server (it returns GeoJSON natively), and the same shape works for Mapbox Directions, OpenRouteService, GraphHopper, or a self-hosted engine. Re-routing is attribute writes: change `origin` or `destination` (from a click handler, a story step, an undo) and the layer re-resolves, aborting any in-flight request.

The Tracking layer's position feed is ordinary layer `data` — a WebSocket stream with a decoder, a polled REST endpoint, or inline JSON your script replaces. There is no separate tracking subscription API. `bearing-field` names the data field that rotates the marker, `interpolate-ms` sets how long the marker glides between two fixes instead of jumping, and `follow="follow"` eases the camera along with it. `icon="arrow|car|motorcycle"` picks the marker's shape (default arrow) — every shape points nose-up and is baked in the layer's `color`, so bearing rotation and per-entity tinting work identically; `size` scales it. One entity per layer: for a fleet, run one `Tracking` layer per vehicle (each glides independently), and beyond a handful drop down to a plain `IconLayer` over a keyed stream.

Link a Route to a Tracking layer with `progress-from="<tracking-layer-id>"` and the route splits at the marker's live position — the split advances per frame with the glide, projected onto the route line, since real GPS fixes sit slightly off it. `tail` picks how the traveled portion renders: `tail="none"` shows only current position → destination (the client view — a customer waiting on a delivery), `tail="dim"` darkens the traveled portion (the operator view; `tail-color` overrides the automatic darkening), and `tail="full"` (the default) keeps today's single-color line.

Whenever a Route resolves — direct `geometry` or a provider round-trip alike — the map dispatches `om-route-resolved`: `detail = { layerId, route }`, where `route` carries the normalized `geometry`, `distanceMeters`, `durationSec`, `legs`, and the fitted `bounds`. That is how a page reads a provider-computed route (an ETA readout, a turn list) without re-fetching it.

## Travel-Map Animations and On-Map Annotations

The classic animated-travel-map moves are native story verbs. A `trace` step draws a line progressively; add `follow` to lock the camera to the drawing tip, and `easing="linear|ease-in|ease-out|ease-in-out"` to shape the clock. Per-feature tracing (`trace` with `feature-id`) draws a polygon's outline at uniform speed — every part of a MultiPolygon, largest first — then reveals its fill. For labels on the shapes themselves (no popup card), put `anchor="surface"` on a `TextLayer` over polygon data: each row's text anchors inside its own polygon, with concave shapes handled; pair with `font-settings='{"sdf":true}'` and `outline-width`/`outline-color` for a legible halo.

## Driving Stories From External Video Renderers

Frameworks that own the clock (Remotion-class) render frame-by-frame: mark the map `data-om-recording` — the determinism switch (camera moves land instantly, effects snap to their end state, transitions and gesture interruption turn off, `snapshot()` returns byte-stable captures) — then per frame call `story.seek(t, { interpolateCamera: true })` (mid-fly-to seeks land on the real flight arc), `await mapEl.whenSettled()` (resolves when the map has genuinely finished drawing; also available on `MapController`), and capture. The same frame renders byte-identically across processes and orderings, which is what licenses parallel rendering. `npx onlymapjs record` remains the built-in one-command path.

## Sharp Flybys Over 3D Tiles, and Recording Them

Story fly-bys over 3D tiles (photogrammetry, BIM, Google Photorealistic) normally show tiles popping in or refining from blurry to sharp as the camera moves — tiles only start downloading when the camera needs them. Because a story's camera route is known before it plays, OnlyMapJS can fix this three ways, in increasing strength:

* **`<om-story warm-tiles>`** pre-loads every 3D tileset's tiles along the story's fly-to route in the background as soon as the page loads. Manual form: the `warm-tiles` action; the `om-tiles-warmed` event on `<om-map>` announces completion. For long routes, keep more tiles cached with `load-options='{"tileset":{"maximumMemoryUsage":512}}'` on the tiles layer.
* **`<om-story paced>`** goes further: playback holds each frame until the tiles under the camera are fully sharp before advancing. The flight takes longer, but no frame ever shows blurry tiles. `paced-max-hold` caps how long one frame may wait (default 10s; `"none"` waits unconditionally); each frame reports its wait through the `om-paced-tick` event. Combine with `warm-tiles` to shorten the holds.
* **`npx onlymapjs record map.html --out flyby.mp4`** plays the story load-paced in headless Chromium and writes a video in which every frame is sharp — widgets, overlays, and attribution included. Uses ffmpeg when installed (otherwise you get PNG frames plus the exact command); `--gpu` is \~3× faster on heavy scenes; `--fps`, `--width/--height/--scale`, `--story`, `--max-hold` tune the take. Custom pipelines hook the same seam with `storyEl.setPacedCapture(...)` — the story waits for your capture, so frames can never tear.

The full guide, including per-engine adapter notes, is [docs/routing.md](https://github.com/NikaGeospatial/onlymapjs/blob/main/docs/routing.md) in the package.

To wire your own logic, read the DOM events on `<om-map>`:

* `om-view-changed` fires when the camera settles. `detail` carries the camera and an `origin` of `"user"` or `"programmatic"`. Use `origin` to suppress echoes during state sync.
* `om-map-point` fires on each click or hover. `detail = {coordinate, kind}` — `coordinate` is `[lng, lat]` (or `null` off the map), and `kind` is `"click"` or `"hover"`. It fires on every click and hover, including empty-map clicks a pick discards. This is how you build a tool the `draw` widget does not cover: a distance measurer, a drop-a-pin, a custom rectangle or circle area. Read the coordinate from this event. Do not read deck.gl internals — the map does not expose those. To turn a screen point into a coordinate yourself, call `mapEl.unproject([x, y])` <sup>0.11.5</sup>.
* `om-tileset-load` gives a `Tile3DLayer`'s live deck `Tileset3D`. `detail = {layerId, tileset}`. Use it for a tool such as region export.
* `om-route-resolved` fires when a `Route` layer's path is ready. `detail = {layerId, route}` with the normalized geometry, distance, duration, legs, and bounds — see Routes and Live Tracking above.
* `om-measure` carries the measure widget's whole readout. `detail` has the mode and units, `totalMeters`/`areaMeters2`/`perimeterMeters`, and in volume mode `cutMeters3`/`fillMeters3`/`netMeters3`/`totalMeters3` plus `cellSizeM`, `gsdM`, `cutErrorM3`/`fillErrorM3` and `nodataFraction` (the error model the numbers were computed under), the material-adjusted `cutAdjustedMeters3`/`fillAdjustedMeters3` and `cutMassKg`/`fillMassKg`, and `profileSeries`. A `stale` flag marks the brief window after a footprint commits but before its terrain sample resolves, so you never mistake a previous shape's numbers for the current ones.

To ask the map what is under a point instead of waiting for a click, use the picking methods <sup>0.11.5</sup>. `mapEl.pickAt([x, y])` returns the feature at a screen point, searching 4 pixels around it, or `null`. `mapEl.pickRect({x, y, width, height})` returns every feature inside a box, front to back, up to 100. Both take a `layers` list to narrow the search. They are queries: they do not change the selection, fire `om-map-point`, or run your behaviors. Only `pickable` layers answer. For a tool that must reach every layer, such as a picker that tells an assistant which feature the user means, set `mapEl.pickMode = "all"` while the tool is open and back to `"authored"` when it closes. It is a property, not an attribute, so nothing is written into the map. While it is on, ordinary hover and click see every layer too.

A tool can read the rest of the map without changing it either <sup>0.11.7</sup>. Set `mapEl.diagnostics = true` and the map reports its problems, each with a suggested fix, as `om-validation-error` events after every change. No error panel appears and nothing is written into the page; `mapEl.getDiagnostics()` returns the latest report. Use this rather than adding `validate` from a tool, which edits the author's map. Legend and layer-switcher rows carry `data-layer="<layer id>"`, so a click on a row can be traced to its layer. An overlay's `templateSource` returns its template as written, with the `{{fields}}` it shows.

To mirror state instead of reading events, use `getStore(token)`. It gives a `{subscribe, getSnapshot}` store for each token: `viewport`, `selection`, `layers`, and `data:<id>`. The store works directly with `useSyncExternalStore`, MobX, Redux, or Zustand.

## Cartographic Maps

A print-like map — an atlas plate, a poster, a regional reference sheet, anything a
cartograph frame will show — wants different defaults from a slippy map. Everything
below is a layer or an attribute on the map itself, so a sheet's frame inherits all of
it.

### A real projection <sup>new in 0.10.0</sup>

```html theme={null}
<om-map crs="EPSG:5070" basemap="none" reference-scale="1:6500000"
        center="[-96, 38]" zoom="3.2">
```

`crs` draws the whole map in that projection's plane: parallels curve, an equal-area map
is genuinely equal-area, and a national-grid sheet is drawn in its own grid rather than
stretched out of Web Mercator. Albers (`EPSG:5070`), the UTM zones, British National
Grid, Swiss LV95, Lambert 93, RD New and `EPSG:4326` are built in; anything else takes a
`+proj=` string via `OmMap.registerCrs()`. The authored camera **stays geographic** —
`center` is lng/lat and `zoom` is unchanged — so stories and `seek()` keep working.

A projected map cannot carry these, and each is a validation error with a fix rather
than a silent no-op:

| Limit | Why | Instead |
| - | - | - |
| A MapLibre basemap | a second renderer with its own Mercator camera | `basemap="none"` |
| `terrain` | the 3D surface and its tiles are Mercator throughout | drop it, or stay Mercator |
| `pitch` / `bearing` | the projected view is planimetric | rotate the *frame* in the sheet |
| H3 / S2 / geohash / quadkey layers | deck builds their geometry from a token, inside the layer | convert the cells to polygons |
| Changing `crs` after boot | re-ingesting is a remount | author two maps |

**Relief works** on a projected map, by both routes below. `sun-datum="sheet"` keeps the
apparent light constant across the plate, the way printed relief atlases do — true north
rotates by 34° across a map of the United States, and light that turned with it would
read as a printing fault. `sun-datum="geographic"` follows true north instead.

`reference-scale="1:6500000"` declares the scale the sheet is drawn at, so millimetre
sizes elsewhere on the map — transform tolerances, buffer widths — resolve to ground
units. Without it, any `mm` value is a validation error naming this attribute.

### Shaded relief <sup>new in 0.9.1</sup>

```html theme={null}
<om-layer type="HillshadeLayer" src="terrarium" sun-azimuth="315 45" z-factor="2"></om-layer>
```

Relief is a **layer**, not `terrain=`: it draws shaded terrain on a flat map at any
angle, sits under your data in document order, is captured by `snapshot()`, and is
treated by a print finish. `src="terrarium"` uses keyless global elevation tiles (the
attribute is required even so). Or shade the elevation raster you already have —
`shading="hillshade"` on a `COGLayer` or `ZarrLayer` turns your own DEM into relief that
shows *through* its `colormap`, so a hypsometric map with shaded terrain is one layer.

The sun is a list: `sun-azimuth="315 45 135"` blends several light directions — the
difference between flat single-light web-map shading and the Swiss-style relief of a
printed atlas. `sun-weight`, `sun-elevation` and `z-factor` tune it, and all are instant.
Tile edges are seamless, relief keeps its true shape at every latitude, and a
high-resolution export gets genuinely sharper relief rather than an enlarged screen.

Two things the validator will tell you: a terrain source in a lossy image format
invents plausible-but-wrong heights and is flagged once; and `identify="off"` does not
free a raster's memory while `shading="hillshade"` is set, because seamless relief needs
neighbouring pixels to hand.

<Note>
  On a sheet, put the relief **under** a translucent land wash — `get-fill-color="[226,206,166,88]"`,
  alpha around 80–90 — not an opaque one. Relief under alpha 255 is still computed, still
  costs the render, and none of it reaches the reader. It is the single most common way a
  plate comes out flat.
</Note>

### Geometry your data doesn't contain <sup>new in 0.10.0</sup>

`<om-transform>` inside a layer rewrites its geometry at ingest:

```html theme={null}
<om-layer id="coast" type="GeoJsonLayer" data="./land.geojson" get-fill-color="[0,0,0,0]"
          get-line-color="[72,56,40,120]">
  <om-transform type="buffer" distance="0.9mm" repeat="5" fade></om-transform>
</om-layer>
```

* `simplify tolerance="0.15mm"` thins a dense coastline to what the scale can print.
* `smooth iterations="1"` — one Chaikin pass removes the chain-of-straight-segments look
  that marks a map as a web map.
* `dot-density` scatters points for a population figure.
* `buffer` draws bands around a shape; with `repeat` and `fade` it is the engraved
  shoreline vignette of old charts. Five bands cost what one costs and cannot tangle. It is
  an **ornament**, not a measurement — for a setback someone will act on, use PostGIS.
* `contour src="terrarium" bounds="[w,s,e,n]" interval="100m"` marches real isolines off
  a DEM (not deck's `ContourLayer`, which contours point density). Its extent is
  *declared*, because a transform runs once at ingest, not per camera. Each line carries
  `elevation` and `index` (true every fifth line — draw those heavier).

Millimetre knobs need `reference-scale` on the map; ground units (`50m`) never do.
Polygons only for `buffer`; lines and polygons for `simplify`/`smooth`; points pass
through untouched and the validator says so.

### Labels that follow the line they name <sup>new in 0.10.0</sup>

```html theme={null}
<om-layer type="TextOnPathLayer" data="./rivers.geojson"
          get-text="$name" get-path="d.geometry.coordinates"
          letter-spacing="1.5" font-family="serif"></om-layer>
```

The oldest label convention there is, and one no web-map library ships: a river's name
runs along the river. Both accessors are required. **On GeoJSON, `get-path` is
`d.geometry.coordinates`** — a `$field` compiles to `properties.<field>`, so
`get-path="$geometry"` hands the layer an object and every label silently vanishes
(a validation error since 0.10.3). `$path` is right only for flat rows that carry the
coordinate list themselves.

The name reads the right way round whichever direction the line was drawn, and one too
long for its line is left off rather than squeezed. Since 0.10.5 a label slides to the
straightest stretch it fits on (`placement="auto"`, the default; `start`/`middle`/`end`
pin it), `max-angle` sets how sharply a name may bend between neighbouring letters
(45°, MapLibre's figure), and `orientation="chord"` lays the whole name straight along
the stretch it covers for data too jagged to follow. `letter-spacing` tracks a name out —
the convention for rivers and ranges rather than a flourish. Add `pickable` to make labels
clickable <sup>0.11.6</sup>: a click reports the feature the label names, so a `{{name}}` popup
shows that river's fields.

### Editable vector export <sup>new in 0.10.0</sup>

```js theme={null}
const svg = await map.snapshot({ format: "svg" });          // SVG text
const file = await map.snapshot({ format: "svg", as: "blob" });
```

Polygons and paths become `<path>`, labels become real `<text>` after a deterministic
decluttering pass, and a curved label becomes one `<textPath>` — artwork you can open in
Illustrator. Relief, imagery and 3D come out as placed `<image>` bands; consecutive
raster layers merge into one band, a vector layer between them keeps them apart. A map
carrying an `<om-effect>` print finish exports as a single raster band at `effectDpi`
(default 600), because the finish treats the whole frame — tell the user that before
they build a sheet around both. In a cartograph, `frame.freeze({ format: "svg" })` does
the same to a frame in place.

## Print Finishes <sup>new in 0.9.0</sup>

```html theme={null}
<om-map basemap="none">
  <om-effect preset="vintage"></om-effect>
  …
</om-map>
```

`<om-effect>` treats the rendered frame — warm paper and ink, a pressed edge, paper
tooth, a soft vignette. Seven looks ship: `vintage`, `engraved`, `night`, `blueprint`,
`riso`, `newsprint` and `muted` (which only calms a busy sheet, with no texture). Presets
assume the map beneath is styled to suit them.

Every look is built from named operations you can write yourself, composed in document
order — `tint`, `levels`, `saturation`, `posterize`, `vignette`, `grain`, `edges`, `blur`,
`sharpen`, `halftone`:

```html theme={null}
<om-effect op="grain" amount="0.07" size="0.12mm"></om-effect>
```

Sizes are **millimetres**, so the grain and ink on a 600 dpi export are the same
physical texture you tuned on screen rather than four times finer. To start from a preset
and change one thing, override a single knob on it. An `<om-effect>` carrying an inline
`<script type="application/json">` shader module is handed to deck.gl untouched, so
anything deck's own `PostProcessEffect` can do is available from the document.

`set-effect` switches the finish live from a behavior or a widget button, and because it
writes the document, undo/redo see it. `<om-widget type="effects">` <sup>0.9.1</sup>
lists every preset plus Off and holds no state of its own, so a hand edit or an undo
moves the radio too.

<Note>
  An effect treats deck's own frame. With a MapLibre basemap, which is composited
  underneath, the data layers are treated and the basemap is not — the validator says so,
  with the fix: `basemap="none"`. Transparent areas stay transparent (since 0.9.1), and
  the `newsprint` screen is sized to read on screen — take `halftone-cell` back down when
  exporting at 300 dpi.
</Note>

## Legends That Read the Styling

The legend widget builds each entry from the layer's real symbology. Write the standard expression shapes, and the legend describes itself:

* `scale($f, sequential|diverging, […], domain=[a,b])` → a gradient ramp with the domain ends labeled.
* `scale($f, threshold, […], domain=[b1, b2])` → discrete class rows (`< b1`, `b1 – b2`, `≥ b2`).
* `classify-by="mag" classify-scale="jenks"` → the same discrete class rows, with the boundaries the classification computed from the data.
* `$type == 'a' ? '#c1' : $type == 'b' ? '#c2' : '#fallback'` → a category palette with an "other" row.
* A `COGLayer` with `colormap` and `min`/`max` → the colormap ramp over the rescale window.

A flat colour — `get-fill-color="[226,206,166,92]"`, a hex literal, `rgb()` — shows as that colour <sup>0.10.5</sup>, read in the order the eye sees it: a transparent fill defers to the stroke. For anything else, the legend shows the layer's single `color` swatch. The legend updates live when the styling changes. When an agent rewrites a color expression, the legend and the map refresh in the same frame.

## Exports

`map.snapshot()` (also on the React controller) returns a PNG data URL. Pass `{ type: "blob" }` to get a `Blob` instead. It captures the basemap and the WebGL canvas together, at device pixels. It does not capture DOM widgets or overlays. Your export pipeline must render the provider attribution itself. `{ format: "svg" }` returns editable vector instead — see [Editable vector export](#editable-vector-export).

`map.hasDrawableContent()` <sup>0.10.6</sup> answers whether the map drew anything at all — a basemap, rows on any layer, a tile template — which is how a host tells "finished loading" from "finished loading and there is nothing there". `whenSettled()` resolves either way, by design.

## Validate, Then Trust

Three authoring mistakes that used to pass validation and draw nothing are now caught <sup>0.10.3</sup>: `get-path="$geometry"` on GeoJSON (an error when the data is inline, a warning when it is a URL), `line-width-units="millimeters"` (only `meters`, `pixels`, `common` exist), and a widget `type` that does not exist — the error lists the real ones, and points out that a north arrow, scale bar or graticule on a print sheet is a cartograph element, not a widget.

Use this authoring loop:

1. Write the manifest, or edit the live DOM. Changes reconcile automatically.
2. `OmMap.validate(html)` returns structured errors, each with a `fix` string.
3. `OmMap.snapshotIR(html)` returns resolved layer descriptors for snapshot tests.
4. `mountForTest(html)` runs headless behavioral tests. A synthetic pick uses the same selection path as a real GPU pick.
5. `npx @nika-js/onlymap check-layout <manifest.html>` checks the real widget layout in headless Chromium at several viewport widths. It confirms no overlaps, and that each widget is hit-testable and in its slot. It exits 0 or 1. You can also import `auditLayout(page)` into your own Playwright suite.

```ts theme={null}
const h = await mountForTest(pageHtml);
await h.pick({ layer: "quakes", featureId: "q-101" });
expect(h.map.querySelector("#detail")!.shadowRoot!.textContent).toContain("M 6.1");
```

## React Projects

In React, do not render `om-*` elements from JSX. Use the first-party adapter: `import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react"`. Props are camelCase deck.gl props. Accessors are plain functions. Interactions are `onClick` and `onHover` handlers. React keeps the state, and the adapter drives the same rendering core with no DOM conflict.


# Cartographs & Atlases
Source: https://docs.nikaplanet.com/onlymap/cartographs

Build print-ready map sheets and multi-page atlases with OnlyMap JS: millimetre layouts, georeferenced frames with fallback sources, derived furniture, projected plates, and print-resolution export.

## Print maps are documents

`@nika-js/onlymap/cartograph` is a separate entry for composing print-ready map sheets
in HTML. A cartograph is measured in millimetres, not browser layout units. It combines
live OnlyMap scenes and static georeferenced rasters with legends, scale bars, north
indicators, graticules, text, shapes, and images.

The cartograph entry is lazy and separate from the interactive-map entry. It does not
increase the core map bundle, and a sheet containing only static frames never loads the
map runtime.

```html theme={null}
<!doctype html>
<link rel="stylesheet"
  href="https://unpkg.com/@nika-js/onlymap@0.11.10/dist/cartograph.css">
<script type="module"
  src="https://unpkg.com/@nika-js/onlymap@0.11.10/dist/cartograph.standalone.js"></script>

<om-cartograph size="A4" orientation="landscape" title="Parcel survey" dpi="300">
  <om-text kind="title" x="10" y="8" w="190" h="10">{{title}}</om-text>

  <om-frame id="main" x="10" y="24" w="220" h="150"
            center="[103.81, 1.31]" zoom="14.4">
    <om-map basemap="positron">
      <om-layer id="parcels" type="GeoJsonLayer" data="./parcels.geojson"
                label="Parcels" color="#0f766e"
                get-fill-color="'#0f766e'" pickable></om-layer>
    </om-map>
  </om-frame>

  <om-legend for="main" x="235" y="24" w="48" h="55"></om-legend>
  <om-scalebar for="main" x="10" y="178" w="65" h="9"
               units="metric"></om-scalebar>
  <om-north for="main" x="210" y="176" w="16" h="18"
            kind="rose"></om-north>
  <om-graticule for="main" x="10" y="24" w="220" h="150"
                interval="0.005" labels="outside"></om-graticule>
</om-cartograph>
```

## Frames and cartographic furniture

`<om-frame>` shows a picture from one of three kinds of source:

* A **live frame** contains an inline `<om-map>` or references a map document with
  `src`. The frame owns its camera, so the same map can appear at different extents on
  one sheet. Export captures it again at the requested print resolution.
* A **static frame** uses `mode="static"`, a raster image, `crs`, and four geographic
  `corners`. Scale bars, grids, and north indicators use that georeference without
  loading the interactive map runtime.
* **Ordered sources** <sup>new in 0.10.6</sup>: a live frame can list several places its
  picture may come from, as `<om-source>` children, and shows the first that actually
  renders. See [Fallback sources](#fallback-sources) below.

Furniture references a frame with `for="frame-id"`. A live-frame legend derives its
rows from the map's resolved symbology, including classified breaks, raster ramps, and
flat colours <sup>0.10.5</sup>, so the map and legend cannot drift apart. Static frames
can use literal `<om-legend-row>` entries with `derived="false"`.

### Colours by attribute <sup>new in 0.10.10</sup>

A sheet has five themes (`theme="default|dark|sepia|blueprint|minimal"`), and each
element's look can now be set on the element itself, beside the theme:

| Element | Attributes |
| - | - |
| `<om-cartograph>` | `bg`, `color`, `font` |
| `<om-legend>` | `bg`, `color`, `stroke`, `font-size` (pt), `padding` (mm) |
| `<om-scalebar>`, `<om-north>`, `<om-graticule>` | `color` |
| `<om-text>`, `<om-shape>` | `color`/`bg` and `fill`/`stroke`, as before |

Each override writes the same `--om-carto-*` property the theme sets, scoped to that
element, so the sheet on screen, the printed page and the exported image agree. Nothing
else is styleable: an attribute outside these lists is a validator warning, not a quiet
no-op — writing `background=` on the page, for instance, warns and changes nothing.

Use `overview-of="main"` on a second frame to draw the main frame's footprint as a
locator inset. Text supports page, frame, and atlas tokens such as `{{title}}`,
`{{date}}`, `{{frame.main.scale}}`, and `{{atlas.name}}`.

### A live frame follows its map <sup>since 0.8.3</sup>

A live frame georeferences whatever its map is showing. Pan, rotate or tilt the map
inside a frame and, once it settles, the north arrow, scale bar, graticule, locator
inset and `{{frame.<id>.scale}}` all describe the view on screen — not the camera the
document was saved with. Zoom out far enough and the world wraps inside the frame like
any web map: the graticule labels each copy, the scale bar measures its own row. The
frame never caps or rewrites the camera. `max-pitch` and `min-zoom` on `<om-map>` exist
as author-set controls for a kiosk-style map, and nothing applies them for you.

### Projected plates <sup>new in 0.10.0</sup>

A live frame inherits the projection of the map it shows. Point it at a map whose
`<om-map>` carries `crs="EPSG:5070"` and you get a properly projected plate — Albers,
UTM, a national grid — with the graticule, scale bar and north arrow all placed through
that plane. Choose the projection in the **map**, not the frame; see
[Cartographic Maps](/onlymap/authoring#cartographic-maps) for what a projected map can
and cannot carry.

### Freeze a frame to vector <sup>new in 0.10.0</sup>

`frame.freeze({ format: "svg" })` turns a live frame into editable artwork in place —
real `<path>` outlines and real `<text>` labels, with relief and imagery as images
underneath. The frozen sheet opens with no JavaScript at all and still reads correctly.
Freezing a projected frame writes the map's CRS onto it.

## Fallback sources <sup>new in 0.10.6</sup>

`src=` names one place a frame's picture comes from and assumes it works. That holds in
the app that wrote the sheet and often nowhere else: a relative path into an app's
storage, or layers served by an app-local protocol, both fail when the file is opened
elsewhere — and they fail *silently*. The map mounts, reports success, and draws an
empty box ringed by a perfectly correct legend, scale bar and title.

A frame can therefore declare several sources and show the first that **renders**:

```html theme={null}
<om-frame id="main" x="15" y="41" w="255" h="155" center="[-96, 38]" zoom="3.25">
  <om-source src="../maps/map-abc.html"></om-source>
  <om-source src="captures/main@2x.png"
             corners="[[-126,50],[-66,50],[-66,23],[-126,23]]" crs="EPSG:5070"></om-source>
</om-frame>
```

* **`src=` on the frame is shorthand** for the first `<om-source>`, so every existing
  sheet keeps working. An inline `<om-map>` child always outranks both.
* **One attribute, `src`, for both kinds.** The kind is read from the extension:
  `.html` is a map document; `.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`, `.gif` or
  `.svg` is a capture. Anything else is a validation error naming both — never a guess.
* **"Rendered" means one drawable thing** after the map settles — a basemap, or rows on
  any layer. Deliberately not "every layer loaded": a sheet whose fifth layer 404s is
  degraded, not failed, and swapping it for a stale capture would be worse.
* **A capture carries its own `corners` and `crs`**, because if it is what you are
  seeing, the live map did not load and there is nothing else to take coordinates
  from. Validation asks for them.
* **The frame says which source it settled on** — a `data-om-carto-source="<index>"`
  attribute and an `om-frame-source` event — so an editor can say "showing a capture".
  Furniture re-places itself against whichever source won.

<Note>
  A saved sheet renders **in place**; it is not portable. Capture paths are relative, so
  moving the file alone breaks them, exactly as it already breaks a relative `src=`.
  Exporting is what produces a file that survives being sent to someone — it inlines the
  map and embeds the pictures.
</Note>

## Print and image export

Sheets print at their real physical size through CSS `@page`. Live WebGL frames are
re-rendered and temporarily replaced with print-resolution images before the print
dialog opens, avoiding blank or screen-resolution map canvases.

```js theme={null}
import {
  renderCartograph,
  validateCartographString,
} from "@nika-js/onlymap/cartograph";

const page = document.querySelector("om-cartograph");
const result = await renderCartograph(page, { dpi: 300 });
// result.blob is a PNG by default; result.dpi reports the delivered resolution.
```

Use `page.print({ dpi: 300 })` for print/PDF or `renderCartograph(page, { dpi: 300 })`
for PNG/JPEG. A hosted cartograph can opt into `?print=1` and
`?export=png&dpi=300` automation by setting `allow-url-actions` on its root; for an
atlas, `?export=png&page=N` (1-based) exports one page of the run.

Press-work attributes are available on `<om-cartograph>`:

* `bleed` expands the printable sheet beyond the trim box.
* `crop-marks` draws trim marks inside that bleed.
* `safe-zone` shows a screen-only guide and never appears in output.
* `flatten` renders the final sheet as one raster for print workflows that mishandle
  SVG or CSS effects.

A map carrying an `<om-effect>` print finish exports as a single raster band, because
the finish treats the whole frame — see
[Print Finishes](/onlymap/authoring#print-finishes).

## One page per feature

`<om-atlas>` turns a layer into a run of sheets — one page per feature. Frames carrying
`atlas-fit="feature"` refit to the current feature, scale bars and tokens update for
that page, and `renderCartographAtlas()` writes the run to one ZIP.

```html theme={null}
<om-frame id="main" atlas-fit="feature" atlas-margin="0.15" ...></om-frame>
<om-atlas for="main" layer="parcels" sort="lot"
          filter="$area > 500"
          filename="lot-{{atlas.lot}}-{{atlas.name}}"
          page-name="{{atlas.name}}"></om-atlas>
```

```js theme={null}
import { renderCartographAtlas } from "@nika-js/onlymap/cartograph";

const { blob, filenames, pages } = await renderCartographAtlas(page, { dpi: 300 });
```

<Warning>
  **`atlas-margin` is a fraction of the feature's extent, not millimetres** — the one
  spatial number in the sheet vocabulary that is not mm. The default is `0.15`; `0.1`–`0.3`
  is the useful range. `atlas-margin="10"` pads each side by ten feature-widths, so every
  page shows its subject as a speck. Since 0.10.9 the validator warns on a margin above 2,
  on a non-numeric value, and on a margin set without `atlas-fit="feature"`, where it does
  nothing.
</Warning>

Pages render sequentially through one live map rather than cloning WebGL contexts, so
large atlases do not fail at the browser's context limit. The layer's features must be
in the document — an atlas cannot page over what a tiled or server-backed layer has
not loaded.

### Turning the pages <sup>new in 0.10.9</sup>

A reader can page an atlas anywhere the runtime runs — a plain browser, an embedding
app's preview, an exported file:

* **Keyboard:** `←`/`→`, `PageUp`/`PageDown`, `Home`, `End`, whenever focus is not in a
  form field.
* **An on-sheet pager**, `‹ 3 / 49 · Alabama ›`, at the sheet's foot. It is screen-only:
  never printed, never in a PNG or JPEG, and stripped before a host saves the document.
  `pager="none"` on `<om-atlas>` removes it for a host that draws its own.
* **A host protocol**, for an app that shows the sheet in a cross-origin iframe and so
  cannot reach `seek()`. On every page change the runtime posts
  `{ source: "onlymap-cartograph", type: "atlas-page", index, count, name }` to its
  parent window, and accepts
  `{ source: "onlymap-cartograph-host", type: "atlas-seek", index }` back. The index is
  0-based, like `seek(i)`.

Programmatically, the page element exposes `cartographEl.atlas` with `count`, `index`,
`current`, `seek(i)`, `next()`, `filenames()` and `pageName(i)`, and fires
`om-atlas-page`.

## Colour and validation

Set `cvd="deuteranopia"`, `protanopia`, `tritanopia`, or `achromatopsia` to review the
whole page through a colour-vision-deficiency simulation. `lintLegendColours()` detects
legend entries that collapse under those simulations.

`validateCartographString()` checks the page without loading the map core.
`validateCartographDeep()` additionally validates inline live-map manifests when the
core is already available. Diagnostics use the same structured error and warning shape
as `OmMap.validate()`.

## Attribution on a sheet

Free non-commercial cartographs include an OnlyMap foot credit in print and image
exports. An authored `<om-text>` credit mentioning OnlyMap satisfies the attribution
requirement; a verified commercial key on a live frame's map removes it, and
`<om-cartograph keep-badge>` keeps it voluntarily <sup>0.8.4</sup>. The sheet credits
itself **once**: a map inside a frame carries no badge of its own <sup>0.10.8</sup>, so a
plate with a main map and two locator insets is credited once, not three times. See
[Licensing & Telemetry](/onlymap/licensing-and-telemetry).

**Basemap credits move to the sheet too** <sup>new in 0.11.3</sup>. A map inside a frame no
longer shows its own OpenStreetMap or CARTO attribution: the sheet credits every provider
**once**, at the page's bottom-right, opposite the OnlyMap credit. A frozen frame records
its providers in an `attribution` attribute —
`attribution="© OpenStreetMap contributors · © CARTO"` — so a static or exported sheet still
credits its tiles with nothing loaded; set it yourself on a placed image whose tiles need
credit. A fallback capture `<om-source>` takes the same `attribution`, and the sheet credits it
while that capture is what the frame shows <sup>0.11.4</sup> — record it with the capture's
`corners`, since a capture is only shown when the live map did not load. If your own
`<om-text>` already names a provider, the sheet leaves it out of its line.

## Changes since 0.8.0

Behaviour fixes a sheet author may have worked around:

* **0.8.1** — A frame switched from static back to live no longer shows its old capture
  as a ghost behind the map. `max-pitch` on `<om-map>` added.
* **0.8.2 / 0.8.3** — The tilt cap a frame briefly imposed is gone; the frame now
  handles any view the map can show, and its furniture follows the map's settled view.
  Sheets saved zoomed-out or steeply tilted open as authored. `min-zoom` added.
* **0.10.0** — A projected frame is no longer placed upside down; relief reaches a
  projected sheet's corners; contour lines stop re-downloading elevation on every edit.
* **0.10.7** — A sheet now shows the *current* version of the map it points at. It used
  to serve the copy it fetched first, so a restyled map never reached the sheet — and a
  sheet that seemed to work only after you opened the map first was this.
* **0.10.8** — One attribution credit per sheet, not one per frame.
* **0.11.3** — Basemap credits (OpenStreetMap, CARTO, …) move off the frames into one
  line in the page's corner, and frozen frames keep them.
* **0.11.4** — A frame that falls back to its saved capture credits that capture's providers.
* **0.11.5** — On a frame whose map uses a projected `crs`, popups appear and a click on a
  feature reports its longitude and latitude. Popups used to stay hidden there, and
  `zoom-to-feature` went to the wrong place.
* **0.11.6** — Curved labels (`TextOnPathLayer`) take `pickable`, and a click on one reports
  the river or road it names, so a `{{name}}` popup no longer comes up blank.

For the complete element and attribute reference, see the
[package cartograph guide](https://github.com/NikaGeospatial/onlymapjs/blob/main/docs/cartograph.md).


# Licensing & Telemetry
Source: https://docs.nikaplanet.com/onlymap/licensing-and-telemetry

Free for non-commercial use with attribution; commercial licensing lifts the free-plan limits. What telemetry collects, and how to turn it off.

## Licensing

OnlyMap JS is proprietary software. It is **free for non-commercial use with attribution** — personal projects, education, academic research, and evaluation. Commercial use needs a commercial license. Commercial use includes for-profit products, internal tools, revenue-generating services, paid consulting, and government work. The full terms are in the package's `LICENSE.md`.

### The Free Plan

Without a license key, a map runs on the free plan:

* Up to **5 layers** per map, and **25,000 rows per layer** (20 MB per data fetch).
* A small badge shows on the map: **"OnlyMap by NIKA. Free for non-commercial use."** You must keep the badge visible. This is a condition of the free non-commercial grant.
* A limit never breaks the map. A layer past the **layer** cap does not render. A layer past the **row** cap renders its first 25,000 rows and shows a dismissible on-map notice that the data is partial, so a capped map is still useful without pretending to be complete. Either way, the validation stream names the exact limit and how to lift it.
* **The limits apply only on hosted http(s) pages** (since 0.6.0). In a development context — localhost, a `file://` page, or any non-web scheme such as a desktop app shell — every cap lifts so you can build without friction. The attribution badge stays in all contexts.
* The exemption is a technical convenience, not a license grant: commercial deployment — hosted **or** shipped inside a packaged app — requires a commercial key regardless of whether the technical limits were active (LICENSE.md §3).

### License Keys

A license key lifts all limits and removes the badge:

```html theme={null}
<om-map license-key="om_live_…">
```

```ts theme={null}
OmMap.configureLicense("om_live_…");
```

Removing the badge is something a commercial license *permits*, not something it
requires. `keep-badge` on `<om-map>` (or `OmMap.setKeepBadge(true)`) lifts the free-plan
limits while still crediting OnlyMap <sup>new in 0.8.4</sup>; the badge then shows the
credit without the "free for non-commercial use" sentence, which would not describe a
paid deployment. The preference is page-level and live, and a cartograph's foot credit
follows it — `<om-cartograph keep-badge>` opts a static sheet in on its own, with no map
runtime.

A print sheet credits itself **once** <sup>since 0.10.8</sup>: a map mounted inside a
cartograph frame carries no badge of its own, because the sheet is the published
artefact and renders the credit for the whole page. A plate with a main map and two
locator insets is credited once, not three times.

A key is **publishable and deployment-restricted**. It is bound to your domains, so it is safe to put in the page source, like a map-provider API key. It verifies offline, with no network round-trip, so it works in CI and in air-gapped environments. For licensing questions, see [nikaplanet.com/onlymap](https://www.nikaplanet.com/onlymap).

A key can also be scoped to one or more packaged applications, for a map shipped inside a native app shell rather than served from a domain. The app passes its own identifier at startup:

```ts theme={null}
await OmMap.configureLicense("om_live_…", { appId: "com.example.riders" });
```

The identifier must come from the platform's own build metadata — never from page script or a bridge message, which the library cannot tell apart from the real thing. Because of that, app scoping is a deployment marker rather than an enforced boundary the way a domain is: ask for a key scoped by **both** your domains and your app identifiers where a deployment has both.

### Third-Party Software

The published bundle includes open-source components (deck.gl, MapLibre GL, Apache Arrow, the GeoTIFF/raster stack, and others). Each component keeps its own permissive license (MIT, ISC, BSD, Apache-2.0). The full list, with the license texts, ships in the package as `THIRD-PARTY-LICENSES.md`. The library generates this list from the dependency tree at each release. OnlyMap's own terms do not change those licenses.

## Telemetry

The library reports **one deployment-scoped usage snapshot per map, per page load**. The snapshot holds the layer types and counts, the widget types, the renderer, the library version, and the page hostname. The library also reports **errors from its own code** — never from your page scripts. Both go to a NIKA-operated first-party endpoint. The full payload schema is in the package's `docs/telemetry.md`.

The library **never** collects page paths or URLs, your data or its contents, coordinates, cookies, or any persistent visitor identifier. A test suite stays silent, because a `headless` map never reports.

### Opting Out

```ts theme={null}
OmMap.configureTelemetry({ disabled: true });   // global — usage snapshots AND error reports
```

```html theme={null}
<om-map telemetry="off">                        <!-- per map -->
```

### `map-id`

`map-id` is an optional attribute. It identifies the **map artifact**, not the visitor. Usage can then tell one popular dashboard from many different maps:

```html theme={null}
<om-map map-id="0f2c6a1e-88f7-4c3e-9d41-7b1f3f9f2ab7">
```

It is author-controlled page metadata. Nothing is stored on the visitor's device. You can change or delete it at any time. It is never required.


# Overview
Source: https://docs.nikaplanet.com/onlymap/overview

OnlyMap JS is NIKA's declarative map library: interactive WebGL maps written as HTML custom elements, powered by deck.gl — no build step required.

## Overview

OnlyMap JS (`@nika-js/onlymap`) builds an interactive WebGL map from a small set of HTML custom elements. You write the layers, widgets, popups, interactions, and guided tours as markup. The library does the rendering, the data loading, the live updates, the picking, and the validation. You do not write deck.gl setup code, shader code, or a build step. One HTML file is a complete map application.

OnlyMap JS is also made for AI agents to write. HTML is a reliable output format for a model. The package includes an agent skill and an `llms.txt` file. `OmMap.validate()` returns structured errors, and each error has a fix. Together these give an agent a real authoring loop.

```html theme={null}
<om-map center="[-122.42, 37.77]" zoom="11" basemap="positron">
  <om-layer id="quakes" type="ScatterplotLayer"
            data="./quakes.json"
            label="Earthquakes" color="#e63946"
            get-position="[$lon, $lat]"
            get-radius="scale($mag, sqrt, [2, 20], domain=[0, 8])"
            pickable></om-layer>
  <om-widget type="legend" position="top-right"></om-widget>
</om-map>
```

## Install

Install the package from npm:

```bash theme={null}
npm install @nika-js/onlymap
```

Import the library and its stylesheet:

```js theme={null}
import "@nika-js/onlymap";
import "@nika-js/onlymap/onlymapjs.css";
```

You can also load it from a CDN with no build step:

```html theme={null}
<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap/dist/onlymapjs.css">
<script type="module" src="https://unpkg.com/@nika-js/onlymap"></script>
```

Bundler support: Vite, webpack 5 (Next.js, Create React App), and Rollup all work — webpack required `@nika-js/onlymap@0.6.19` or later. Use a raw-file CDN (unpkg, jsDelivr) — the bare package URL serves a single-file standalone bundle built for this. Do not use a rebundling CDN such as esm.sh or skypack: re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.

Building a mobile app? The same runtime ships as an Expo React Native
adapter, `@nika-js/onlymap-native` — see [React Native](/onlymap/react-native).

Two optional commands complete the setup:

* **`npx @nika-js/onlymap init`** — adds VS Code IntelliSense for every `om-*` element and attribute. It also adds `!`-prefix snippets (`!starter`, `!map`, …).
* **`npx -y skills add NikaGeospatial/onlymapjs --skill onlymapjs`** — installs the OnlyMap authoring skill into coding agents (Claude Code, Cursor, Codex). The agents then write correct manifests on the first try.

## Key Features

### Declarative Everything

* **41 layer types by name**: all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, and more). It adds a built-in `PopupLayer` for WebGL labels at scale, a native `COGLayer` for GeoTIFF rasters, a `ZarrLayer` for chunked Zarr/GeoZarr rasters, an `ImageOverlay` for georeferenced drone photos, a `BIMLayer` for in-browser IFC models, `Route`/`Tracking` for styled routes and live position tracking, a `HillshadeLayer` for shaded relief, and a `TextOnPathLayer` for labels that follow a line.
* **Live manifest**: the markup is the state. When you change an attribute — from a widget, a behavior, a script, or devtools — the map updates automatically.
* **Satellite imagery without a key** <sup>new in 0.11.10</sup>: `basemap="satellite"` shows a cloud-free satellite view of the whole world (EOX Sentinel-2 cloudless), free for commercial use with its credit — detailed to about city-district zoom. Sharper, current imagery remains the keyed `maptiler-satellite`.
* **Built-in undo and redo**: you can undo a layer toggle, a filter change, a basemap switch, an element edit, or a drawn sketch. Use `<om-widget type="undo-redo">` or Cmd/Ctrl-Z.
* **Clustering as a toggle** <sup>new in 0.11.0</sup>: `cluster="true"` on a point layer merges the points that would overlap into count bubbles that split apart as the reader zooms in — same layer, same data, same styling for the points that stand alone. `cluster-properties` carries sums, means or the commonest category onto each bubble, bubble sizes stay meaningful at every zoom, and a click flies to where a bubble splits. See [Clustering](/onlymap/authoring#clustering-overlapping-points).
* **Print-ready cartographs** <sup>new in 0.8.0</sup>: the separate `@nika-js/onlymap/cartograph` entry composes millimetre-based map sheets with live or static georeferenced frames, derived legends, graticules, scale bars, north arrows, press marks, and atlas export. It stays out of the interactive-map bundle, and a static-only sheet never loads the map runtime. A frame can name **fallback sources** <sup>0.10.6</sup> — a capture it shows when its live map cannot load where the sheet is opened — and an atlas can be **paged by its reader** <sup>0.10.9</sup> with the keyboard or an on-sheet control. See [Cartographs & Atlases](/onlymap/cartographs).
* **Maps in a real projection** <sup>new in 0.10.0</sup>: `crs="EPSG:5070"` on `<om-map>` draws the whole map in that projection's plane — parallels curve, an equal-area map is genuinely equal-area, a national-grid sheet is drawn in its own grid. Albers, the UTM zones, British National Grid, Swiss LV95, Lambert 93, RD New and more are built in; anything else takes a `+proj=` string. The authored camera stays geographic. See [Cartographic Maps](/onlymap/authoring#cartographic-maps).
* **Shaded relief as a layer** <sup>new in 0.9.1</sup>: `<om-layer type="HillshadeLayer" src="terrarium">` draws shaded terrain from keyless global elevation tiles on a flat map, or `shading="hillshade"` turns a `COGLayer`/`ZarrLayer` DEM of your own into relief that shows *through* a colormap. Up to four suns (`sun-azimuth="315 45 135"`) for Swiss-style multi-directional relief; seamless tile edges, true shape at every latitude, and it works on a projected map.
* **Geometry your data doesn't contain** <sup>new in 0.10.0</sup>: `<om-transform>` inside a layer adds `simplify`, `smooth`, `dot-density`, `buffer` (with `repeat` and `fade` for the engraved coastal vignette of old charts) and `contour` (elevation lines marched off a DEM). Sizes are millimetres on the page.
* **Labels that follow the line they name** <sup>new in 0.10.0</sup>: `<om-layer type="TextOnPathLayer">` runs a river's name along the river. It reads the right way round whichever way the line was drawn, slides to the straightest stretch it fits on <sup>0.10.5</sup>, and drops a name that does not fit rather than squeezing it.
* **Export a map as editable vector** <sup>new in 0.10.0</sup>: `snapshot({ format: "svg" })` gives real `<path>` outlines and real `<text>` labels for Illustrator or a print shop, with relief and imagery placed as images underneath.
* **A printed finish in one attribute** <sup>new in 0.9.0</sup>: `<om-effect preset="vintage">` treats the rendered frame — seven looks ship, every one built from named operations you can write yourself, sized in millimetres so a 600 dpi export has the same texture you tuned on screen. An `effects` widget <sup>0.9.1</sup> switches finishes live, and undo sees it. See [Print Finishes](/onlymap/authoring#print-finishes).

### A Full 3D Scene, Still Just Attributes <sup>new in 0.3</sup>

* **Terrain**: `terrain="terrarium"` adds real elevation with no configuration (keyless AWS tiles). Geographic layers drape onto the surface automatically. You can also give your own DEM tile URL or register presets.
* **Scene lighting**: set `lighting="daylight|studio|flat|custom"`, with `lighting-*` attributes for fine control. `lighting-sun-date` computes the sun position from a date and the map location. A `lighting` widget shows these as presets and sliders.
* **Snapshots**: `map.snapshot()` captures the basemap and the WebGL canvas together, as a PNG data URL or a Blob, or as editable SVG with `{ format: "svg" }` <sup>0.10.0</sup>. Use it for print and export pipelines.
* **Camera limits as author controls** <sup>0.8.1 / 0.8.3</sup>: `max-pitch` caps how far a map can be tilted and `min-zoom` floors how far it can be zoomed out — for a kiosk or embedded map that should stay within its intended view. Neither is applied automatically.
* **BIM / IFC models** <sup>new in 0.6.1</sup>: `<om-layer type="BIMLayer" src="./model.ifc">` (or the `ifc-loader` drop-zone widget, with multi-model federation) parses IFC in the browser via CDN-fetched web-ifc and renders it as 3D Tiles. `pick-features` gives per-element picking on any 3D Tiles layer; declarative isolate/hide/ghost, colour-by-property, an `ifc-browser` model tree, a `feature-inspector`, and an `ifc-clash` overlay come as attributes and widgets.
* **Cut, export, and pick inside a 3D scene** <sup>new in 0.6.2</sup>: three tools that work on whatever 3D content is already loaded — 3D Tiles, BIM models, extruded vector geometry alike. A **clip box** (`<om-map clip-box-min="[lng,lat,elev]" clip-box-max="…">`, or the `clip-box` widget with draggable face handles) cuts the scene open; `clip-box-invert` shows what is outside instead, `clip-box-highlight` dims the cut-away geometry instead of removing it, and `clip="off"` opts a layer out. **Region export** (`<om-widget type="draw" export-3d>`) downloads the 3D content inside a drawn footprint as a portable GLB, or `export-3d="b3dm"` for Cesium and 3D Tiles pipelines. **`pickable="3d"`** opts a layer into depth picking, so a click on a building face resolves on the face and carries a real elevation, instead of the ground point behind it.
* **Snapping to real geometry** <sup>new in 0.6.2</sup>: `<om-map snap="vertex edge midpoint" snap-tolerance="12">` refines a click or hover to the nearest vertex, edge, or edge midpoint of whichever feature is under the cursor — including a BIM model's own wall corners. Vertex wins over midpoint over edge; hold Space to place a point without snapping, the usual CAD convention. `snap="off"` opts a layer out.
* **3D city models** <sup>new in 0.5</sup>: point `data` at a CityJSON file (`.city.json`, or a streamed `.city.jsonl`) — national building datasets such as 3DBAG and PLATEAU. The library decodes it to extruded footprints by default, or to real per-face roof geometry with `?om-surfaces=1`, and reprojects national coordinate grids (NL, CH, DE, JP, AT, SG) automatically.

### Data That Stays Fresh

* **Formats**: JSON/GeoJSON, CSV/TSV, Apache Arrow and GeoArrow (columnar fast path, zstd IPC), Shapefile with `.dbf` attributes, KML, GPX, the cloud-native **FlatGeobuf** (`.fgb`) and **GeoParquet** (`.parquet`) vector formats, and **CityJSON / CityJSONSeq** (semantic 3D city models). Large parsers load on first use.
* **GeoTIFF and Cloud-Optimized GeoTIFF** <sup>new in 0.3.1</sup>: `<om-layer type="COGLayer" src="./dem.tif">` streams raster tiles by HTTP Range request. The min/max restretch and the colormap are GPU uniforms, so the tiles are not fetched again. Nodata pixels are transparent.
* **Zarr / GeoZarr rasters** <sup>new in 0.5.11</sup>: `<om-layer type="ZarrLayer" src="./x.zarr" variable="temp" select="time=0">` renders chunked N-dimensional array data (climate/weather grids, datacubes) on the GPU. Pin the non-spatial dimensions with `select`; GeoZarr stores georeference themselves, a plain Zarr takes manual `bounds`/`crs`/`spatial-dims`. `src` can point at any CORS-enabled public remote store — no server setup needed.
* **Georeferenced drone photos** <sup>new in 0.5.7</sup>: `<om-layer type="ImageOverlay" src="./DJI_0123.jpg" georeference="exif">` reads a JPEG's EXIF/DJI-XMP, computes its WGS84 footprint, and overlays the image — no manual corner-pinning. `OmMap.resolveImageOverlay(file)` preprocesses once for saved maps; explicit `bounds` reconstructs without re-reading EXIF.
* **Live sources**: WebSocket streams with upsert-by-key and burst coalescing. Polled REST snapshots with `refresh="5s"`.
* **Routing and tracking** <sup>new in 0.6.7–0.6.11</sup>: `<om-layer type="Route">` draws a styled route (casing, line, origin/destination markers) from a GeoJSON LineString you already have, or resolves one from `origin`/`destination` through a pluggable `RoutingProvider` — a \~15-line adapter covers OSRM's keyless demo server, Mapbox, OpenRouteService, or your own engine. `follow="fit-route"` frames the camera on arrival, and `om-route-resolved` hands the page the resolved geometry, distance, duration, and legs. `<om-layer type="Tracking">` renders a moving entity that glides between GPS fixes with bearing-based rotation, an `arrow`/`car`/`motorcycle` marker tinted per entity, and an optional follow camera; the position feed is ordinary layer `data` (a WebSocket stream, a polled endpoint), not a separate API. Link the two with `progress-from` and the route splits live at the marker: `tail="none"` hides the traveled portion (the client view), `tail="dim"` darkens it (the operator view).
* **Multi-dimension GPU filters** <sup>new in 0.6.5–0.6.6</sup>: up to 4 numeric ranges (`filter-fields`) and up to 4 categorical keep-lists (`filter-category-fields`) filter a layer at once, combined on the GPU with no data re-upload. The same `filter` widget renders a slider for a numeric field and a checkbox list for a categorical one, and widget statistics respect every active dimension.
* **Private endpoints**: `OmMap.configureData({ headers, credentials, fetch })` keeps credentials out of the markup.

### Application UI Without an App Framework

* **Widgets**: legend, layer switcher, basemap switcher, lighting controls, zoom controls, undo/redo, scale bar, attribution, GPU filter sliders (including readable date labels for epoch-millisecond fields), a play/pause `time-slider` for temporal data, live Vega-Lite charts, a drawing toolbar, a measure tool, a clip-box control, and an event-driven `dynamic-chart`. You can also write custom widgets with a typed context (`ctx.data`, `ctx.stats`, `ctx.viewport`, `ctx.emit`).
* **Measurement, including cut/fill volume** <sup>new in 0.6.2</sup>: `<om-widget type="measure" modes="distance area volume">` measures geodesic distance and area, and — in `volume` mode — real earthworks cut and fill. Outline a footprint and the library integrates the terrain DEM cell by cell against a base surface, so one shape can report cut *and* fill on sloping ground, each with a published ± error quoted against the DEM's own ground-sample distance. Choose the base surface with `base-surface` (`custom` drag-a-plane, `triangulated` boundary TIN, `plane`, `lowest`, `highest`, `average`). `density`, `swell`, and `shrink` add Bank/Loose/Compacted volumes and tonnage; `profile` samples an elevation profile around the footprint for a `dynamic-chart` to plot. Volume mode needs `terrain` on the map.
* **Safe date formatting**: `formatDate($time, 'datetime', 'UTC')` turns epoch-millisecond or ISO fields into readable `get-text` labels without enabling arbitrary JavaScript. The same date style and time-zone contract is available on the built-in filter widget.
* **Managed, adaptive layout** <sup>new in 0.4</sup>: `position` puts a widget in one of 8 logical slots (`top-start` … `bottom-end`), and the library sets the pixel position. Widgets in the same slot stack with a shared gap, and small controls next to each other join into one group. The map attribution and the license badge sit in the bottom slots as normal members, so they do not cover a widget. On narrow maps (640px or less by default; change it with `--om-widget-fold-breakpoint`) the widgets fold into drawers, and a slot dims when an open popup covers it. `<om-map widgets-hidden>` hides all your widgets but keeps them in the page, and `position="manual"` turns off management for one widget.
* **Classified symbology** <sup>new in 0.6.12</sup>: `classify-by="magnitude"` computes choropleth-style class breaks from the data itself — `classify-scale="quantile|equal-interval|jenks"`, 2–12 classes, and 14 named color ramps (`viridis`, `turbo`, `ylorrd`, `spectral`, …) — and the legend shows the computed classes automatically. No hand-written domains or color lists.
* **Temporal playback** <sup>new in 0.6.12</sup>: `<om-widget type="time-slider" layer="quakes" field="time" duration="20s" loop>` plays a time field back through the ordinary GPU filter — cumulative reveal or a sliding `window` — so statistics, undo, and stories stay coherent with the animation.
* **Symbology-aware legends** <sup>new in 0.3</sup>: the legend uses each layer's real color styling. A continuous `scale()` ramp becomes a gradient bar with domain labels. A threshold scale becomes discrete class ranges. A categorical expression becomes a swatch palette. A raster colormap becomes its ramp. You do not configure the legend.
* **Themeable from plain CSS**: each built-in widget reads `--om-widget-*` custom properties (`om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }`). You can set a dark theme with one CSS rule and no JavaScript.
* **Overlays and behaviors**: HTML popups anchor to map coordinates or to a picked feature. Declarative `on="click|hover|drag|load"` interactions need no event-handler code.
* **Map stories**: an `<om-story>` has steps that fire the same actions as behaviors, including basemap, lighting, and terrain changes. A player widget plays the steps, and you can scrub to any step.
* **Travel-map animations + external renderer support** <sup>new in 0.6.18</sup>: trace steps take `follow` (camera rides the drawing tip) and `easing`; `anchor="surface"` puts labels on the shapes themselves; and `whenSettled()` + interpolating `seek()` + the `data-om-recording` determinism switch let Remotion-class frameworks render stories frame-by-frame with byte-identical output.
* **Sharp 3D flybys + video export** <sup>new in 0.6.17</sup>: `<om-story warm-tiles>` pre-loads a route's 3D tiles before playback; `<om-story paced>` holds each frame until tiles are sharp (no blurry frame, ever); and `npx onlymapjs record map.html --out flyby.mp4` turns a story into a video with every frame fully refined — `--gpu` for several-times-faster takes on heavy scenes.

### Built for Verification

* **`OmMap.validate(html)`** returns structured errors, and each error has a fix. Add the `validate` attribute for a live error panel on the page.
* **Headless test harness**: `mountForTest` runs full behavioral tests (picks, widgets, overlays, real projection math) in jsdom or happy-dom, with no WebGL.
* **Layout audit** <sup>new in 0.4</sup>: `npx @nika-js/onlymap check-layout <manifest.html>` checks the real widget layout in headless Chromium at several viewport widths. It confirms that no widgets overlap, that each widget is hit-testable and in its slot, and that same-slot edges align. It prints structured `{severity, element, message, fix}` diagnostics and exits 0 or 1. You can also import `auditLayout(page)` into your own Playwright suite.
* **React adapter**: `@nika-js/onlymap/react` gives `<OmMap>`, `<OmLayer>`, `<OmWidget>`, `<OmOverlay>`, and a typed `useOmMap()` hook over the same core. React keeps the state, and the adapter does not conflict with the virtual DOM.
* **Custom layer classes**: `@nika-js/onlymap/deck` re-exports the bundled deck.gl classes. `OmMap.registerLayer` extensions use the renderer's own class hierarchy. A desktop app can register domain layers (local-file rasters, catalog sources) as first-class manifest types.

### Framework & Programmatic Integration <sup>new in 0.4</sup>

* **`MapController`**: a programmatic front-end for frameworks. Typed `LayerDescriptor`s drive the same reconcile core, with no DOM manifest. It adds camera methods, `emit`, `injectPick`, `snapshot`, the picking queries `pickAt`/`pickRect`/`unproject` with a `pickMode` switch <sup>0.11.5</sup> (also on `<om-map>`), and `onViewChange`/`onMapPoint`/`onTilesetLoad` callbacks.
* **External-store contract**: `getStore(token)` gives a `{subscribe, getSnapshot}` store for each token (`viewport`, `selection`, `layers`, `data:<id>`). The snapshots are cached, immutable, and tagged with an `origin`. You can use them directly with React's `useSyncExternalStore`, MobX, Redux, or Zustand.
* **Consumer events**: `om-view-changed` fires when the camera settles. `om-map-point` fires on each click or hover with the map coordinate — use it for custom capture tools that the draw widget does not cover. `om-tileset-load` gives a `Tile3DLayer`'s live `Tileset3D`, for tools such as region export. `om-route-resolved` hands over a `Route` layer's resolved path — normalized geometry, distance, duration, legs, and bounds — so a page can render an ETA or a turn list without re-fetching the route. `om-measure` carries the measure widget's full readout — distance, area, cut/fill volumes with their error bounds, material-adjusted figures, and the elevation profile series — so you can render your own readout instead of the built-in panel.

## Roadmap

These features are designed but not shipped yet: Mapbox GL basemaps, depth-interleaved 3D compositing, globe projection, SSE transport, `dblclick` behaviors, the typed fluent builder, and stories and draw as React components. On cartography: relief cannot yet be masked to land, `contour` samples in the DEM's Mercator grid even on a projected sheet (the lines themselves project exactly), and native-CRS tile pyramids are deferred. The README lists the current state in its "Not implemented yet" section at each release.

## Resources

* **npm**: [`@nika-js/onlymap`](https://www.npmjs.com/package/@nika-js/onlymap)
* **GitHub (docs, examples, llms.txt)**: [NikaGeospatial/onlymapjs](https://github.com/NikaGeospatial/onlymapjs)
* **Product page**: [nikaplanet.com/onlymap](https://www.nikaplanet.com/onlymap)


# React Native
Source: https://docs.nikaplanet.com/onlymap/react-native

@nika-js/onlymap-native runs the full OnlyMap runtime inside an Expo React Native app: the same layers, expression accessors, and live data, driven from JSX over a JSON bridge.

## What it is

`@nika-js/onlymap-native` is the official React Native adapter for OnlyMap JS.
It packages the complete web runtime — every layer type, data format, live
transport, and validation rule — inside a secure WebView served from a
loopback-only host, and gives you `<OmMap>` and `<OmLayer>` components that
speak the same vocabulary as the web library. The adapter owns the JSON
bridge, the app lifecycle (background suspend, foreground resume), and
WebView renderer recovery.

It is not a native MapLibre renderer and not the web `@nika-js/onlymap/react`
adapter: it is the OnlyMap runtime itself, hosted natively. A 20-fixture
parity gate keeps the React Native surface byte-identical to the web React
adapter at the intermediate-representation level.

```tsx theme={null}
import { OmLayer, OmMap } from "@nika-js/onlymap-native";

export default function RiderMap() {
  return (
    <OmMap style={{ flex: 1 }} center={[103.852, 1.287]} zoom={13.5} basemap="positron">
      <OmLayer
        id="riders"
        type="ScatterplotLayer"
        data={riders}
        getPosition="[$lon, $lat]"
        getFillColor="$color"
        getRadius="9"
        radiusUnits="pixels"
        pickable
        onClick={(selection) => console.log(selection.object)}
      />
    </OmMap>
  );
}
```

## Support matrix

| Environment | Status |
| - | - |
| Expo SDK 57 development build (iOS, Android) | Supported |
| Expo SDK 57 local Release build (iOS, Android) | Supported |
| Expo Go | Unsupported — the adapter includes native modules |
| EAS Build / EAS Update | Not yet verified |
| Bare React Native | Planned (`0.2.0`) |
| Flutter (`onlymap_flutter`) | Planned — same bridge protocol |

Install the package and follow the setup in its bundled `llms.txt` (local
networking permission, cleartext-for-loopback exception, and the Metro config
extension for the packaged host assets):

```bash theme={null}
npm install @nika-js/onlymap-native
npx expo install expo-build-properties
```

## The rules that differ from web

* **Accessors are expression strings, never functions.** `getPosition="[$lon, $lat]"`
  crosses the JSON bridge; `getPosition={(d) => ...}` cannot and is rejected.
* **Props are camelCase JSX**, not the web manifest's kebab-case attributes.
* **Everything crossing the bridge is finite plain JSON.** Bulk data stays out
  of the bridge: pass URLs (the full web format matrix works unchanged from a
  URL inside the packaged host — GeoJSON, CSV, KML, GPX, FlatGeobuf, GeoArrow
  including zstd, GeoParquet, Shapefile, range-requested COG), WebSocket
  `source="upsert"` streams with `streamKey`, or `refresh` polling.
* **Native UI lives beside the map**, driven by the imperative handle and
  `useOmMapWatch`. The web's widgets, overlays, stories, and draw have no
  native components yet — but `<OmMap html={manifestString}>` hosts a raw
  HTML manifest so the full DOM lane runs in the WebView; sketches reach
  React Native as GeoJSON via `onDrawChange`, measure readouts via
  `onMeasure`.
* **Events for taps, watch tokens for continuous state.** Per-layer
  `onClick` is the tap-selection channel. `useOmMapWatch` mirrors
  continuous state (viewport, layers, data) last-write-wins — hover picks
  share the `selection` token, so a tap's trailing hover can overwrite the
  click in the same render batch if you try to drive selection UI from it.
* **`emit()` runs core-backed actions** (`fly-to`, `zoom-in`, `zoom-out`,
  `zoom-to-feature`, registered custom actions) exactly as on the web
  `MapController`. DOM-manifest actions (`toggle-layer`, `filter-layer`,
  overlay/tooltip/story actions, `set-basemap`) deliberately warn and do
  nothing natively — express those through React props and state.

## The imperative handle

A ref (or `useOmMap()` in descendants) exposes the `MapController` surface,
all Promise-returning: `flyTo`, `flyToBounds`, `zoomBy`, `setView`,
`getViewState`, `project`, `getSelection`, `emit`, `snapshot`, `stats`,
`data`, `dataInViewport`, `irSnapshot`, `reload`, `hostFile` (copies a device
file into the served tree and returns a local URL for layer `data`), and
`injectPick`.

`injectPick` is the consumer testing surface: a synthetic selection travels
the same code path as a real tap and reaches your per-layer
`onClick`/`onHover`, so interaction handling is testable in CI without a
device. `reload()` deliberately rebuilds the WebView renderer and replays
canonical state; repeated calls are harmless.

## Lifecycle, verified on hardware

The adapter suspends rendering and live transports when the app backgrounds
and restores them on foreground; WebView renderer loss replays configuration,
the complete layer document, settled camera, and watches. These are tested
claims, not intentions: the acceptance suite runs on an iOS simulator and an
Android emulator in CI on every change, and on physical hardware the full
flow suite is green — including a five-minute background against a live
WebSocket feed (current data within seconds of returning), airplane-mode
network loss with structured errors and unattended recovery, and bridge
round-trip latency measured at \~8.5 ms median on a mid-range Android phone.

## Reference

* The package ships `llms.txt` (the complete agent-facing authoring
  reference) and an installable agent skill — both inside the npm tarball.
* Repository, examples, and acceptance evidence:
  [github.com/NikaGeospatial/onlymap-native](https://github.com/NikaGeospatial/onlymap-native)
* Licensing: commercial keys support app-scoped `apps` claims for packaged
  applications — see [Licensing & Telemetry](/onlymap/licensing-and-telemetry).


# Remotion
Source: https://docs.nikaplanet.com/onlymap/remotion

@nika-js/onlymap-remotion renders OnlyMap maps as frames inside a Remotion composition: bring a route, a list of places, or a story, and the camera, markers and video length are derived from that data.

## What it is

Remotion makes videos by screenshotting a React page once per frame. A map is
the worst possible thing to screenshot: tiles stream in asynchronously, labels
settle over hundreds of milliseconds, and the camera animates on its own clock.
Point Remotion at a map naively and you get blurry frames, missing labels, and
a video that renders differently every time.

`@nika-js/onlymap-remotion` makes a map safe to screenshot. Every frame is held
until the map reports it has genuinely finished drawing, and a frame is a pure
function of the frame number — the same frame renders byte-identically whether
it is produced alone, in sequence, or out of order.

```tsx theme={null}
import { OmMapVideo, omMapVideoMetadata } from "@nika-js/onlymap-remotion";

// One component. The prop you pass decides how the camera moves.
<OmMapVideo src={staticFile("map.html")} route={route} zoom={14} pitch={55} />
```

It is an independent integration, not affiliated with or endorsed by Remotion.

## Which tool for which job

<Note>
  If the video is *just the map moving* — no titles, no overlays, one output —
  you do not need this package. `npx onlymapjs record map.html --out flyby.mp4`
  is one command and has none of the caveats below.
</Note>

| You want | Use |
| - | - |
| An MP4 of a flyby, nothing layered on top | `onlymapjs record` |
| A map clip inside a larger Remotion edit | `record` → `<OffthreadVideo>` |
| Text, labels or charts that react to the map per frame | This package |
| One composition rendering many videos from data | This package |

## Bring data, not coordinates

The camera should be derived from data you already have. The prop you pass to
`<OmMapVideo>` selects the source, and `omMapVideoMetadata` derives the
composition's duration from that same prop — so a longer route is a longer
video, and an extra stop is a longer tour.

| You have | Prop | Derived for you |
| - | - | - |
| GeoJSON LineString | `route` | position, follow-bearing, marker, duration from ground distance |
| A list of places | `places` | dwell-and-travel tour, duration from the list |
| An OnlyMap story | *(none)* | camera and duration from the story |
| Composed shots | `keyframes` | interpolation between poses |

```tsx theme={null}
<Composition
  id="flyover"
  component={MyVideo}
  fps={30}
  width={1920}
  height={1080}
  durationInFrames={1}                    // replaced by calculateMetadata
  defaultProps={{ route }}
  calculateMetadata={omMapVideoMetadata({ fps: 30, metersPerSecond: 600 })}
/>
```

TypeScript permits only one camera source at a time, so a contradictory
composition does not compile. Anything the wrapper cannot express — a spring, a
data-driven zoom, a camera chasing live telemetry — drops to the `useOmManifest`
and `useOmCamera` hooks it is built from.

Hand-typed coordinate arrays are the escape hatch, not the starting point. If
you find yourself typing longitudes, you probably want a route file instead.

## Overlays that track geography

This is the capability a recorded MP4 cannot offer. Because the map is live DOM
inside your React tree, `projectLngLat` gives a coordinate's screen position
each frame, so Remotion content — `<Sequence>`-timed, `interpolate()`-animated —
stays pinned to a place as the camera flies over it.

```tsx theme={null}
<OmMapVideo src={staticFile("map.html")} route={route}
  onFrameSettled={() => project({ hq: [-122.4, 37.79] })}>
  {points.hq && <Label style={{ left: points.hq[0], top: points.hq[1] }}>HQ</Label>}
</OmMapVideo>
```

<Warning>
  Projection must be committed with `flushSync` inside `onFrameSettled` — a plain
  `setState` lands after the frame is captured, so every overlay renders one frame
  stale and visibly lags the map. The `useProjectedPoints` helper does this for
  you.
</Warning>

## The rules that differ from ordinary Remotion

* **ANGLE GL is required, not preferred.** Remotion's default software renderer
  cannot create a WebGL context for the map — every render fails. Set
  `Config.setChromiumOpenGlRenderer("angle")` in `remotion.config.ts`, or pass
  `chromiumOptions: { gl: "angle" }` to programmatic `@remotion/renderer` calls,
  which do not read the config file.
* **Preview and render gate differently, on purpose.** Studio releases each
  frame as soon as the camera is written, so scrubbing is instant and tiles pop
  in behind the playhead. Rendering always waits for the map to settle,
  whatever the preview does. Set `previewGate="exact"` to preview at final
  quality.
* **Studio cannot host interactive map UI.** Its preview overlays consume
  pointer events before a composition sees them, so buttons and map gestures
  inside a composition receive nothing. Interactive shot composing runs as a
  separate page (`npm run rig`) that writes a JSON file a composition loads;
  tweaks belong in the props panel via a zod `schema`.
* **Manifests are prepared before mounting.** Every `<om-map>` gains the
  recording switch, `<script>` tags are removed (they never execute under
  `innerHTML`, and a second OnlyMap runtime would fail deck.gl's
  duplicate-version check), and `loop` is stripped. Each warns once.
* **Concurrency turns over.** Measured on a basemap scene: `2` → 1.66×,
  `4` → 1.90×, `8` → **slower than 4**. Use `--concurrency 2`; every worker is
  a browser tab with a cold tile cache, so start at `1` on metered providers.

## Verified, not asserted

The determinism claim is enforced by a render suite that boots a real browser:
the same frame rendered twice in separate processes must be byte-identical, and
a frame rendered out of order must equal the same frame rendered cold. A
cross-check renders the same manifest through `onlymapjs record` and through the
plugin and compares them — currently 0.9999 structural similarity at aligned
story time, across two different Chromium and GL stacks.

## Reference

* The package ships `llms.txt` (the complete agent-facing reference) and an
  installable agent skill — both inside the npm tarball.
* Peers: `@nika-js/onlymap` at an exact version (it bundles deck.gl, which
  fails on duplicate versions), `remotion` ≥ 4.0.342, React ≥ 18. `zod` is
  optional, for props-panel schemas.
* Licensing: free for non-commercial use provided the in-frame OnlyMap
  attribution survives into the output; commercial use needs a key. Remotion
  and OnlyMap JS carry their own separate terms — see
  [Licensing & Telemetry](/onlymap/licensing-and-telemetry).