\
.\" 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 "Pnmcolormap User Manual" 0 "21 February 2023" "netpbm documentation"

.SH "نام (NAME)"

pnmcolormap \- ایجاد نقشه‌رنگ کوانتیزاسیون برای یک تصویر Netpbm

.UN synopsis
.SH "خلاصه دستور (SYNOPSIS)"

\fBpnmcolormap\fP

[\fB-center\fP|\fB-meancolor\fP|\fB-meanpixel\fP]

[\fB-spreadbrightness\fP|\fB-spreadluminosity\fP]

[\fB-splitpixelct\fP|\fB-splitcolorct\fP|\fB-splitspread\fP]

[\fB-sort\fP]

[\fB-square\fP] 

[\fB-verbose\fP] 

[\fB-debug\fP] 

\fIncolors\fP|\fBall\fP

[\fIpnmfile\fP]

.UN description
.SH "توضیحات (DESCRIPTION)"
.PP
این برنامه بخشی از
.BR "Netpbm" (1)\c
\& است.
.PP
برنامه \fBpnmcolormap\fP یک تصویر PNM یا PAM را به عنوان ورودی خوانده، تعداد \fIncolors\fP رنگ را برای بهترین بازنمایی تصویر انتخاب می‌کند و یک نقشه‌رنگ (colormap) PNM حاوی تعریف آن‌ها در خروجی می‌نویسد. یک تصویر PAM در واقع ممکن است حاوی تاپل‌هایی از هر نوع باشد، اما مفهوم \fBpnmcolormap\fP از مقادیر تاپل‌هایی که به بهترین شکل عناصر موجود در تصویر را نمایش دهند، در صورتی که نوع تاپل RGB یا GRAYSCALE نباشد ممکن است چندان منطقی نباشد. طراحی این برنامه و باقی این راهنما، فرض را بر این می‌گذارد که تاپل‌ها بیانگر رنگ‌ها هستند.
.PP
می‌توانید از این نقشه‌رنگ به عنوان ورودی برای \fBpnmremap\fP بر روی همان تصویر ورودی استفاده کنید تا رنگ‌های آن تصویر را کوانتیزه کنید (یعنی تصویری مشابه با تعداد رنگ‌های کمتر تولید کنید). برنامه \fBpnmquant\fP هر دو مرحله \fBpnmcolormap\fP و \fBpnmremap\fP را برای شما انجام می‌دهد.
.PP
یک نقشه‌رنگ PNM در واقع تصویری در فرمت PNM با هر ابعادی است که حداقل یک پیکسل از هر رنگ در مجموعه رنگ‌هایی که بازنمایی می‌کند دارد. نقشه‌هایی که \fBpnmcolormap\fP تولید می‌کند دقیقاً شامل یک پیکسل از هر رنگ هستند، به جز در مواردی که با استفاده از گزینه \fB-square\fP پدینگ (padding) ضروری باشد.
.PP
روش کوانتیزاسیون مورد استفاده، روش "median cut" هکبرت (Heckbert) است. مشاهده کنید:
.UR #quant
روش کوانتیزاسیون
.UE
\&.
.PP
تصویر خروجی دارای همان فرمت (PBM، PGM، PPM، PAM) تصویر ورودی است. توجه داشته باشید که نقشه‌رنگ یک تصویر PBM چندان جذاب و کاربردی نیست.
.PP
نقشه‌رنگ معمولاً همان مقدار maxval تصویر ورودی را دارد، اما \fBpnmcolormap\fP ممکن است در صورت وجود رنگ‌های بیش از حد در ورودی، به عنوان بخشی از الگوریتم کوانتیزاسیون خود آن را کاهش دهد.
.PP
برنامه \fBpnmcolormap\fP بر روی یک جریان ورودی چندتصویری (multi-image) نیز کار می‌کند. در آن صورت، یک نقشه‌رنگ تولید می‌کند که برای تمام رنگ‌های موجود در تمامی تصاویر ورودی اعمال می‌شود. همه تصاویر باید فرمت، عمق و maxval یکسانی داشته باشند (اما می‌توانند عرض و ارتفاع متفاوتی داشته باشند). این قابلیت زمانی مفید است که بخواهید مجموعه‌ای از تصاویر را کوانتیزه کنید که یک ویدیو تشکیل می‌دهند یا به نوعی با هم استفاده می‌شوند؛ معمولاً می‌خواهید همگی از یک پالت مشترک استفاده کنند، در حالی که محاسبه جداگانه نقشه‌رنگ برای هر تصویر موجب می‌شود رنگ‌های یکسان در دو تصویر به رنگ‌های متفاوتی نگاشت شوند. پیش از Netpbm 10.31 (دسامبر ۲۰۰۵)، \fBpnmcolormap\fP تصاویر پس از تصویر اول را نادیده می‌گرفت.
.PP
اگر می‌خواهید نقشه‌رنگی را بدون تکیه بر رنگ‌های یک تصویر ورودی ایجاد کنید، ابزارهای \fBpamseq\fP، \fBppmmake\fP و \fBpamcat\fP می‌توانند مفید باشند.

.UN parameters
.SH "پارامترها (PARAMETERS)"
.PP
تنها پارامتری که اجباری است، تعداد رنگ‌هایی است که در نقشه‌رنگ خروجی می‌خواهید. برنامه \fBpnmcolormap\fP ممکن است نقشه‌رنگی با تعداد رنگ‌هایی اندکی کمتر از آن تولید کند. می‌توانید \fBall\fP را مشخص کنید تا نقشه‌رنگی از تمام رنگ‌های موجود در تصویر ورودی (بدون کوانتیزاسیون) دریافت نمایید. هنگامی که \fBall\fP را تعیین می‌کنید، عملکرد برنامه اساساً مشابه عملکرد \fBppmhist -map\fP است. برنامه \fBppmhist\fP بسیار قدیمی‌تر است.


.UN options
.SH "گزینه‌ها (OPTIONS)"
.PP
علاوه بر گزینه‌های مشترک بین تمامی برنامه‌های مبتنی بر libnetpbm (به‌ویژه \fB-quiet\fP؛ مشاهده کنید: 
.UR index.html#commonoptions
گزینه‌های عمومی
.UE
\&)، برنامه \fBpnmcolormap\fP گزینه‌های خط فرمان زیر را تشخیص می‌دهد:
.PP
تمامی گزینه‌ها را می‌توان به کوتاه‌ترین پیشوند منحصربه‌فردشان خلاصه کرد. می‌توانید به جای یک خط تیره از دو خط تیره برای تعیین گزینه استفاده کنید. همچنین می‌توانید میان نام گزینه و مقدار آن از فاصله یا علامت مساوی استفاده نمایید.


.TP
\fB-sort\fP
این گزینه باعث می‌شود نقشه‌رنگ خروجی بر اساس شدت مؤلفه قرمز، سپس سبز و سپس آبی به صورت صعودی مرتب شود. این مرتب‌سازی از نوع مرتب‌سازی درجی (insertion sort) است، بنابراین در نقشه‌رنگ‌های بزرگ خیلی سریع نیست. مرتب‌سازی مفید است زیرا امکان مقایسه دو مجموعه رنگ را به شما می‌دهد.

.TP
\fB-square\fP
به‌طور پیش‌فرض، \fBpnmcolormap\fP نقشه‌رنگ را به صورت یک تصویر PPM با یک سطر و با یک ستون به ازای هر رنگ در نقشه‌رنگ تولید می‌کند. این گزینه باعث می‌شود که \fBpnmcolormap\fP به جای آن یک تصویر PPM تولید کند که اختلاف ابعاد آن تا مربع کامل در حد یک سطر یا ستون باشد، و در صورت نیاز آخرین پیکسل تکرار می‌شود تا تعداد پیکسل‌ها یک مربع تقریباً کامل ایجاد کند.

.TP
\fB-verbose\fP
این گزینه باعث می‌شود \fBpnmcolormap\fP پیام‌هایی درباره کوانتیزاسیون به خروجی خطای استاندارد ارسال کند.

.TP
\fB-debug\fP
این گزینه باعث می‌شود \fBpnmcolormap\fP پیام‌هایی درباره عملکردهای داخلی به خروجی خطای استاندارد ارسال کند.

.TP
\fB-center\fP

.TP
\fB-meancolor\fP

.TP
\fB-meanpixel\fP

.TP
\fB-spreadbrightness\fP

.TP
\fB-spreadluminosity\fP

.TP
\fB-splitpixelct\fP

.TP
\fB-splitcolorct\fP

.TP
\fB-splitspread\fP
این گزینه‌ها الگوریتم کوانتیزاسیون را کنترل می‌کنند. مشاهده کنید: 
.UR #quant
روش کوانتیزاسیون
.UE
\&.




.UN quant
.SH "روش کوانتیزاسیون (QUANTIZATION METHOD)"
.PP
روش کوانتیزاسیون راهکاری است برای انتخاب رنگ‌هایی که (با تعداد کمتر از ورودی) در خروجی می‌خواهید. برنامه \fBpnmcolormap\fP از روش کوانتیزاسیون "median cut" متعلق به Heckbert استفاده می‌کند.
.PP
این روش شامل تفکیک تمامی رنگ‌ها درون "جعبه‌ها" (boxes) است، که هر جعبه رنگ‌هایی را در بر می‌گیرد که تقریباً تعداد پیکسل‌های یکسانی را نمایندگی می‌کنند. کار با یک جعبه آغاز می‌شود و جعبه‌ها به دو نیم تقسیم می‌شوند تا جایی که تعداد جعبه‌ها با تعداد رنگ‌های مد نظر شما در خروجی برابر شود، و سپس یک رنگ برای نمایندگی هر جعبه انتخاب می‌گردد.
.PP
سه روش وجود دارد که \fBpnmcolormap\fP می‌تواند به وسیله آن‌ها جعبه را برای تقسیم در هر مرحله انتخاب کند:
  
.IP \(bu
تقسیم جعبه‌ای که بیشترین پیکسل را دارد. این حالت پیش‌فرض است، و می‌توانید آن را صراحتاً با گزینه \fB-splitpixelct\fP انتخاب کنید.
.IP \(bu
تقسیم جعبه‌ای که بیشترین رنگ را دارد. این مورد تنها برای اهداف پژوهشی و آکادمیک مفید به نظر می‌رسد. این گزینه را با \fB-splitcolorct\fP انتخاب کنید.
.IP \(bu
تقسیم جعبه‌ای که بزرگ‌ترین گستره رنگی (color spread) را دارد. این حالت را با گزینه \fB-splitspread\fP انتخاب کنید. این روش می‌تواند نتیجه بهتری برای جزئیات کوچک با رنگ‌هایی که در جاهای دیگر تصویر یافت نمی‌شوند تولید کند.
  
.PP
گزینه‌های \fB-splitpixelct\fP، \fBsplitcolorct\fP و \fBsplitspread\fP در Netpbm 10.88 (سپتامبر ۲۰۱۹) جدید بودند. پیش از آن، \fBpnmcolormap\fP همیشه جعبه حاوی بیشترین پیکسل را تقسیم می‌کرد.
  
.PP
هنگامی که یک جعبه را تقسیم می‌کنید، این کار به گونه‌ای انجام می‌شود که هر زیرجعبه تعداد پیکسل یکسانی داشته باشد (به جز اینکه اگر کل جعبه تعداد فردی داشته باشد، یک زیرجعبه یکی بیشتر خواهد داشت)، با قرارگیری پیکسل‌های «بزرگ‌تر» در یک زیرجعبه و پیکسل‌های «کوچک‌تر» در زیرجعبه دیگر. «بزرگ‌تر» برای یک جعبه خاص، به معنای روشن‌تر بودن در مؤلفه رنگی (قرمز، سبز، آبی) است که بیشترین گستره را در آن جعبه دارد. برنامه \fBpnmcolormap\fP دو راه برای تعریف "بزرگ‌ترین گستره" به شما ارائه می‌دهد: ۱) بزرگ‌ترین گستره روشنایی؛ ۲) بزرگ‌ترین گستره سهم در درخشندگی (luminosity) رنگ؛ برای مثال رنگ قرمز بسیار بیشتر از آبی وزن‌دهی می‌شود. انتخاب میان این دو با گزینه‌های \fB-spreadbrightness\fP و \fB-spreadluminosity\fP صورت می‌گیرد. حالت پیش‌فرض \fB-spreadbrightness\fP است. در جاهایی که چندین رنگ با اندازه میانه وجود داشته باشند، آن‌ها به صورت دلخواه میان زیرجعبه‌ها توزیع می‌شوند.

با این حال، این توزیع دلخواه برای یک نسخه مشخص از Netpbm تکرارپذیر است؛ هر بار فراخوانی \fBpnmcolormap\fP همان نقشه‌رنگ را تولید می‌کند. پیش از Netpbm 11.03 (ژوئن ۲۰۲۳)، توزیع به عملکرد تابع \fBqsort\fP سیستم در مواجهه با مقادیر مساوی متعدد بستگی داشت، بنابراین \fBpnmcolormap\fP ممکن بود روی سیستم‌های مختلف نتایج اندکی متفاوت تولید کند.
.PP
برنامه \fBpnmcolormap\fP سه روش برای انتخاب رنگ نماینده یک جعبه ارائه می‌دهد: ۱) رنگ مرکزی - رنگی که در میانه راه میان بزرگ‌ترین و کوچک‌ترین رنگ‌های جعبه قرار دارد (با استفاده از تعریف بالا برای «بزرگ‌تر»)؛ ۲) میانگین رنگ‌ها در جعبه (هر مؤلفه بر اساس روشنایی جداگانه میانگین‌گیری می‌شود)؛ ۳) میانگین وزنی بر اساس تعداد پیکسل‌های هر رنگ در تصویر.
.PP
انتخاب میان این موارد با گزینه‌های \fB-center\fP، \fB-meancolor\fP و \fB-meanpixel\fP انجام می‌شود. حالت پیش‌فرض \fB-center\fP است.
.PP
توجه داشته باشید که در هر سه روش، ممکن است رنگ‌هایی در خروجی وجود داشته باشند که اصلاً در ورودی وجود نداشته‌اند.
.PP
همچنین توجه داشته باشید که رنگی که برای نمایندگی رنگ‌های جعبه A به عنوان بهترین انتخاب شده است، ممکن است یک رنگ در جعبه B را نیز بهتر از رنگ انتخاب‌شده برای جعبه B نمایندگی کند. این امر برای معیارهای مختلف سنجش مناسب بودن بازنمایی یک رنگ توسط رنگی دیگر صادق است. به‌ویژه، اگر از \fBpnmremap\fP برای نگاشت رنگ‌های همان تصویری که برای ایجاد نقشه‌رنگ استفاده کردید به رنگ‌های آن نقشه‌رنگ استفاده کنید، رنگ‌های جعبه B اغلب به رنگی نگاشت می‌شوند که \fBpnmcolormap\fP برای نمایندگی جعبه دیگری انتخاب کرده است و در واقع رنگی که \fBpnmcolormap\fP برای نمایندگی جعبه B انتخاب کرده ممکن است اصلاً در خروجی \fBpnmremap\fP ظاهر نشود.
  

.UN references
.SH "منابع (REFERENCES)"

"Color Image Quantization for Frame Buffer Display" نوشته Paul Heckbert، مجموعه مقالات SIGGRAPH '82، صفحه ۲۹۷.

.UN seealso
.SH "همچنین ببینید (SEE ALSO)"
.BR "pnmremap" (1)\c
\&,
.BR "pnmquant" (1)\c
\&,
.BR "ppmquantall" (1)\c
\&,
.BR "pamgetcolor" (1)\c
\&,
.BR "pamdepth" (1)\c
\&,
.BR "ppmdither" (1)\c
\&,
.BR "pamseq" (1)\c
\&,
.BR "ppmmake" (1)\c
\&,
.BR "pamcat" (1)\c
\&,
.BR "ppm" (1)\c
\&

.UN history
.SH "تاریخچه (HISTORY)"
.PP
پیش از Netpbm 10.15 (آوریل ۲۰۰۳)، \fBpnmcolormap\fP برای تصاویر بزرگ حافظه بسیار بیشتری مصرف می‌کرد زیرا کل تصویر ورودی را در حافظه نگه می‌داشت. اکنون، آن را سطر به سطر پردازش می‌کند، اما چون گاهی باید چندین گذر روی تصویر انجام دهد، اگر ورودی قبلاً در یک فایل با قابلیت جستجو (seekable) نباشد، ابتدا ورودی را در یک فایل موقت قابل جستجو کپی می‌کند.
.PP
برنامه \fBpnmcolormap\fP نخستین بار در Netpbm 9.23 (ژانویه ۲۰۰۲) ظاهر شد. پیش از آن، عملکرد آن تنها به عنوان بخشی از قابلیت \fBpnmquant\fP (که برگرفته از برنامه بسیار قدیمی‌تر \fBppmquant\fP بود) در دسترس بود. کوانتیزاسیون رنگ در واقع دو زیرکارکرد اصلی دارد، بنابراین Netpbm 9.23 آن را به دو برنامه جداگانه تقسیم کرد: \fBpnmcolormap\fP و \fBpnmremap\fP، و سپس Netpbm 9.24 برنامه \fBpnmquant\fP را با برنامه‌ای جایگزین کرد که صرفاً \fBpnmcolormap\fP و \fBpnmremap\fP را فراخوانی می‌کند.

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

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