> ## Documentation Index
> Fetch the complete documentation index at: https://docs-beta.rebase.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Layers

> Create interactive map and weather visualizations with unified DeckGL layers and customizable styling

## Understanding layers

Layers are the building blocks of your interactive energy visualizations. They transform your geospatial and weather data into stunning visual representations on interactive maps. The Rebase Dashboard API uses a unified layer system that consolidates both map layers and weather layers into a single, flexible structure using DeckGL for powerful, performant rendering.

## Layer structure

The API uses a unified layer structure with type discrimination:

```typescript theme={null}
// Base Layer (common properties)
interface BaseLayer {
  id: string;
  user_id: string;
  name: string;
  deckgl_props?: object;
  ui_config?: UiConfig;
  created_at?: string;
  updated_at?: string;
}

// Weather Layer (extends BaseLayer)
interface WeatherLayer extends BaseLayer {
  type: "wl:RasterLayer" | "wl:ParticleLayer" | "wl:IsolineLayer";
  weather_model_id: string;
  variable: string;
  altitude: number;
  run_hour?: number;
  run_day?: string;
}

// Map Layer (extends BaseLayer)
interface MapLayer extends BaseLayer {
  type: "ScatterPlotLayer" | "GeoJsonLayer";
  dataset_id: string;
}

// Unified Layer Type
type Layer = WeatherLayer | MapLayer;
```

## Layer types

The `type` field acts as a discriminator that determines which layer model to use:

* **Weather layers**: `type` starts with `"wl:"` (e.g., `"wl:RasterLayer"`)
* **Map layers**: `type` doesn't start with `"wl:"` (e.g., `"ScatterPlotLayer"`)

The API automatically validates required fields based on the layer type.

### Map Layer Types

#### ScatterPlotLayer

Perfect for visualizing point data like wind turbines, solar panels, or power plants.

```python theme={null}
# Create a scatterplot layer for wind turbines
wind_turbines_layer = client.layers.create_layer(
    name="Wind Turbines",
    type="ScatterPlotLayer",
    dataset_id=geospatial_dataset.id,
    deckgl_props={
        "radiusScale": 1000,
        "radiusMinPixels": 3,
        "radiusMaxPixels": 15,
        "getFillColor": [0, 255, 0],
        "getLineColor": [0, 200, 0],
        "lineWidthMinPixels": 1,
        "pickable": True,
        "stroked": True
    }
)
```

**Key properties:**

* `radiusScale`: Scale factor for point sizes
* `radiusMinPixels`/`radiusMaxPixels`: Min/max size constraints
* `getFillColor`: Fill color for each point
* `getLineColor`: Border color for each point
* `pickable`: Enable click interactions
* `stroked`: Enable borders

#### GeoJsonLayer

For complex geometries like wind farm boundaries, transmission lines, or service areas.

```python theme={null}
# Create a GeoJSON layer for wind farm boundaries
geojson_layer = client.layers.create_layer(
    name="Wind Farm Boundaries",
    type="GeoJsonLayer",
    dataset_id=boundaries_dataset.id,
    deckgl_props={
        "getFillColor": [0, 100, 255, 100],
        "getLineColor": [0, 100, 255],
        "lineWidthMinPixels": 2,
        "opacity": 0.6,
        "stroked": True,
        "filled": True,
        "extruded": False
    }
)
```

**Key properties:**

* `getFillColor`: Fill color for polygons
* `getLineColor`: Border color for geometries
* `lineWidthMinPixels`: Border thickness
* `extruded`: Enable 3D extrusion for height data

### Weather Layer Types

#### wl:RasterLayer

Raster-based weather data visualization for wind speed, temperature, precipitation, etc.

```python theme={null}
# Create a raster weather layer for wind speed
wind_speed_layer = client.layers.create_layer(
    name="Wind Speed at 10m",
    type="wl:RasterLayer",
    weather_model_id="ECMWF_IFS",
    variable="WindSpeed",
    altitude=10,
    run_hour=12,
    run_day="2025-01-15",
    deckgl_props={
        "opacity": 0.7
    }
)
```

#### wl:ParticleLayer

Particle-based weather visualization for wind flow, air currents, etc.

```python theme={null}
# Create a particle layer for wind flow
wind_flow_layer = client.layers.create_layer(
    name="Wind Flow Particles",
    type="wl:ParticleLayer",
    weather_model_id="ECMWF_IFS",
    variable="WindSpeed",
    altitude=10,
    run_hour=12,
    run_day="2025-01-15",
    deckgl_props={
        "opacity": 0.8,
        "particleCount": 1000
    }
)
```

#### wl:IsolineLayer

Contour/isoline weather visualization for pressure, temperature gradients, etc.

```python theme={null}
# Create an isoline layer for pressure
pressure_layer = client.layers.create_layer(
    name="Atmospheric Pressure",
    type="wl:IsolineLayer",
    weather_model_id="ECMWF_IFS",
    variable="Pressure",
    altitude=0,
    run_hour=12,
    run_day="2025-01-15",
    deckgl_props={
        "opacity": 0.6,
        "contourInterval": 2
    }
)
```

### Other DeckGL Layer Types

You can use any DeckGL layer type by specifying it as a string. The API will pass the `deckgl_props` directly to the specified layer type.

```python theme={null}
# Example with a custom DeckGL layer type
custom_layer = client.layers.create_layer(
    name="Custom Layer",
    type="YourDeckGLLayerType",  # Any valid DeckGL layer type
    dataset_id=dataset.id,
    deckgl_props={
        # Properties specific to your layer type
    }
)
```

## Advanced layer features

### Dynamic styling

Make your layers respond to data properties:

```python theme={null}
# Dynamic styling based on turbine status
dynamic_scatterplot = client.layers.create_layer(
    name="Dynamic Wind Turbines",
    type="ScatterPlotLayer",
    dataset_id=turbines_dataset.id,
    deckgl_props={
        "radiusScale": 500,
        "radiusMinPixels": 5,
        "radiusMaxPixels": 25,
        "getFillColor": [
            "case",
            ["==", ["get", "status"], "operational"], [0, 255, 0],
            ["==", ["get", "status"], "maintenance"], [255, 165, 0],
            ["==", ["get", "status"], "offline"], [255, 0, 0],
            [128, 128, 128]  # Default gray
        ],
        "getLineColor": [0, 0, 0],
        "pickable": True,
        "stroked": True
    }
)
```

### UI Configuration

Add interactive controls for layer properties:

```python theme={null}
# Layer with UI controls
ui_controlled_layer = client.layers.create_layer(
    name="Interactive Layer",
    type="ScatterPlotLayer",
    dataset_id=dataset.id,
    deckgl_props={
        "radiusScale": 1000,
        "getFillColor": [0, 255, 0],
        "opacity": 0.8
    },
    ui_config={
        "controls": {
            "size_control": {
                "property": "radiusScale",
                "type": "slider",
                "default": 1000,
                "range": [100, 2000],
                "label": "Point Size"
            },
            "opacity_control": {
                "property": "opacity",
                "type": "slider",
                "default": 0.8,
                "range": [0, 1],
                "label": "Opacity"
            },
            "color_control": {
                "property": "getFillColor",
                "type": "colorScheme",
                "default": [0, 255, 0],
                "label": "Point Color"
            }
        }
    }
)
```

## Layer management

### Creating layers

```python theme={null}
# Create a new map layer
map_layer = client.layers.create_layer(
    name="My Custom Layer",
    type="ScatterPlotLayer",
    dataset_id=dataset.id,
    deckgl_props={
        # Your layer properties here
    }
)

# Create a new weather layer
weather_layer = client.layers.create_layer(
    name="Wind Speed Layer",
    type="wl:RasterLayer",
    weather_model_id="ECMWF_IFS",
    variable="WindSpeed",
    altitude=10,
    run_hour=12,
    run_day="2025-01-15",
    deckgl_props={
        "opacity": 0.7
    }
)
```

### Updating layers

```python theme={null}
# Update layer properties (all parameters required)
updated_layer = client.layers.update_layer(
    layer_id,
    name="Updated Layer Name",
    type="ScatterPlotLayer",  # Required
    dataset_id=dataset.id,    # Required for map layers
    deckgl_props={
        "radiusScale": 1500,
        "getFillColor": [255, 0, 0]
    }
)

# Update weather layer
updated_weather_layer = client.layers.update_layer(
    weather_layer_id,
    name="Updated Weather Layer",
    type="wl:RasterLayer",  # Required
    weather_model_id="ECMWF_IFS",  # Required for weather layers
    variable="WindSpeed",  # Required for weather layers
    altitude=10,  # Required for weather layers
    deckgl_props={
        "opacity": 0.8
    }
)
```

### Retrieving layers

```python theme={null}
# Get all layers (both map and weather)
all_layers = client.layers.list_layers()

# Filter by type if needed
weather_layers = [layer for layer in all_layers if layer.type.startswith('wl:')]
map_layers = [layer for layer in all_layers if not layer.type.startswith('wl:')]

# Get a specific layer
layer = client.layers.get_layer(layer_id)
```

### Deleting layers

```python theme={null}
# Delete a layer (use with caution!)
client.layers.delete_layer(layer_id)
```

## Component integration

### Creating map components with unified layers

```python theme={null}
# Create a map component with both map and weather layers
map_component = client.components.create_map(
    name="My Map",
    config={"latitude": 55.6761, "longitude": 9.5018, "zoom": 6},
    layer_ids=[map_layer.id, weather_layer.id]  # All layer types in one array
)
```

## Layer type reference

### Weather Layer Types

| Type               | Description                           | Required Fields                            |
| ------------------ | ------------------------------------- | ------------------------------------------ |
| `wl:RasterLayer`   | Raster weather data visualization     | `weather_model_id`, `variable`, `altitude` |
| `wl:ParticleLayer` | Particle-based weather visualization  | `weather_model_id`, `variable`, `altitude` |
| `wl:IsolineLayer`  | Contour/isoline weather visualization | `weather_model_id`, `variable`, `altitude` |

### Map Layer Types

| Type               | Description                 | Required Fields |
| ------------------ | --------------------------- | --------------- |
| `ScatterPlotLayer` | Point-based geospatial data | `dataset_id`    |
| `GeoJsonLayer`     | GeoJSON polygon/line data   | `dataset_id`    |

## Important Limitations

* **Layer ordering**: Z-index and layer stacking order is not supported
* **Interactive events**: onClick handlers and tooltips are not implemented
* **Layer types**: Any DeckGL layer type can be used, but not all may work as expected
* **Updates**: All parameters (name, type, dataset\_id/weather\_model\_id) are required when updating layers
* **UI controls**: Only basic property controls (slider, colorScheme, toggle, dropdown) are supported

## Best practices

### Performance optimization

* Use appropriate layer types for your data
* Limit the number of points in large datasets
* Use data filtering to show relevant subsets
* Consider using clustering for dense point data

### Visual design

* Choose colors that work well together
* Use opacity to show overlapping data
* Provide clear visual hierarchy
* Include legends for clarity

### User experience

* Add interactive controls for layer properties using `ui_config`
* Use consistent styling across related layers
* Test layer performance with your actual data
* Validate that your chosen DeckGL layer type works as expected

## Next steps

Now that you understand layers, learn how to combine them:

<CardGroup cols={2}>
  <Card title="Map Components" icon="map" href="/essentials/components">
    Combine multiple layers into interactive map components.
  </Card>

  <Card title="Weather Integration" icon="cloud" href="/essentials/weather-integration">
    Learn more about weather data integration.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all layer endpoints and options.
  </Card>
</CardGroup>