\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "PGM Format Specification" 5 "07 November 2025" "netpbm documentation"

.SH "نام (NAME)"

pgm \- قالب تصویر در مقیاس خاکستری Netpbm

.UN description
.SH "توضیحات (DESCRIPTION)"
.PP
این برنامه بخشی از
.BR "Netpbm" (1)\c
\& است.
.PP
قالب PGM ساده‌ترین مخرج مشترک قالب‌های فایل مقیاس خاکستری (grayscale) است. این قالب به‌گونه‌ای طراحی شده که یادگیری و برنامه‌نویسی برای آن بسیار آسان باشد (آن‌قدر ساده است که بیشتر افراد به جای خواندن این مشخصات، به سادگی با مهندسی معکوس آن را متوجه می‌شوند).
.PP
یک تصویر PGM نشان‌دهنده یک تصویر گرافیکی در مقیاس خاکستری است. قالب‌های شبه-PGM متعددی در حال استفاده هستند که در آن‌ها همه چیز مطابق موارد مشخص‌شده در این سند است، به جز معنای مقادیر تک‌تک پیکسل‌ها. برای بیشتر اهداف، یک تصویر PGM را می‌توان صرفاً آرایه‌ای از اعداد صحیح اختیاری در نظر گرفت، و تمامی برنامه‌های دنیا که تصور می‌کنند در حال پردازش یک تصویر مقیاس خاکستری هستند را می‌توان به راحتی فریب داد تا چیز دیگری را پردازش کنند.
.PP
نام «PGM» سرواژه‌ای برگرفته از «Portable Gray Map» (نگاشت خاکستری قابل‌حمل) است.
.PP
یکی از گونه‌های رسمی PGM ماسک شفافیت است. یک ماسک شفافیت در Netpbm با یک تصویر PGM نمایش داده می‌شود، با این تفاوت که به جای شدت روشنایی پیکسل‌ها، مقادیر مات بودن قرار می‌گیرند. بخش‌های بعدی را ببینید.

.UN format
.SH "قالب (THE FORMAT)"
.PP
تعریف قالب به شرح زیر است. می‌توانید از کتابخانه زیرروال‌های زبان C به نام
.BR "libnetpbm" (1)\c
\& برای خواندن و تفسیر آسان و دقیق قالب استفاده کنید.
.PP
یک فایل PGM از دنباله‌ای شامل یک یا چند تصویر PGM تشکیل شده است. هیچ داده، جداکننده یا فاصله‌گذاری (padding) قبل، بعد یا بین تصاویر وجود ندارد.
.PP
هر تصویر PGM از موارد زیر تشکیل شده است:



.IP \(bu
یک «عدد جادویی» (magic number) برای شناسایی نوع فایل. عدد جادویی یک تصویر pgm دو نویسه «P5» است.

.IP \(bu
فضای خالی (شامل نویسه‌های فاصله، تب، CR و LF).

.IP \(bu
عرض تصویر، قالب‌بندی‌شده به‌صورت نویسه‌های اسکی (ASCII) در مبنای ده.

.IP \(bu
فضای خالی.

.IP \(bu
ارتفاع تصویر، مجدداً به‌صورت نویسه‌های اسکی در مبنای ده.

.IP \(bu
فضای خالی.

.IP \(bu
بیشترین مقدار خاکستری (Maxval)، مجدداً به‌صورت اسکی در مبنای ده. باید کمتر از 65536 و بیشتر از صفر باشد.

.IP \(bu
یک نویسه فضای خالی منفرد (معمولاً یک خط جدید).

.IP \(bu
یک رستر از سطرهایی به تعداد Height، به ترتیب از بالا به پایین. هر سطر شامل مقادیر خاکستری به تعداد Width، به ترتیب از چپ به راست است. هر مقدار خاکستری عددی از 0 تا Maxval است که در آن 0 نشان‌دهنده سیاه و Maxval نشان‌دهنده سفید است. هر مقدار خاکستری در حالت دودویی خالص با 1 یا 2 بایت نمایش داده می‌شود. اگر مقدار Maxval کمتر از 256 باشد، 1 بایت خواهد بود؛ در غیر این صورت، 2 بایت است. باارزش‌ترین بایت ابتدا می‌آید.
.sp
یک سطر از تصویر افقی است. یک ستون عمودی است. پیکسل‌ها در تصویر مربعی و به هم پیوسته هستند.
.sp
هر مقدار خاکستری عددی متناسب با شدت روشنایی پیکسل است که توسط تابع تبدیل گامای توصیه‌نامه ITU\-R BT.709 تنظیم شده است (آن تابع تبدیل، عدد گامای 2.2 را مشخص کرده و دارای یک بخش خطی برای شدت‌های روشنایی کم است). بنابراین مقدار صفر، سیاه است. مقدار Maxval نشان‌دهنده سفید CIE D65 و درخشان‌ترین مقدار در تصویر و هر تصویر دیگری است که ممکن است این تصویر با آن مقایسه شود.
.sp
محدوده مقادیر کانال BT.709 (یعنی 16\-240) ارتباطی با PGM ندارد.
.sp
توجه داشته باشید که یک تغییر رایج نسبت به قالب PGM این است که مقدار خاکستری «خطی» (linear) باشد؛ یعنی همان‌طور که در بالا مشخص شده، اما بدون اعمال تنظیم گاما. دستور \fBpnmgamma\fP چنین گونه‌ای از PGM را به عنوان ورودی دریافت کرده و یک PGM واقعی در خروجی تولید می‌کند.
.sp
تغییر رایج دیگر نسبت به PGM، جایگزینی تابع تبدیل جدیدتر sRGB به جای BT.709 است. می‌توانید از \fBpnmgamma\fP برای تبدیل بین این تغییر و PGM واقعی استفاده کنید.
.sp
در گونه ماسک شفافیت PGM، مقدار نشان‌دهنده مات بودن (opaqueness) است. این مقدار متناسب با کسری از شدت یک پیکسل است که به جای پیکسل زیرین نمایش داده می‌شود. بنابراین آنچه معمولاً به معنای سفید است، نشان‌دهنده ماتی کامل و آنچه معمولاً به معنای سیاه است، نشان‌دهنده شفافیت کامل خواهد بود. در مقادیر بین این دو، شدت یک پیکسل ترکیبی از یک پیکسل «زیرین» (under) و «رویی» (over) به صورت under * (1\-(alpha/alpha_maxval)) + over * (alpha/alpha_maxval) محاسبه می‌شود. توجه داشته باشید که در ماسک شفافیت هیچ تابع تبدیل گامایی وجود ندارد.


.PP
رشته‌هایی که با «#» شروع می‌شوند می‌توانند توضیحات (کامنت) باشند، همان‌گونه که در
.BR "PBM" (1)\c
\& آمده است.
.PP
توجه داشته باشید که می‌توانید از \fBpamdepth\fP برای تبدیل میان قالب با ۱ بایت به ازای هر مقدار خاکستری و قالب با ۲ بایت به ازای هر مقدار خاکستری استفاده کنید.
.PP
تمام نویسه‌های اشاره‌شده در این سند با کدگذاری اسکی (ASCII) هستند. «newline» به نویسه‌ای اطلاق می‌شود که در اسکی به عنوان Line Feed یا LF شناخته می‌شود. یک نویسه «فضای خالی» (white space) شامل فاصله (space)، CR، LF، TAB، VT یا FF است (یعنی آنچه تابع استاندارد isspace() در زبان C استاندارد ANSI آن را فضای خالی می‌نامد).

.UN minimal
.SS "زیرمجموعه کمینه (Minimal Subset)"
.PP
قالب PGM به قدری ساده است که بسیاری از برنامه‌نویسان برنامه‌هایی می‌نویسند تا آن را مستقیماً و بدون استفاده از کتابخانه‌ای مانند \fBlibnetpbm\fP پردازش کنند؛ آن‌ها به جای استفاده از مشخصات رسمی، زیرمجموعه‌ای از قالب را بر اساس مثال‌ها مهندسی معکوس می‌کنند. بنابراین، اگر می‌خواهید تصویری تولید کنید که تا حد امکان برنامه‌های بیشتری قادر به خواندن آن باشند، باید به زیرمجموعه زیر پایبند بمانید:
.PP
تصویر شامل بایت‌های زیر است:

.IP \(bu
عبارت 'P5' که پس از آن خط جدید می‌آید
.IP \(bu
عرض و ارتفاع که با یک فاصله از هم جدا شده‌اند (مانند '50 100')، و پس از آن خط جدید می‌آید
.IP \(bu
مقدار maxval که پس از آن خط جدید می‌آید. حداکثر 255؛ و در حالت کمینه‌تر، دقیقاً 255.
.IP \(bu
رستر داده‌ها (The raster)

.PP
تنها یک تصویر در فایل وجود دارد.
.PP
برنامه \fBpnmtopnm\fP این زیرمجموعه کمینه را تولید می‌کند؛ بنابراین اگر یک تصویر PGM پیچیده‌تر دارید، می‌توانید با ارسال آن از طریق \fBpnmtopnm\fP، آن را به برنامه‌ای که انعطاف‌پذیری کمتری دارد منتقل کنید. برنامه \fBpamdepth\fP می‌تواند مقدار maxval را به 255 تبدیل کند.


.UN plainpgm
.SS "قالب متنی ساده (Plain PGM)"
.PP
در واقع نسخه دیگری از قالب PGM نیز وجود دارد که نسبتاً نادر است: قالب PGM «متنی ساده» (plain). قالبی که در بالا توصیف شد و عموماً قالب عادی در نظر گرفته می‌شود، به عنوان قالب PGM «خام» (raw) شناخته می‌شود. برای توضیحاتی درباره نحوه ارتباط قالب‌های متنی ساده و خام با یکدیگر و چگونگی استفاده از آن‌ها به
.BR "pbm" (1)\c
\& مراجعه کنید.
.PP
تفاوت‌های موجود در قالب متنی ساده عبارتند از:


.IP \(bu

دقیقاً یک تصویر در هر فایل وجود دارد.
.IP \(bu

عدد جادویی به جای P5 برابر با P2 است.
.IP \(bu

هر پیکسل در رستر به صورت یک عدد دهدهی اسکی (با اندازه اختیاری) نمایش داده می‌شود.
.IP \(bu

هر پیکسل در رستر دارای فضای خالی قبل و بعد از خود است. باید حداقل یک نویسه فضای خالی بین هر دو پیکسل وجود داشته باشد، اما هیچ حداکثری وجود ندارد.
.IP \(bu

هیچ خطی نباید طولانی‌تر از 70 نویسه باشد.

.PP
در اینجا نمونه‌ای از یک تصویر کوچک در قالب PGM متنی ساده آورده شده است.

.nf
P2
# feep.pgm
24 7
15
0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
0  3  3  3  3  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15 15 15 15  0
0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0 15  0
0  3  3  3  0  0  0  7  7  7  0  0  0 11 11 11  0  0  0 15 15 15 15  0
0  3  0  0  0  0  0  7  0  0  0  0  0 11  0  0  0  0  0 15  0  0  0  0
0  3  0  0  0  0  0  7  7  7  7  0  0 11 11 11 11  0  0 15  0  0  0  0
0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
.fi
.PP
در انتهای هر یک از این خطوط یک نویسه خط جدید (newline) قرار دارد.
.PP
برنامه‌هایی که این قالب را می‌خوانند باید تا حد امکان با مدارا رفتار کنند و هر چیزی را که حتی اندکی شبیه به یک تصویر PGM باشد بپذیرند.


.UN internetmediatype
.SH "نوع رسانه اینترنتی (INTERNET MEDIA TYPE)"
.PP
هیچ نوع رسانه اینترنتی (که با عنوان نوع MIME یا نوع محتوا نیز شناخته می‌شود) برای PGM در IANA ثبت نشده است، اما مقدار \f(CWimage/x-portable-graymap\fP به‌طور سنتی استفاده می‌شود.
.PP
توجه داشته باشید که نوع رسانه اینترنتی PNM به صورت \f(CWimage/x-portable-anymap\fP نیز برای آن صدق می‌کند.


.UN filename
.SH "نام فایل (FILE NAME)"
.PP
هیچ الزامی برای نام یک فایل PGM وجود ندارد، اما طبق عرف از پسوند «.pgm» استفاده می‌شود. همچنین در مواردی که تمایز بین زیرقالب‌های خاص PNM چندان آسان یا ضروری نیست، استفاده از «pnm» نیز مرسوم است.


.UN compatibility
.SH "سازگاری (COMPATIBILITY)"
.PP
پیش از آوریل سال 2000، یک فایل PGM در قالب خام نمی‌توانست مقدار maxval بیشتر از 255 داشته باشد؛ بنابراین نمی‌توانست بیش از یک بایت در هر نمونه داده داشته باشد. برنامه‌های قدیمی ممکن است به این موضوع وابسته باشند.
.PP
پیش از ژوئیه سال 2000، حداکثر یک تصویر می‌توانست در یک فایل PGM وجود داشته باشد. در نتیجه، بیشتر ابزارهای پردازش فایل‌های PGM، هرگونه داده پس از تصویر نخست را نادیده گرفته و نمی‌خوانند.

.UN seealso
.SH "همچنین ببینید (SEE ALSO)"
.BR "pnm" (1)\c
\&,
.BR "pbm" (1)\c
\&,
.BR "ppm" (1)\c
\&,
.BR "pam" (1)\c
\&,
.BR "libnetpbm" (1)\c
\&,
.BR "programs that process PGM" (1)\c
\&

.UN author
.SH "نویسنده (AUTHOR)"

حق نشر \(co 1989، 1991 متعلق به Jef Poskanzer است.
.SH "منبع سند (DOCUMENT SOURCE)"
این صفحه راهنما توسط ابزار 'makeman' از بسته Netpbm و از روی منبع HTML تولید شده است. مستندات اصلی در نشانی زیر قرار دارد:
.IP
.B http://netpbm.sourceforge.net/doc/pgm.html
.PP