\
.\" 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 "Ppmtoarbtxt User Manual" 0 "26 November 2014" "netpbm documentation"

.SH "نام (NAME)"
ppmtoarbtxt \- تولید تصویر در قالب متنی دلخواه از یک تصویر PPM

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

\fBppmtoarbtxt\fP
\fIbodytmpl\fP
[\fB-hd\fP \fIheadtmpl\fP]
[\fB-tl\fP \fItailtmpl\fP]
[\fIppmfile\fP]

.UN description
.SH "توضیحات (DESCRIPTION)"
.PP
این برنامه بخشی از
.BR "Netpbm" (1)\c
\& است.
.PP
دستور \fBppmtoarbtxt\fP قالب‌های گرافیکی متنی ساده را بر مبنای توصیف ساختار ارائه‌شده به عنوان ورودی تولید می‌کند. قالب گرافیکی متنی قالبی است که در آن یک تصویر توسط متن نمایش داده می‌شود (مانند فرمت متنی plain در PNM، بر خلاف فرمت دودویی raw در PNM).
.PP
دستور \fBppmtoarbtxt\fP یک تصویر PPM را به عنوان ورودی می‌خواند. برای هر پیکسل در تصویر، \fBppmtoarbtxt\fP محتویات فایل قالب بدنه (\fIbodytmpl\fP) را با انجام جایگزینی‌های مشخص بر اساس مقدار آن پیکسل، در خروجی استاندارد (stdout) می‌نویسد.
.PP
شما همچنین می‌توانید یک فایل قالب سربرگ (head template) مشخص کنید؛ در این حالت \fBppmtoarbtxt\fP متنی را بر اساس ابعاد تصویر از فایل قالب تولید کرده و آن را پیش از هر چیز دیگری در خروجی قرار می‌دهد.
.PP
به همین ترتیب، می‌توانید یک فایل قالب پاورقی (tail template) ارائه دهید تا متن مربوطه در انتهای خروجی درج شود.


.UN templatefiles
.SS "فایل‌های قالب (Template Files)"
.PP
متنی که \fBppmtoarbtxt\fP از یک فایل قالب تولید می‌کند، همان متن تحت‌اللفظی فایل قالب است، با این تفاوت که مشخص‌کننده‌های جایگزینی با مقادیر مربوطه جایگزین می‌شوند. برنامه یک مشخص‌کننده جایگزینی را به صورت متنی در قالب \fB#(\fP...\fB)\fP تشخیص می‌دهد.
.PP
دستور \fBppmtoarbtxt\fP با فاصله‌ها (white space) در فایل‌های قالب مانند هر نویسه دیگری رفتار می‌کند و آن‌ها را در خروجی قرار می‌دهد، به جز یک مورد استثنا: اگر فایل قالب با نویسه خط جدید (newline) پایان یابد، \fBppmtoarbtxt\fP آن را نادیده گرفته و در خروجی درج نمی‌کند.
.PP
بسیاری از مشخص‌کننده‌های جایگزینی از رشته‌های قالب‌بندی (فرمی دیگر از الگو) برای تعیین نحوه جایگزینی استفاده می‌کنند. شما باید این رشته‌های فرمت را تا حد ممکن مینیمال و ساده بنویسید و متن‌های تحت‌اللفظی را به جای قرار دادن درون رشته فرمت، بیرون از مشخص‌کننده جایگزینی قرار دهید. به عنوان مثال:
.PP
اشتباه: \f(CW#(flum %%%2.2f 0 1) \fP
.PP
صحیح: \f(CW%#(flum %2.2f 0 1) \fP
.PP
مشخص‌کننده‌های مجاز جایگزینی به شرح زیر هستند. متنی که به شکل یک مشخص‌کننده جایگزینی باشد اما در عمل معتبر نباشد (مانند \fB#(random junk)\fP)، معمولاً به صورت همان متن تحت‌اللفظی درج می‌شود، اما اگر شباهت زیادی به یک مشخص‌کننده معتبر داشته باشد، \fBppmtoarbtxt\fP فرض می‌کند که خطایی رخ داده است و اجرا ناموفق خواهد بود.
.PP
مشخص‌کننده‌های کاربردی در قالب بدنه، برای انجام جایگزینی بر اساس یک پیکسل خاص:


.TP
\fB#(ired\fP\fI format blackref whiteref\fP\fB)\fP
یک عدد صحیح در بازه بین \fIblackref\fP تا \fIwhiteref\fP با قالب مشخص‌شده توسط \fIformat\fP تولید می‌کند که نشان‌دهنده شدت رنگ قرمز پیکسل است. شدت رنگ قرمز صفر تبدیل به \fIblackref\fP می‌شود؛ شدت رنگ قرمز با بیشترین مقدار (maxval) تبدیل به \fIwhiteref\fP شده و بقیه مقادیر به صورت خطی در این میان درون‌یابی می‌شوند.
.sp
آرگومان \fIformat\fP یک مشخص‌کننده فرمت شبیه به printf مانند "%d" است. دستور \fBppmtoarbtxt\fP از آن به عنوان کل رشته فرمت برای فراخوانی تابع سیستمی POSIX بنام \fBfprintf\fP استفاده می‌کند که تنها آرگومان دیگر آن شدت رنگ قرمز به عنوان یک نوع داده عددی صحیح است. دستور \fBppmtoarbtxt\fP الزاماً منطقی بودن رشته فرمت شما را بررسی نمی‌کند؛ حتی مقادیری وجود دارند که ممکن است باعث کرش کردن برنامه شوند. برای جلوگیری از رفتارهای غیرمنتظره، رشته‌های فرمت را ساده و ثابت نگه دارید و هرگز از علامت درصد اضافی یا خط جدید استفاده نکنید.
.sp
عبارت \fB#(ired)\fP معادل \fB#(ired %d 0 255)\fP است.

.TP
\fB#(igreen\fP\fI format blackref whiteref\fP\fB)\fP
مشابه \fB#(ired...\fP است، اما برای رنگ سبز عمل می‌کند.

.TP
\fB#(iblue\fP\fI format blackref whiteref\fP\fB)\fP
مشابه \fB#(ired...\fP است، اما برای رنگ آبی عمل می‌کند.

.TP
\fB#(ilum\fP\fI format blackref whiteref\fP\fB)\fP
مشابه \fB#(ired...\fP است، اما مقدار روشنایی (luminance) پیکسل را نمایش می‌دهد:
(0.299*red + 0.587*green + 0.114*blue).

.TP
\fB#(fred\fP\fI format blackref whiteref\fP\fB)\fP
مشابه \fB#(ired...\fP است، اما به جای یک عدد صحیح، یک عدد ممیز شناور تولید می‌کند.
.sp
در این حالت، آرگومان دوم ارسالی به تابع \fBfprintf\fP که از \fIformat\fP استفاده می‌کند، نوع داده اعشاری با دقت مضاعف (double precision floating point) است.
.sp
عبارت \fB#(fred)\fP معادل \fB#(fred %f 0.0 1.0)\fP است.

.TP
\fB#(fgreen \fP\fIformat blackref whiteref\fP\fB)\fP
مشابه \fB#(fred...\fP است، اما برای رنگ سبز به کار می‌رود.

.TP
\fB#(fblue \fP\fIformat blackref whiteref\fP\fB)\fP
مشابه \fB#(fred...\fP است، اما برای رنگ آبی به کار می‌رود.

.TP
\fB#(flum \fP\fIformat blackref whiteref\fP\fB)\fP
مشابه \fB#(fred...\fP است، اما مقدار روشنایی پیکسل را نمایش می‌دهد:
(0.299*red + 0.587*green + 0.114*blue).

.TP
\fB#(posx \fP\fIformat\fP\fB)\fP
موقعیت افقی پیکسل را بر حسب پیکسل از لبه چپ تصویر تولید می‌کند.
.sp
آرگومان دوم در فراخوانی تابع \fBfprintf\fP که از \fIformat\fP استفاده می‌کند دارای نوع داده عدد صحیح بدون علامت (unsigned integer) است.
.sp
مقدار پیش‌فرض \fIformat\fP برابر با \fB%u\fP است.

.TP
\fB#(posy \fP\fIformat\fP\fB)\fP
مشابه \fB#(width...\fP است، اما برای موقعیت عمودی پیکسل به کار می‌رود.


.PP
اگر از هر یک از مشخص‌کننده‌های جایگزینی فوق در قالب سربرگ یا پاورقی استفاده کنید، نتیجه تعریف‌نشده خواهد بود.
.PP
مشخص‌کننده‌های کاربردی در قالب سربرگ یا پاورقی، برای انجام جایگزینی‌ها بر پایه ویژگی‌های کل تصویر:


.TP
\fB#(width \fP\fIformat\fP\fB)\fP
عرض تصویر را بر حسب پیکسل تولید می‌کند.
.sp
آرگومان دوم ارسالی به \fBfprintf\fP که از \fIformat\fP استفاده می‌کند، نوع داده عدد صحیح بدون علامت دارد.
.sp
مقدار پیش‌فرض \fIformat\fP برابر با \fB%u\fP است.

.TP
\fB#(height \fP\fIformat\fP\fB)\fP
مشابه \fB#(width...\fP است، اما برای ارتفاع تصویر به کار می‌رود.




.UN options
.SH "گزینه‌ها (OPTIONS)"
.PP
علاوه بر گزینه‌های مشترک برای تمام برنامه‌های مبتنی بر libnetpbm (به‌ویژه \fB-quiet\fP، به
.UR index.html#commonoptions
گزینه‌های مشترک (Common Options)
.UE
مراجعه کنید)، دستور \fBppmtoarbtxt\fP گزینه‌های خط فرمان زیر را نیز می‌شناسد:


.TP
\fB-hd\fP \fIheadtmpl\fP
این گزینه یک قالب سربرگ را تعیین می‌کند (\fIheadtmpl\fP نام فایل قالب سربرگ است)؛ این گزینه باعث می‌شود \fBppmtoarbtxt\fP محتویات فایل با نام \fIheadtmpl\fP را در ابتدای خروجی قرار دهد.

.TP
\fB-tl\fP \fItailtmpl\fP
این گزینه یک قالب پاورقی را مشخص می‌کند؛ و ساختاری مشابه با \fB-hd\fP دارد.



.UN examples
.SH "مثال‌ها (EXAMPLES)"

.SS "وارونگی خاکستری (gray inversion)"
.PP
در اینجا تصویری در قالب متنی ساده PGM همراه با معکوس‌سازی خاکستری تولید می‌کنیم
(مشابه \fBppmtopgm | pnminvert\fP).
.PP
محتویات فایل قالب سربرگ ما:

.nf
P2
#(width) #(height)
255
.fi
.PP
محتویات فایل قالب بدنه ما:

.nf
#(ilum %d 255 0)
.fi

.SS "فایل povray"
.PP
در اینجا یک فایل povray تولید می‌کنیم که در آن هر پیکسل با کره‌ای در مختصات (x,y,z) = (posx,height-posy,luminance) نمایش داده می‌شود. رنگ کره همان رنگ پیکسل خواهد بود.
.PP
محتویات قالب سربرگ ما:

.nf
#include "colors.inc"
#include "textures.inc"
camera {
   location  <#(width) * 0.6, #(height) * 0.7, 80>
   look_at   <#(width) * 0.5, #(height) * 0.5, 0>
}

light_source { <#(width) * 0.5, #(height) * 0.5, 25> color White
}
.fi
.PP
محتویات قالب بدنه ما:

.nf
sphere { <#(posx),#(height)-#(posy),#(ilum %d 0 10)>, 0.5
  texture {
    pigment {
      color rgb <#(fred),#(fgreen),#(fblue)>
    }
    finish {
      phong 1
    }
  }
}
.fi

.UN seealso
.SH "همچنین ببینید (SEE ALSO)"
.BR "pnmtoplainpnm" (1)\c
\&, 
.BR "pamtable" (1)\c
\&, 
.BR "ppm" (1)\c
\&

.UN history
.SH "تاریخچه (HISTORY)"
.PP
دستور \fBppmtoarbtxt\fP در نسخه ۱۰.۱۴ بسته Netpbm (مارس ۲۰۰۳) اضافه شد. این ابزار از سال ۱۹۹۵ با نام \fBppmtotxt\fP وجود داشته است.

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

حق نشر (C) ۱۹۹۵ متعلق به Peter Kirchgessner
.SH "منبع سند (DOCUMENT SOURCE)"
این صفحه راهنما توسط ابزار «makeman» از Netpbm از منبع HTML تولید شده است. مستندات مرجع در نشانی زیر در دسترس است:
.IP
.B http://netpbm.sourceforge.net/doc/ppmtoarbtxt.html
.PP