ضع خمسين ألف نقطة على خريطة وستتوقف عن رؤية البيانات. تتراكم العلامات فوق بعضها، وتتحول المناطق الكثيفة إلى بقعة واحدة مصمتة، ولا تستطيع أن تعرف إن كان الموضع يحمل عشر نقاط أم عشرة آلاف. الحل المعروف هو التوقف عن رسم النقاط ورسم خلايا بدلها: قسّم الخريطة إلى شبكة، عُدّ ما يقع في كل خلية، ثم لوّن الخلايا.
الفكرة سهلة القول، لكن فيها أجزاء متحركة أكثر مما توقعت. أي شبكة؟ كيف تلوّن قيمًا تمتد على عدة مراتب عشرية؟ وماذا يحدث لخلية تعبر خط الطول 180°؟ hexbin-heatmap هو المشروع الذي اشتغلت فيه على هذه الأسئلة.
يجمّع المشروع بيانات النقاط (CSV أو GeoJSON) في سداسيات H3 أو خلايا geohash، ويعرض النتيجة كخريطة حرارية ملوّنة (choropleth) في MapLibre، مع شريط تمرير للدقة (resolution). والتجميع نفسه متاح كأداة سطر أوامر (CLI) تكتب GeoJSON أو CSV.
ماذا يقدّم
تطبيق ويب. افتح ملف CSV/TSV أو ملف GeoJSON فيه عناصر Point أو MultiPoint. الملفات تُقرأ محليًّا ولا تُرفع أبدًا. في ملفات CSV، يُكتشف عمودا خط العرض وخط الطول تلقائيًّا (lat و latitude و y و lon و lng و longitude و x وغيرها)، والفاصل يمكن أن يكون , أو ; أو tab أو |.
طريقتان للتقسيم. اختر H3 (دقة من 0 إلى 15) أو geohash (دقة من 1 إلى 12) بشريط التمرير، أو فعّل "follow map zoom" لتتغير الدقة مع التكبير.
التلوين حسب ما يهمك. لوّن حسب count، أو حسب sum أو mean لعمود وزن رقمي. الفئات يمكن أن تكون log أو quantile أو linear، مع 4 تدرجات لونية.
الفحص والتصدير. مرّر المؤشر فوق خلية لترى إحصاءاتها، وصدّر الخلايا الظاهرة كـ GeoJSON.
أداة CLI بنفس المحرك. أداة سطر الأوامر تشغّل كود التجميع نفسه وتكتب GeoJSON أو CSV. كل عنصر في المخرجات يحمل الخصائص cell و count و sum و mean، ومعرّفه هو معرّف الخلية.
طريقة الاستعمال
تطبيق الويب لا يحتاج تثبيتًا. النسخة التجريبية موقع ثابت على GitHub Pages، وملفاتك تبقى في المتصفح: https://abdeldjalilchougui.github.io/hexbin-heatmap/
لتشغيله محليًّا، أو استضافة نسختك، أو استعمال الـ CLI:
git clone https://github.com/AbdeldjalilChougui/hexbin-heatmap.git cd hexbin-heatmap pnpm install pnpm dev # web app: click "Sample data" or open your own file pnpm test # vitest pnpm build # CLI -> dist/cli, web app -> dist/web بناء الإنتاج يستعمل مسار Vite الأساسي /hexbin-heatmap/ (انظر vite.config.ts). غيّره إذا كنت تقدّم الموقع من مسار آخر.
الـ CLI على ملف العيّنة المرفق:
pnpm cli samples/points.csv --res 5 --weight value -o cells.geojson pnpm cli samples/points.csv --mode geohash --res 4 --format csv --min-count 10 cat points.geojson | node dist/cli/index.js - -r 8 # after pnpm build وخياراته:
-m, --mode <h3|geohash> binning scheme (default h3) -r, --res <n> H3 resolution 0-15 or geohash precision 1-12 (default 7 / 5) -w, --weight <name> numeric CSV column / GeoJSON property to sum --lat / --lon <name> explicit coordinate columns --min-count <n> drop sparse cells -f, --format <geojson|csv> output format -o, --out <file> output file (default stdout) ما بنيته من الصفر
كل المنطق موجود في src/lib/، بـ TypeScript صرف يتشاركه الـ CLI وتطبيق الويب:
src/lib/ pure TypeScript, shared by the CLI and the web app csv.ts RFC 4180 splitter, delimiter sniffing, column detection, bad-row skipping geojson.ts Point / MultiPoint / GeometryCollection extraction, weights from properties geohash.ts geohash encode/decode/bounds written from scratch aggregate.ts point -> cell id (h3-js latLngToCell or geohash), count/sum/mean per cell, cell polygons polygon.ts antimeridian handling: split rings into a MultiPolygon at ±180° color.ts ramps, linear/quantile/log class breaks, value -> colour src/cli/ node:util parseArgs CLI src/web/ MapLibre UI; colours via a "step" expression built from the class breaks H3 نفسه يأتي من h3-js؛ لم أُعِد كتابته. ما كتبته يدويًّا هو ترميز geohash وفكّه، وقارئ CSV مع اكتشاف الفاصل، ومنطق حدود الفئات، وقسمة الخلايا عند خط الطول 180° (antimeridian).
التجميع مرور واحد على النقاط باستعمال Map<cell, {count, sum}>. الخلايا تخرج مرتبة حسب المعرّف، فالنتائج حتمية (deterministic): الإدخال نفسه يعطي دائمًا الملف نفسه. مضلعات الخلايا تأتي من cellToBoundary في H3 أو من الصندوق المحيط في geohash، على شكل حلقات مغلقة من [lon, lat].
ما تعلّمته
الشبكة اختيار له نتائج. خلايا geohash مستطيلات بخطوط العرض والطول، فمساحتها تتغير مع خط العرض. أما خلايا H3 فمتقاربة المساحة. إذا قارنت الأعداد بين خلايا متباعدة في خط العرض، يصبح هذا الفرق مهمًّا. كتابة geohash من الصفر جعلت الأمر واضحًا: الخلية مجرد مجال من خطوط العرض ومجال من خطوط الطول، لا أكثر.
سلّم الألوان يحدد ما تراه. بيانات النقاط في العادة غير متوازنة أبدًا: خلايا قليلة تحمل أغلب النقاط. مع الفئات الخطية (linear)، تقع كل الخلايا تقريبًا في أدنى فئة. فئات quantile تساعد، لكن حدودها المكررة تُحذف، فالبيانات كثيرة التساوي (مثلًا أغلب الخلايا عددها 1) قد تعطي فئات أقل مما طلبت. ولهذا السبب كان السلّم اللوغاريتمي (log) هو الافتراضي.
خط الطول 180° حالة حدّية حقيقية. خلية H3 التي تمتد على جانبي ±180° لها حلقة تقفز خطوط طولها من طرف العالم إلى الطرف الآخر. إذا تُركت كما هي، رُسم مضلع يعبر الخريطة كلها. المشروع يقسم هذه الحلقات إلى MultiPolygon عند هذا الخط ليبقى الـ GeoJSON صالحًا وفق RFC 7946.
مكتبة واحدة وواجهتان. لأن src/lib/ لا يعرف شيئًا عن المتصفح ولا عن الطرفية، لا يمكن أن يتباعد الـ CLI وتطبيق الويب. وفي تطبيق الويب، تأتي الألوان من تعبير "step" في MapLibre مبني من حدود الفئات، فتستعمل الخريطة والمفتاح الأرقام نفسها.
الحل بالقوة الغاشمة مرجع جيد للاختبار. الأمر pnpm test يشغّل 22 اختبارًا:
- geohash مقابل قيم مرجعية منشورة، مع اختبار أن فكّ الترميز يعطي خلية تحتوي النقطة
- التجميع مقابل تجميع بالقوة الغاشمة (brute force) على 3,000 نقطة عشوائية لـ H3 و geohash، مع بقاء مجموع الأوزان محفوظًا
- شكل خلية H3 وترتيبها، والقسمة عند antimeridian، والتحقق من الدقة
- علامات الاقتباس في CSV، والفواصل، واكتشاف الأعمدة، والأسطر الخاطئة؛ وأوزان GeoJSON والأشكال المتجاهَلة
- حدود الفئات والتصنيف
- الـ CLI من البداية إلى النهاية على ملفات مؤقتة
أشياء يجب معرفتها
- كل شيء يعمل في الذاكرة. مئات الآلاف من النقاط لا مشكلة فيها، أما عشرات الملايين فلا.
- فئات quantile قد تخرج أقل من المطلوب مع البيانات كثيرة التساوي، كما ذُكر أعلاه.
- مساحة خلية geohash تتغير مع خط العرض. استعمل H3 عندما تحتاج خلايا متقاربة الحجم.
- الخريطة الأساسية من tile.openstreetmap.org، وهي للاستعمال الشخصي الخفيف فقط حسب سياسة بلاطات OSM.
- الملف
samples/points.csv(ونسخته فيpublic/) بيانات اصطناعية ينتجهاpnpm gen:sample: تجمعات غاوسية حول إحداثيات تقريبية لمدن جزائرية مع ضجيج منتظم. لا تمثّل أي قياس حقيقي.
لماذا بنيته
كومة النقاط تخفي نمطها، والتجميع في خلايا هو المخرج المعتاد. أردت أن أفهم المسار كاملًا من ملف CSV خام إلى خلية ملوّنة، لا أن أستدعي طبقة جاهزة فقط: كيف تصبح النقطة معرّف خلية، وكيف يغيّر اختيار الشبكة الصورة، وكيف تغيّرها حدود الفئات مرة أخرى. ووجود الكود نفسه خلف صفحة ويب وخلف CLI يعني أن الصورة التي تستكشفها في المتصفح يمكن إعادة إنتاجها كملف بواسطة سكربت.
احصل على الكود
الكود المصدري والاختبارات والعيّنة الاصطناعية على GitHub: https://github.com/AbdeldjalilChougui/hexbin-heatmap. الكود برخصة MIT. مكتبة H3 حقوقها لـ Uber Technologies (Apache-2.0، عبر h3-js)، وبيانات الخريطة © مساهمو OpenStreetMap (ODbL). الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.
نُشر في الأصل على abdeldjalilchougui.biz.