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

> توثيق تنسيق إخراج الصور PNG

# PNG

| الإدخال | الإخراج | الاسم البديل |
| ------- | ------- | ------------ |
| ✗       | ✔       | ✗            |

<div id="description">
  ## الوصف
</div>

يعرض نتيجة الاستعلام على هيئة صورة PNG. ويكون ذلك مفيدًا كأداة تصور مدمجة.

يُحدَّد حجم الصورة الناتجة بواسطة الإعدادات
[`output_format_image_width`](/docs/ar/reference/settings/formats/output-format#output_format_image_width) و
[`output_format_image_height`](/docs/ar/reference/settings/formats/output-format#output_format_image_height)
(القيمة الافتراضية لكليهما هي 1024). وتُملأ البكسلات التي لا تغطيها النتيجة باللون الأسود
(في وضعي `RGB` والتدرج الرمادي) أو بالأسود الشفاف (في وضع `RGBA`).

يُحدَّد وضع الألوان تلقائيًا استنادًا إلى أسماء الأعمدة وأنواعها في النتيجة:

| الأعمدة             | الوضع                                                 |
| ------------------- | ----------------------------------------------------- |
| `r`, `g`, `b`       | RGB بعمق 8 بت                                         |
| `r`, `g`, `b`, `a`  | RGBA بعمق 8 بت                                        |
| `v` من نوع عدد صحيح | تدرج رمادي بعمق 8 بت                                  |
| `v` من نوع `Float*` | تدرج رمادي بعمق 8 بت (القيم في `[0, 1]` → `[0, 255]`) |
| `v` من نوع `Bool`   | ثنائي (يُعرَض كتدرج رمادي بعمق 8 بت: `0` أو `255`)    |

تُطابَق أسماء الأعمدة دون حساسية لحالة الأحرف. وإذا تعذر تحديد وضع الألوان
بشكل لا لبس فيه (مثلًا: أسماء أعمدة غير معروفة، أو مزج `v` مع `r`/`g`/`b`/`a`، أو غياب أحد `r`/`g`/`b`)،
فإن الاستعلام يرفع استثناءً.

بالنسبة إلى قنوات البكسل، تُقيَّد القيم الصحيحة ضمن `[0, 255]`، وتُقيَّد قيم الفاصلة العائمة
ضمن `[0, 1]` ثم تُحوَّل إلى النطاق `[0, 255]`.

يُحدَّد موضع كل سجل في الصورة بأحد وضعين:

* **ضمني** (الافتراضي — عندما لا يكون `x` ولا `y` موجودين). يقابل كل سجل
  بكسلًا واحدًا؛ وتُملأ البكسلات بترتيب خطوط المسح: من اليسار إلى اليمين، ومن الأعلى إلى الأسفل.
* **صريح** (عند وجود العمودين `x` و`y`، وكلاهما من نوع عدد صحيح).
  يحدِّد العمودان `x` و`y` إحداثيات البكسل. وتُتجاهل السجلات ذات الإحداثيات الواقعة خارج
  الصورة بصمت. وعند وجود عدة سجلات بالإحداثيات نفسها،
  تكون الغلبة للأخير (خوارزمية الرسام).

<div id="example-usage">
  ## مثال للاستخدام
</div>

<div id="implicit-rgb">
  ### الإحداثيات الضمنية (صف لكل بكسل)، RGB
</div>

```sql theme={null}
SELECT
    toUInt8(x * 25) AS r,
    toUInt8(y * 25) AS g,
    toUInt8((x + y) * 12) AS b
FROM
(
    SELECT number % 10 AS x, intDiv(number, 10) AS y FROM numbers(100)
)
INTO OUTFILE 'gradient.png'
FORMAT PNG
SETTINGS output_format_image_width = 10, output_format_image_height = 10;
```

<div id="explicit-grayscale">
  ### إحداثيات صريحة، وتدرّج رمادي
</div>

```sql theme={null}
SELECT
    toInt32(x) AS x,
    toInt32(y) AS y,
    toUInt8(intensity) AS v
FROM points
INTO OUTFILE 'points.png'
FORMAT PNG
SETTINGS output_format_image_width = 512, output_format_image_height = 512;
```

<div id="animation">
  ## الرسوم المتحركة
</div>

إذا كانت النتيجة تحتوي على عمود `t` بنوع عدد صحيح، فسينتج التنسيق صورة PNG متحركة (`APNG`) بدلًا من
صورة ثابتة. تُجمَّع السجلات في إطارات وفقًا لقيمة `t`، التي تمثل الإزاحة الزمنية النسبية
للإطار. كل إطار صورة مستقلة: تكون اللوحة فارغة عند بدء كل إطار، وفي
وضع الإحداثيات الضمني يُعاد المؤشر إلى الزاوية العلوية اليسرى. يمكن استخدام العمود `t` مع
أيٍّ من وضعي الإحداثيات.

تُحدَّد وحدة `t` بواسطة
[`output_format_image_time_multiplier_seconds`](/docs/ar/reference/settings/formats/output-format#output_format_image_time_multiplier_seconds)
و
[`output_format_image_time_divisor_seconds`](/docs/ar/reference/settings/formats/output-format#output_format_image_time_divisor_seconds):
تساوي وحدة واحدة من `t` عدد الثواني `output_format_image_time_multiplier_seconds / output_format_image_time_divisor_seconds`.
وباستخدام القيم الافتراضية (`1` و`60`)، تساوي وحدة واحدة من `t` 1/60 من الثانية.

يُعرض الإطار إلى أن يبدأ الإطار التالي، لذا تساوي مدته الفرق بين قيمتين متتاليتين
لـ `t`. ويُعرض الإطار الأخير للمدة نفسها التي عُرض بها الإطار السابق. تتكرر الرسوم المتحركة إلى ما لا نهاية.

```sql theme={null}
SELECT
    number % 60 AS t,
    toInt32(intDiv(number, 60) % 64) AS x,
    toInt32((number * 7) % 64) AS y,
    toUInt8(255) AS v
FROM numbers(60 * 64)
INTO OUTFILE 'animation.png'
FORMAT PNG
SETTINGS output_format_image_width = 64, output_format_image_height = 64;
```

<div id="streaming-animation">
  ### بث الإطارات
</div>

افتراضيًا، تُجمع جميع الإطارات في الذاكرة وتُكتب عند انتهاء الاستعلام، مما يُبقي مخزنًا واحدًا للصور
لكل قيمة مميزة لـ `t` ويتيح ورود `t` بأي ترتيب.

يكتب الإعداد
[`output_format_image_streaming_animation`](/docs/ar/reference/settings/formats/output-format#output_format_image_streaming_animation)
كل إطار فور ظهور القيمة التالية لـ `t`. يُحتفظ بمخزن صور واحد فقط في الذاكرة، وتصل الإطارات إلى
المخرجات بينما لا يزال الاستعلام قيد التشغيل، بحيث يمكن للعارض عرضها فور إنتاجها.
في المقابل:

* يجب أن تكون قيم `t` غير متناقصة؛ وإلا يرفع الاستعلام استثناءً. أضف `ORDER BY t` عند الحاجة.
* لا يكون عدد الإطارات معروفًا عند وجوب كتابة الترويسة، لذا يعلن الجزء `acTL` حدًا
  أعلى بدلًا من العدد الدقيق. تشغّل المتصفحات ملفًا كهذا، لكن المفككات التي تعتمد العدد المُعلن
  (مثل `Pillow` وبعض أدوات `APNG` من سطر الأوامر) تُبلغ عن خطأ بعد آخر إطار فعلي.
  ويُستثنى من ذلك الرسم المتحرك المكوّن من إطار واحد: إذ تكون النتيجة كاملة قد قُرئت عند كتابة ذلك الإطار،
  لذا يُعلن العدد بدقة وتتوافق المخرجات مع المواصفة.

نظرًا إلى أن بروتوكول الصور المضمنة في الطرفية يحمل تدفق البيانات بالكامل كحمولة واحدة، فلا يمكن للإطارات
الوصول إلى الطرفية مبكرًا، ولا يؤثر هذا الإعداد هناك إلا في مقدار الذاكرة المستخدمة. يُصحَّح العدد الدقيق
للإطارات في الحمولة المخزنة مؤقتًا قبل إرسالها، لذا لا ينطبق التحذير المتعلق بالحد الأعلى.

لا يُعرض الرسم المتحرك إلا في وضع الطرفية `iterm`. ولا يستطيع بروتوكول `sixel` تمثيل الرسوم المتحركة
مطلقًا، كما أن بروتوكول رسومات Kitty لا يحرّك الصور إلا عبر تدفق منفصل من الأوامر لكل إطار،
وليس عبر تدفق بيانات متحرك، لذا سيعرض الإطار الأول فقط؛ ويرفض كلا الوضعين نتيجة تحتوي على
عمود `t`.

<div id="terminal-mode">
  ## عرض الصور في الطرفية
</div>

بشكل افتراضي، يكتب تنسيق `PNG` بايتات الصورة الخام. ويجعل الإعداد
[`output_format_image_terminal_mode`](/docs/ar/reference/settings/formats/output-format#output_format_image_terminal_mode)
التنسيق يعرض الصورة مباشرةً في الطرفية باستخدام بروتوكول صور مضمنة بدلًا من ذلك:

| القيمة      | السلوك                                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| \`\` (فارغ) | اكتب بايتات الصورة الخام (وهو السلوك الافتراضي).                                                                            |
| `iterm`     | استخدم بروتوكول الصور المضمنة الخاص بـ iTerm2.                                                                              |
| `kitty`     | استخدم بروتوكول الرسوميات الخاص بـ Kitty. لا يمكنه عرض رسم متحرك.                                                           |
| `sixel`     | استخدم بروتوكول Sixel. تُختزل الصورة إلى لوحة ألوان ثابتة 6×6×6، وتُركَّب قناة alpha، إن وُجدت، فوق خلفية سوداء.            |
| `auto`      | إذا كان الخرج طرفية، فاكتشف إمكاناتها واستخدم `iterm` أو `kitty` أو `sixel` (بهذا الترتيب)؛ وإلا فاكتب بايتات الصورة الخام. |

```sql theme={null}
SELECT toUInt8(x * 25) AS r, toUInt8(y * 25) AS g, toUInt8((x + y) * 12) AS b
FROM (SELECT number % 10 AS x, intDiv(number, 10) AS y FROM numbers(100))
FORMAT PNG
SETTINGS output_format_image_width = 10, output_format_image_height = 10, output_format_image_terminal_mode = 'auto';
```

<div id="format-settings">
  ## إعدادات التنسيق
</div>

| الإعداد                                       | الوصف                                       | القيمة الافتراضية |
| --------------------------------------------- | ------------------------------------------- | ----------------- |
| `output_format_image_width`                   | عرض صورة ناتجة بالبكسل.                     | `1024`            |
| `output_format_image_height`                  | ارتفاع صورة ناتجة بالبكسل.                  | `1024`            |
| `output_format_image_terminal_mode`           | بروتوكول صورة الطرفية المضمّن (انظر أعلاه). | \`\` (فارغ)       |
| `output_format_image_time_multiplier_seconds` | بسط وحدة الوقت للعمود `t`، بالثواني.        | `1`               |
| `output_format_image_time_divisor_seconds`    | مقام وحدة الوقت للعمود `t`، بالثواني.       | `60`              |
| `output_format_image_streaming_animation`     | اكتب كل إطار بمجرد تقدّم `t` (انظر أعلاه).  | `0`               |