DEV Community

Cover image for pmtiles_provider: خرائط raster بلا إنترنت في flutter_map من ملف PMTiles واحد
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

pmtiles_provider: خرائط raster بلا إنترنت في flutter_map من ملف PMTiles واحد

الخريطة التي تعمل بلا إنترنت (offline) تعني عادةً مجلدًا فيه آلاف الصور الصغيرة (البلاطات، tiles)، أو خادم بلاطات عليك تشغيله. PMTiles فكرة أبسط: الخريطة كلها ملف واحد، في أوله فهرس يقول أين توجد كل بلاطة. القارئ يحتاج فقط الترويسة (header)، وبعض الفهارس (directories)، والبلاطات الظاهرة على الشاشة. والملف نفسه يمكن أن يكون في تخزين الهاتف، أو على استضافة ثابتة عادية يجلب منها القارئ مقاطع من البايتات عبر HTTP.

pmtiles_provider تجلب هذا إلى flutter_map. هي TileProvider لأرشيفات PMTiles v3 من نوع raster. تعرض خريطة من ملف واحد بلا إنترنت، من ملف أو asset أو من الذاكرة، أو تبثّها من أي استضافة ثابتة عبر HTTP range requests.

شيء يجب قوله من البداية: الحزمة ترسم بلاطات raster فقط (PNG و JPEG و WebP). ليست محرّك رسم للبلاطات المتجهة (vector tiles). فتح أرشيف MVT يفشل بخطأ واضح يوجّهك إلى محرّك vector.

ماذا تقدّم

أربعة مصادر. PmTilesProvider.fromFile و.fromBytes و.fromAsset و.fromUrl. مع الملفات، القراءة عشوائية (random access): لا يُقرأ إلا الترويسة والفهارس والبلاطات الظاهرة. والوصول إلى الملفات موضوع خلف conditional import، فالحزمة تُبنى للويب أيضًا.

طلبات HTTP range مع كشف التغيّر. fromUrl ترسل طلبات Range وتتابع ETag وLast-Modified وحجم الأرشيف. إذا استُبدل الأرشيف على الخادم في منتصف الجلسة، يُكتشف التغيّر، وتُفرَّغ الـ caches، ويُعاد الطلب، ويُطلق provider.changes حدثًا حتى يعيد TileLayer.reset تحميل البلاطات القديمة.

الـ caches. هناك LRU cache للفهارس الفرعية (leaf directories) بالعدد، وآخر لبايتات البلاطات بالحجم. الحجمان قابلان للضبط. والترويسة مع الفهرس الجذري تأتيان من قراءة واحدة بحجم 16 KiB.

البيانات الوصفية (metadata). provider.info() تعطي حدود الأرشيف، ومركزه، وأدنى وأقصى zoom، ونوع البلاطات، والاسم، والـ attribution. وinfo.mapOptions() تبني MapOptions منها، فتُفتح الخريطة على المكان الصحيح.

البلاطات المفقودة. البلاطة المفقودة يمكن أن تكون شفافة، أو خطأ (فتظهر TileLayer.errorImage)، أو overzoom: تُقصّ أقرب بلاطة من مستوى أعلى وتُكبَّر. الـ overzoom يملأ أيضًا مستويات zoom الأعمق من أقصى zoom في الأرشيف.

الإلغاء. البلاطة التي تخرج من الشاشة تُلغي قراءتها المعلّقة. والقراءات المشتركة بين عدة بلاطات لا تُلغى إلا إذا ألغت كل البلاطات المنتظرة.

قارئ مكتوب من المواصفة. قارئ PMTiles v3 يغطي الترويسة، وفهارس varint و delta، والـ run lengths، والفهارس الفرعية، ومعرّفات Hilbert TileID، وضغط gzip.

طريقة الاستعمال

أضِفها من GitHub، مع flutter_map و latlong2:

dependencies:
  flutter_map: ^8.0.0
  latlong2: ^0.9.1
  pmtiles_provider:
    git: https://github.com/AbdeldjalilChougui/pmtiles_provider
Enter fullscreen mode Exit fullscreen mode

ثم أعطِ المزوّد لـ TileLayer:

import 'package:flutter/material.dart';
import 'package:flutter_map/flutter_map.dart';
import 'package:pmtiles_provider/pmtiles_provider.dart';

class OfflineMap extends StatefulWidget {
  const OfflineMap({super.key, required this.path});
  final String path;

  @override
  State<OfflineMap> createState() => _OfflineMapState();
}

class _OfflineMapState extends State<OfflineMap> {
  late final provider = PmTilesProvider.fromFile(
    widget.path,
    missingTile: const MissingTileBehavior.overzoom(),
  );
  late final info = provider.info();

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<PmTilesInfo>(
      future: info,
      builder: (context, snapshot) {
        final info = snapshot.data;
        if (info == null) return const SizedBox();
        return FlutterMap(
          options: info.mapOptions(), // center, zoom, bounds from the archive
          children: [
            TileLayer(
              tileProvider: provider,
              reset: provider.changes,
              userAgentPackageName: 'com.example.app',
            ),
          ],
        );
      },
    );
  }
}
Enter fullscreen mode Exit fullscreen mode

المصادر الأخرى تُكتب هكذا:

PmTilesProvider.fromUrl('https://cdn.example.com/region.pmtiles');
PmTilesProvider.fromAsset('assets/region.pmtiles'); // loaded into memory
PmTilesProvider.fromBytes(bytes);
Enter fullscreen mode Exit fullscreen mode

كل constructor يقبل أحجام الـ cache: directoryCacheSize: 64 وtileCacheBytes: 8 * 1024 * 1024.

يمكنك فحص الأرشيف قبل عرض الخريطة. provider.validate() ترمي PmTilesTileTypeException إذا كان الأرشيف يحتوي بلاطات vector.

الحصول على أرشيف

الـ README يشرح مسار العمل offline بأداة pmtiles من مشروع go-pmtiles. إما أن تحوّل ملف MBTiles من نوع raster صنعته بـ QGIS أو GDAL أو أدوات مشابهة، أو تقتطع منطقة ونطاق zoom من أرشيف raster أكبر:

pmtiles convert my_raster.mbtiles my_raster.pmtiles

pmtiles extract https://example.com/world_raster.pmtiles algiers.pmtiles \
  --bbox=2.8,36.6,3.3,36.85 --maxzoom=14
pmtiles show algiers.pmtiles   # check "tile type: png|jpg|webp"
Enter fullscreen mode Exit fullscreen mode

الأرشيف الذي تقتطع منه يجب أن يكون raster. خرائط Protomaps الأساسية من نوع vector (MVT)، وهذه تحتاج محرّك vector.

الأرشيف الصغير يمكن تضمينه كـ asset في Flutter وفتحه بـ fromAsset. حزم الـ assets لا تدعم القراءة العشوائية، فيُقرأ الـ asset كله إلى الذاكرة. للأرشيفات الأكبر من بضعة ميغابايتات، يبيّن الـ README كيف تنسخ الـ asset إلى ملف مرة واحدة، أو تحمّله إلى مجلد المستندات، ثم تستعمل fromFile.

الاستضافة لـ fromUrl

أي استضافة ثابتة تدعم range requests تصلح: S3 و R2 و GCS و nginx و GitHub Pages. على الويب، يجب أن تسمح سياسة CORS في الخادم بترويسة الطلب Range، وأن تكشف ETag وContent-Range. أول طلب يجلب البايتات 0-16383، والطلبات التالية تجلب فهرسًا فرعيًا واحدًا أو بلاطة واحدة في كل مرة. الخادم الذي يتجاهل Range ويجيب بـ 200 يعمل أيضًا، لكن كل طلب عندها يحمّل الملف كاملًا.

ما يجب معرفته

  • raster فقط. PNG و JPEG و WebP، مع نوع البلاطات "unknown" الذي يُمرَّر إلى مفكّك الصور في Flutter. أرشيفات MVT و MLT و AVIF مرفوضة.
  • الضغط. المدعوم هو gzip أو بلا ضغط. أرشيفات brotli أو zstd ترمي PmTilesUnsupportedException، وعليك إعادة ترميزها بـ gzip.
  • الـ zoom. معرّفات TileID دقيقة حتى zoom 26، وهو أقصى ما يتسع له عدد صحيح آمن على الويب.
  • الويب. fromFile غير متاحة على الويب وترمي UnsupportedError. وfromAsset وfromBytes تُبقيان الأرشيف كله في الذاكرة.
  • كشف التغيّر يعتمد على أن يرسل الخادم ETag قويًا، أو ترويسة Last-Modified، أو الحجم الكلي في Content-Range. الـ ETags الضعيفة تُتجاهل. البلاطات الظاهرة تبقى حتى تعيد الطبقة تحميلها، وهذا يحدث إذا مرّرت provider.changes إلى TileLayer.reset.
  • overzoom أم maxNativeZoom. إذا كنت تريد فقط تجاوز أقصى zoom في الأرشيف والأرشيف بلا ثغرات، فـ TileLayer(maxNativeZoom: info.maxZoom) تقوم بالتكبير داخل flutter_map وبتكلفة أقل. أما overzoom في المزوّد فيملأ الثغرات أيضًا، كما في المقتطعات التي تغطي مستوياتها العميقة جزءًا من المنطقة فقط.
  • ما تم اختباره. القارئ مختبَر مقابل جدول TileID الموجود في المواصفة نفسها، وكاتب مستقل خاص بالاختبارات، وأرشيف أنتجته أداة pmtiles الرسمية. السلوك مغطى باختبارات وحدة على الـ VM واختبارات widget مع flutter_map. لكنه لم يُتحقق منه بعد على جهاز حقيقي ولا في متصفح.

لماذا بنيتها

الـ README صريح في سبب كتابة قارئ جديد بدل الاعتماد على حزمة pmtiles الموجودة في Dart. تلك الحزمة قارئ سليم، لكنها تتطلب إصدار Dart SDK أحدث مما تدعمه هذه الحزمة، وقارئ الأرشيف وقارئ HTTP فيها يستوردان dart:io دون شرط (فالتطبيقات التي تستعملها لا تُبنى للويب)، وليس فيها ETag ولا كشف تغيّر، ولا إلغاء للطلبات، ولا cache للبلاطات، وتجلب اعتماديات لا يحتاجها مزوّد raster.

ومن جهة flutter_map كان هناك فراغ أيضًا: آخر إصدار لـ flutter_map_pmtiles كان في فبراير 2025. لذلك نفّذت الجزء الصغير الذي يحتاجه مزوّد raster من مواصفة v3، وبنيت المزوّد حول ما تواجهه خريطة على الهاتف: بلاطات تخرج من الشاشة قبل أن تُحمَّل، وأرشيفات فيها ثغرات، وملف يتغيّر على الخادم والتطبيق مفتوح. وعدا Flutter، الحزمة تعتمد فقط على flutter_map وhttp وlatlong2 وarchive (لضغط gzip بـ Dart خالص).

إذا كنت قادمًا من flutter_map_pmtiles، ففي الـ README جدول انتقال. باختصار: PmTilesTileProvider.fromSource(url) تصبح PmTilesProvider.fromUrl(url)، وهي متزامنة (synchronous)، فلا حاجة إلى FutureBuilder لمجرد إنشاء المزوّد.

الكود

الكود، ومسار العمل offline، وجدول الانتقال، والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/pmtiles_provider. الرخصة MIT، والـ issues والـ pull requests مرحّب بها.


نُشر في الأصل على abdeldjalilchougui.biz.

Top comments (0)