MapLibre Preview

A Ruby gem providing development tools for MapLibre GL JS styles with advanced filtering, terrain visualization, and performance monitoring capabilities. Designed for seamless integration into Sinatra applications.

• Advanced Layer Filtering: Metadata-driven layer filtering with support for complex filter expressions
• Terrain Visualization: Full terrain support with elevation profiles and contour line generation
• Performance Monitoring: Real-time FPS, memory usage, and tile loading metrics
• Interactive Debugging: Hover and click modes for feature inspection
• Sinatra Integration: Seamless integration as Sinatra extension with helper methods
• Static Asset Serving: Built-in middleware for serving JavaScript modules without conflicts

The gem consists of several integrated components:

• Main Module - Core gem functionality including Sinatra extension, Rack middleware, helper methods, and standalone application
• Slim Templates - HTML templates for map interface
• JavaScript Modules - Client-side filtering and terrain logic

1. Sinatra Integration → Register extension → Configure options → Use helpers
2. Asset Serving → StaticMiddleware intercepts /js/* requests → Serves from gem
3. Map Rendering → Helper methods render Slim templates → Include external dependencies
4. Client Interaction → JavaScript modules handle filtering and terrain features

Add to your Gemfile:

gem 'maplibre-preview'

Then run:

bundle install

require 'maplibre-preview'

class MyApp < Sinatra::Base
  register MapLibrePreview::Extension
  
  get '/map' do
    render_maplibre_preview
  end
end

There are several ways to pass a style URL to the map:

1. Via URL parameter:

http://localhost:9292/map?style_url=https://example.com/style.json

2. Via route parameter:

get '/map' do
  params[:style_url] = 'https://example.com/style.json'
  render_maplibre_preview
end

3. Via source parameter:

http://localhost:9292/map?source=Example_Style

The gem includes a complete Sinatra application for testing and development:

require 'maplibre-preview'

# Run standalone development server
MapLibrePreview::App.run!

This starts a complete web server with:

• Map interface at http://localhost:4567/map
• JavaScript assets served from /js/*
• All gem functionality available out of the box

How to use with a style:

• Pass style URL as parameter: http://localhost:4567/map?style_url=https://example.com/style.json

Without a style:

• Shows only basemap tiles (OpenStreetMap)
• Useful for testing basic functionality
• No custom layers or styling

Use cases:

• Quick testing of gem functionality
• Development and debugging
• Demonstrating capabilities

The gem uses fixed configurations for optimal compatibility:

• Map Center: [35.15, 47.41]
• Initial Zoom: 2
• Basemap: OpenStreetMap tiles with 0.8 opacity
• Library Versions: MapLibre GL JS 5.7.3, MapLibre Contour 0.1.0, D3.js 7

Style URL: Pass via URL parameter ?style_url=https://example.com/style.json

# Register the extension
register MapLibrePreview::Extension

# Available routes
GET /map          # Main map development interface
GET /js/:file     # JavaScript asset serving

The gem supports advanced filtering through style metadata:

{
  "metadata": {
    "filters": {
      "buildings": [
        {
          "id": "residential",
          "filter": ["==", ["get", "type"], "residential"]
        },
        {
          "id": "commercial", 
          "filter": ["==", ["get", "type"], "commercial"]
        }
      ]
    },
    "locale": {
      "en": {
        "buildings": "Buildings",
        "residential": "Residential",
        "commercial": "Commercial"
      }
    }
  }
}

For terrain visualization, add terrain configuration to your style:

{
  "terrain": {
    "source": "terrain-source"
  },
  "sources": {
    "terrain-source": {
      "type": "raster-dem",
      "tiles": ["https://your-terrain-tiles/{z}/{x}/{y}.png"],
      "encoding": "terrarium"
    }
  }
}

The gem includes real-time performance monitoring:

• FPS and Frame Time: Real-time rendering performance
• Memory Usage: JavaScript heap memory monitoring
• Tile Loading: Active tile count and loading status
• Layer Management: Active layer count and visibility
• Zoom Level: Current map zoom level
• Terrain Status: Terrain data availability

lib/
├── maplibre-preview.rb          # Main gem module and Sinatra integration
└── maplibre-preview/
    ├── version.rb                # Gem version
    ├── views/                    # Slim templates
    │   ├── map.slim             # Main map interface
    │   └── map_layout.slim      # HTML layout
    └── public/js/               # JavaScript modules
        ├── filters.js           # Layer filtering logic
        └── contour.js           # Terrain and contour features

• Ruby 2.7+
• Sinatra 2.1+
• Slim 4.1+
• Rack 2.0+

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run RuboCop
bundle exec rubocop

# Build gem
gem build maplibre-preview.gemspec

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/maplibre_preview_spec.rb

class MyApp < Sinatra::Base
  register MapLibrePreview::Extension
  
  get '/map' do
    render_maplibre_preview
  end
end

class MyApp < Sinatra::Base
  register MapLibrePreview::Extension
  
  get '/map' do
    # Style URL passed via params[:style_url]
    render_maplibre_preview
  end
end

class MyApp < Sinatra::Base
  register MapLibrePreview::Extension
  
  get '/map' do
    # Uses params[:style_url] if provided
    render_maplibre_preview
  end
  
  get '/terrain' do
    # Set style URL via params
    params[:style_url] = 'https://example.com/terrain-style.json'
    render_maplibre_preview
  end
end

This project is licensed under the MIT License - see the LICENSE file for details.