دوال للتعامل مع الإحداثيات الجغرافية

يحسب المسافة بين نقطتين على سطح الأرض باستخدام معادلة الدائرة العظمى.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

معلمات الإدخال

• lon1Deg — خط الطول النقطة الأولى بالدرجات. النطاق: [-180°, 180°].
• lat1Deg — خط العرض النقطة الأولى بالدرجات. النطاق: [-90°, 90°].
• lon2Deg — خط الطول النقطة الثانية بالدرجات. النطاق: [-180°, 180°].
• lat2Deg — خط العرض النقطة الثانية بالدرجات. النطاق: [-90°, 90°].

تشير القيم الموجبة إلى خط العرض شمالًا وخط الطول شرقًا، وتشير القيم السالبة إلى خط العرض جنوبًا وخط الطول غربًا.

القيمة المُعادة

المسافة بين نقطتين على سطح الأرض، بالمتر.

يُنشئ استثناءً عندما تقع قيم معلمات الإدخال خارج النطاق.

مثال

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance

┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

مشابهة لـ greatCircleDistance، لكنها تحسب المسافة على إهليلج WGS-84 بدلًا من الكرة. ويوفّر ذلك تقريبًا أدق لجيود الأرض. الأداء مماثل لأداء greatCircleDistance (من دون أي تراجع في الأداء). ويُوصى باستخدام geoDistance لحساب المسافات على الأرض.

ملاحظة تقنية: بالنسبة للنقاط المتقاربة بما يكفي، نحسب المسافة باستخدام تقريب مستوٍ وفق المترية على المستوى المماس عند منتصف الإحداثيات.

geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

معلمات الإدخال

• lon1Deg — خط الطول النقطة الأولى بالدرجات. النطاق: [-180°, 180°].
• lat1Deg — خط العرض النقطة الأولى بالدرجات. النطاق: [-90°, 90°].
• lon2Deg — خط الطول النقطة الثانية بالدرجات. النطاق: [-180°, 180°].
• lat2Deg — خط العرض النقطة الثانية بالدرجات. النطاق: [-90°, 90°].

تشير القيم الموجبة إلى خطوط العرض الشمالية وخطوط الطول الشرقية، وتشير القيم السالبة إلى خطوط العرض الجنوبية وخطوط الطول الغربية.

القيمة المعادة

المسافة بين نقطتين على سطح الأرض، بالمتر.

يتم إنشاء استثناء عندما تقع قيم معلمات الإدخال خارج هذا النطاق.

مثال

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance

┌─geoDistance─┐
│   212458.73 │
└─────────────┘

تحسب الزاوية المركزية بين نقطتين على سطح الأرض باستخدام معادلة الدائرة العظمى.

greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

معلمات الإدخال

• lon1Deg — خط الطول للنقطة الأولى، بالدرجات.
• lat1Deg — خط العرض للنقطة الأولى، بالدرجات.
• lon2Deg — خط الطول للنقطة الثانية، بالدرجات.
• lat2Deg — خط العرض للنقطة الثانية، بالدرجات.

القيمة المعادة

الزاوية المركزية بين نقطتين، بالدرجات.

مثال

SELECT greatCircleAngle(0, 0, 45, 0) AS arc

┌─arc─┐
│  45 │
└─────┘

يحوّل الإحداثيات الجغرافية وفق نظام WGS84 (longitude, latitude) إلى إحداثيات Universal Transverse Mercator (UTM).

UTM عبارة عن مجموعة من 60 إسقاط ميركاتور مستعرض، يغطي كلٌّ منها نطاقًا من خطوط الطول بعرض 6°، ويحوّل الإحداثيات الجغرافية إلى شبكة مستوية بوحدة المتر. يُحدَّد نطاق UTM تلقائيًا من خط الطول، مع تطبيق الاستثناءات القياسية الخاصة بـ Norway وSvalbard، ما لم تُحدَّد قيمة zone صراحةً. لا يُعرَّف UTM إلا لخطوط العرض ضمن النطاق [-80°, 84°]؛ أما المناطق القطبية فتستخدم نظام UPS المنفصل.

geoToUTM(longitude, latitude[, zone])

المعاملات

• longitude — خط الطول بالدرجات. النطاق: [-180°, 180°]. Float32/Float64.
• latitude — خط العرض بالدرجات. النطاق: [-80°, 84°]. Float32/Float64.
• zone — اختياري. يفرض الإسقاط على نطاق UTM هذا بدلًا من اختيارها تلقائيًا. النطاق: [1, 60]. (U)Int*.

القيمة المعادة

Tuple مسمّاة بالشكل (easting, northing, zone, band): تكون قيمتا easting وnorthing بالمتر (Float64)، ورقم zone الخاص بـ UTM (UInt8)، وحرف band لخط العرض في MGRS (FixedString(1)). وتشير قيمة band التي تساوي 'N' أو أي حرف يليه إلى نصف الكرة الشمالي.

يُنتج استثناءً عندما يكون خط العرض خارج [-80°, 84°] أو يكون خط الطول خارج [-180°, 180°].

مثال

SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower

(448251.5978370684,5411935.125629659,31,'U')

يحوّل إحداثيات UTM إلى الإحداثيات الجغرافية وفق WGS84 (خط الطول، خط العرض). وهذه هي الدالة العكسية لـ geoToUTM.

UTMToGeo(easting, northing, zone, is_north)

الوسيطات

• easting — الإحداثي الشرقي بالأمتار (يتضمن الإزاحة الشرقية الكاذبة بمقدار 500000 م). (U)Int*/Float*.
• northing — الإحداثي الشمالي بالأمتار (يتضمن الإزاحة الشمالية الكاذبة بمقدار 10000000 م في نصف الكرة الجنوبي). (U)Int*/Float*.
• zone — رقم نطاق UTM. المدى: [1, 60]. (U)Int*.
• is_north — نصف الكرة الأرضية: 1 للنصف الشمالي و0 للنصف الجنوبي. (U)Int*.

القيمة المعادة

Tuple مُسمّى بالشكل (longitude, latitude) بالدرجات. Tuple(Float64, Float64).

مثال

SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord;

(2.2944970289079203,48.85822204127082)

يحوِّل الإحداثيات الجغرافية وفق WGS84 (خط الطول، خط العرض) إلى سلسلة Military Grid Reference System (MGRS).

تكون السلسلة بالتنسيق <zone><band><100km square><easting><northing>، على سبيل المثال 31UDQ4825111935. تتحكم الوسيطة precision في عدد الخانات المستخدمة لكلٍّ من easting وnorthing: تكون القيمة 5 (الافتراضية) لدقة 1 م، و4 لدقة 10 م، و3 لدقة 100 م، و2 لدقة 1 كم، و1 لدقة 10 كم، و0 لمربع شبكة 100 كم فقط. لا يُعرَّف MGRS إلا لدوائر العرض ضمن النطاق [-80°, 84°].

geoToMGRS(longitude, latitude[, precision])

الوسائط

• longitude — خط الطول بالدرجات. النطاق: [-180°, 180°]. Float32/Float64.
• latitude — خط العرض بالدرجات. النطاق: [-80°, 84°]. Float32/Float64.
• precision — اختياري. عدد الخانات لكل من الإحداثي الشرقي والإحداثي الشمالي. القيمة الافتراضية: 5. النطاق: [0, 5]. (U)Int*.

القيمة المُعادة

سلسلة مرجعية بتنسيق MGRS. String.

مثال

SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m;

┌─mgrs────────────┬─mgrs_100m───┐
│ 31UDQ4825111935 │ 31UDQ482119 │
└─────────────────┴─────────────┘

يفكّ ترميز سلسلة MGRS إلى إحداثيات جغرافية وفق WGS84 (longitude, latitude). وهذه هي العملية العكسية لـ geoToMGRS.

النقطة المُعادة هي مركز مربع الشبكة المشار إليه، لذلك تتوافق دقة النتيجة مع الدقة المرمّزة في السلسلة. ويُتجاهل الفراغ الأبيض في الإدخال، كما أن الأحرف لا تتأثر بحالة الأحرف.

MGRSToGeo(mgrs)

الوسائط

• mgrs — سلسلة مرجعية بتنسيق MGRS المطلوب فك ترميزها. String/FixedString.

القيمة المُعادة

Tuple مُسمّى (longitude, latitude) بالدرجات. Tuple(Float64, Float64).

مثال

SELECT MGRSToGeo('31UDQ4825111935') AS coord;

(2.294495618908297,48.85822536113692)

يتحقق مما إذا كانت النقطة تقع داخل شكل بيضاوي واحد على الأقل. الإحداثيات هندسية ضمن نظام الإحداثيات الديكارتية.

pointInEllipses(x, y, x₀

معلمات الإدخال

• x, y — إحداثيات نقطة على المستوى.
• xᵢ, yᵢ — إحداثيات مركز القطع الناقص رقم i.
• aᵢ, bᵢ — محورا القطع الناقص رقم i بوحدات إحداثيي x وy.

يجب أن يكون عدد معلمات الإدخال 2+4⋅n، حيث إن n هو عدد الأشكال البيضوية.

القيم المعادة

1 إذا كانت النقطة داخل شكل بيضوي واحد على الأقل؛ 0 إذا لم تكن كذلك.

مثال

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)

┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

يتحقق مما إذا كانت النقطة تقع داخل المضلع على المستوى.

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

قيم الإدخال

• (x, y) — إحداثيات نقطة على المستوى. نوع البيانات — Tuple — قيمة Tuple مكوّنة من رقمين، أو Point.
• [(a, b), (c, d) ...] — رؤوس المضلع. نوع البيانات — Array أو Ring. تُمثَّل كل قمة بزوج من الإحداثيات (a, b). يجب تحديد الرؤوس بترتيب مع عقارب الساعة أو عكس اتجاه عقارب الساعة. الحد الأدنى لعدد الرؤوس هو 3.
• تدعم الدالة أيضًا المضلع ذي الفتحات (الأجزاء المقتطعة). نوع البيانات — Polygon. مرِّر إما Polygon بالكامل باعتباره المُدخل الثاني، أو مرِّر الحلقة الخارجية أولًا ثم كل فتحة كمدخل إضافي منفصل.
• تدعم الدالة أيضًا MultiPolygon. نوع البيانات — MultiPolygon. مرِّر إما MultiPolygon بالكامل باعتباره المُدخل الثاني، أو أدرج كل مضلع مكوّن باعتباره مُدخلًا مستقلًا.
• يمكن أيضًا أن تكون وسيطة المضلع عمود Geometry يحتوي على قيم ذات شكل مضلع (Ring أو Polygon أو MultiPolygon).

يمكن تمرير الأنواع ذات الشكل المضلع (Ring وPolygon وMultiPolygon وGeometry) إما كثوابت أو كأعمدة جدول عادية (غير ثابتة). وعندما يُمرَّر المضلع عبر عدة وسائط منفصلة (حلقة خارجية تتبعها فتحات، أو عدة مضلعات ضمن multipolygon)، يجب أن تكون جميع تلك الوسائط ثابتة.

القيم المعادة

1 إذا كانت النقطة داخل المضلع، و0 إذا لم تكن كذلك. إذا كانت النقطة على حدود المضلع، فقد تُرجع الدالة 0 أو 1.

مثال

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res

┌─res─┐
│   1 │
└─────┘

يمكن أيضًا تمرير المضلع باستخدام أنواع البيانات الهندسية المسمّاة، بما في ذلك كعمود في جدول:

CREATE TABLE poly (id UInt32, shape Polygon) ENGINE = Memory;
INSERT INTO poly VALUES (1, [[(0, 0), (10, 0), (10, 10), (0, 10)], [(4, 4), (6, 4), (6, 6), (4, 6)]]);
SELECT id, pointInPolygon((2., 2.), shape) AS res FROM poly;

┌─id─┬─res─┐
│  1 │   1 │
└────┴─────┘

ملاحظة • يمكنك تعيين validate_polygons = 0 لتجاوز التحقق من صحة الأشكال الهندسية. • تفترض الدالة pointInPolygon أن كل مضلع مُشكَّل بصورة صحيحة. إذا كان الإدخال متقاطعًا مع نفسه، أو كانت حلقاته مرتبة على نحو غير صحيح، أو كانت حوافه متداخلة، تصبح النتائج غير موثوقة—خصوصًا للنقاط الواقعة تمامًا على حافة أو رأس، أو داخل تقاطع ذاتي حيث يكون مفهوم "الداخل" مقابل "الخارج" غير معرّف. • عندما تكون وسيطة المضلع ثابتة وتُعبَّر النقطة باستخدام أعمدة المفتاح المفهرسة (على سبيل المثال، pointInPolygon((x, y), constant_polygon) على جدول تكون فيه x, y جزءًا من PRIMARY KEY أو مشمولة بفهرس minmax)، يمكن لـ ClickHouse استخدام كلٍّ من المفتاح الأساسي وفهارس تخطي البيانات minmax لاستبعاد الحبيبات غير ذات الصلة.