\
.\" 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 "Ppmdraw User Manual" 0 "17 mAY 2025" "netpbm documentation"

.SH "نام (NAME)"
ppmdraw \- رسم و ویرایش خطوط، اشکال هندسی و متن بر روی تصویر PPM

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

\fBppmdraw\fP

{
\fB-script=\fP\fIscript\fP
|
\fB-scriptfile=\fP\fIfilename\fP
}
[\fB-verbose\fP]

[\fIppmfile\fP]
.PP
تمامی گزینه‌ها را می‌توان به کوتاه‌ترین پیشوند یکتای آن‌ها خلاصه کرد.
می‌توانید به‌جای یک خط تیره از دو خط تیره برای مشخص کردن گزینه استفاده کنید.
همچنین می‌توانید بین نام گزینه و مقدار آن از فاصله یا علامت مساوی استفاده نمایید.


.UN description
.SH "توضیحات (DESCRIPTION)"
.PP
این برنامه بخشی از
.BR "Netpbm" (1)\c
\& است.
.PP
برنامه \fBppmdraw\fP خطوط، اشکال هندسی، متن و موارد دیگر را روی یک تصویر PPM رسم می‌کند.
این ابزار در اصل یک رابط کاربری ساده برای زیرروال‌های "ppmd" در کتابخانه \fBlibnetpbm\fP است
و به شما امکان می‌دهد تا به‌جای نوشتن یک برنامه به زبان C، از یک اسکریپت ساده و
انسان‌فهم برای توصیف ترسیمات استفاده کنید.
.PP
شما دستورالعمل‌های ترسیم را از طریق یک اسکریپت ارائه می‌دهید؛ این اسکریپت یا در
فایلی قرار دارد که با گزینه \fB-scriptfile\fP مشخص می‌شود و یا به عنوان مقدار
گزینه \fB-script\fP ارسال می‌گردد. در ادامه یک نمونه اسکریپت آورده شده است:

.nf
\f(CW
setpos 50 50;
text_here 10 30 "hello";
setcolor black;
text_here 10 0 "there";
line_here 5 20;
\fP
.fi
.PP
این مثال از ستون ۵۰ و سطر ۵۰ تصویر ورودی شروع می‌کند و کلمه "hello" را با
حروف سفید به ارتفاع ۱۰ پیکسل و با زاویه ۳۰ درجه نسبت به خط افق می‌نویسد.
سپس از نقطه‌ای که متن اول پایان یافته، کلمه "there" را به صورت افقی با حروف
سیاه به ارتفاع ۱۰ پیکسل درج می‌کند. در نهایت، یک خط سیاه تا نقطه‌ای به فاصله
۵ پیکسل به سمت راست و ۲۰ پیکسل به سمت پایین از انتهای کلمه "there" رسم می‌نماید.
.PP
اگر \fIppmfile\fP را مشخص نکنید، \fBppmdraw\fP تصویر PPM ورودی را از ورودی استاندارد (Standard Input) می‌خواند.
.PP
تصویر خروجی به خروجی استاندارد (Standard Output) فرستاده می‌شود.
.PP
برنامه \fBppmdraw\fP روی جریان‌های چندتصویری نیز کار می‌کند. این برنامه اسکریپت
یکسانی را روی هر تصویر ورودی اجرا کرده و یک جریان خروجی شامل یک تصویر به ازای هر تصویر
ورودی تولید می‌کند. اما پیش از نسخه Netpbm 10.32 (فوریه ۲۰۰۶)، \fBppmdraw\fP تمامی
تصاویر پس از تصویر اول را نادیده می‌گرفت.
.PP
اگر تنها قصد دارید یک خط متن ساده به تصویر اضافه کنید، ممکن است برنامه
\fBppmlabel\fP گزینه مناسب‌تری برای شما باشد.


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



.TP
\fB-script=\fP\fIscript\fP
این گزینه متن اسکریپت را مشخص می‌کند. بخش
.UR #script
اسکریپت
.UE
را ببینید.
.sp
نمی‌توانید هر دو گزینه \fB-script\fP و \fB-scriptfile\fP را هم‌زمان مشخص کنید.

.TP
\fB-scriptfile=\fP\fIfilename\fP
این گزینه نام فایلی را مشخص می‌کند که حاوی اسکریپت است. مقدار \fB-\fP
به معنای ورودی استاندارد است.
.sp
نمی‌توانید هر دو گزینه \fB-script\fP و \fB-scriptfile\fP را هم‌زمان مشخص کنید.
.sp
نمی‌توانید مقدار \fB-\fP (ورودی استاندارد) را هم‌زمان برای \fB-scriptfile\fP
و فایل تصویر ورودی استفاده کنید.




.UN script
.SH "اسکریپت (SCRIPT)"
.PP
هسته اصلی عملکرد \fBppmdraw\fP اسکریپت آن است. اسکریپت یک جریان کاراکتری متشکل
از دستورات مختلف است. دستورات با نقطه-ویرگول (;) از یکدیگر جدا می‌شوند. فاصله‌های
خالی (White space) همانند زبان C در نظر گرفته می‌شوند: هر دنباله پیوسته از فاصله‌های
خالی خارج از نقل‌قول معادل یک نویسه فاصله تکی است. توجه داشته باشید که این موضوع
بدین معناست که شکستگی‌های خط (Newlines) هیچ اهمیت خاصی ندارند.
.PP
هر دستور از توکن‌هایی تشکیل شده است که با فاصله خالی از یکدیگر جدا می‌شوند. برای
نوشتن توکنی که حاوی فاصله خالی است، آن را داخل نقل‌قول دوتایی (Double quotes) قرار
دهید. تمام محتوای بین دو علامت نقل‌قول جفت، یک توکن واحد محسوب می‌شود.
.PP
اولین توکن هر دستور یک «فعل» (Verb) است که عملکرد اصلی دستور را مشخص می‌کند.
سایر توکن‌های دستور آرگومان‌ها هستند که معنای آن‌ها به فعل مورد نظر بستگی دارد.
فهرست زیر تمام فعل‌های معتبر، معنا و آرگومان‌های هر یک را شرح می‌دهد.
.PP
بسیاری از دستورات دارای آرگومان‌هایی برای تعیین موقعیت روی بوم نقاشی هستند که
با سطر و ستون مشخص می‌شوند. سطر ۰ بالاترین سطر و ستون ۰ چپ‌ترین ستون است.
می‌توانید اعداد منفی نیز مشخص کنید (اما چنین موقعیتی لزوماً خارج از بوم نقاشی خواهد بود).
.PP
دستورالعمل‌های ترسیم شما ممکن است شامل موقعیت‌های خارج از بوم نقاشی باشند؛
در این حالت هر پیکسلی که در خارج از بوم رسم شود نادیده گرفته و دور ریخته می‌شود.


.TP
setpos
تنظیم موقعیت جاری ("current position") در تصویر. این موقعیت مشخص می‌کند که
دستورات بعدی ترسیمات را از کجا انجام دهند. ۲ آرگومان این دستور شماره ستون و
شماره سطر هستند.
.sp
در ابتدای اسکریپت، موقعیت جاری برابر با (0,0) است.

.TP
setlinetype
دارای ۱ آرگومان با مقدار "normal" یا "nodiag." است. این دستور تابع
\fBppmd_setlinetype()\fP را فراخوانی می‌کند. جزئیات بیشتر هنوز مستند نشده است.

.TP
setlineclip
این دستور تابع \fBppmd_setlineclip()\fP را فراخوانی می‌کند. هنوز مستند نشده است.

.TP
setcolor
تنظیم رنگ جاری ("current color") که رنگ ترسیمات دستورات بعدی را تعیین می‌کند.
پیش از اولین دستور \fBsetcolor\fP، رنگ جاری سفید است.
.sp
این دستور یک آرگومان دارد که رنگ را مطابق توضیحات
.UR libnetpbm_image.html#colorname
آرگومان تابع کتابخانه‌ای \fBpnm_parsecolor()\fP
.UE
مشخص می‌کند.

.TP
setfont
تنظیم قلم جاری ("current font") که قلم مورد استفاده در دستورات بعدی رسم متن را
تعیین می‌کند. پیش از اولین دستور \fBsetfont\fP، قلم جاری یک قلم پیش‌ساخته به نام
"standard" است.
.sp
آرگومان این دستور نام یک فایل است که نام فایل قلم PPMD در Netpbm می‌باشد.
.sp
یک فایل قلم PPMD در Netpbm معمولاً نامی دارد که به ".ppmdfont" ختم می‌شود و
۸ بایت اول آن معادل کد اسکی "ppmdfont" است.
.sp
تا آنجا که می‌دانیم تنها یکی از این قلم‌ها وجود دارد. این قلم همراه با Netpbm
در قالب فایل \fBstandard.ppmdfont\fP توزیع شده است، اما نیازی به استفاده از آن
فایل ندارید زیرا همان قلم درون کتابخانه Netpbm تعبیه شده و پیش‌فرض است. اگر می‌خواهید
قلم جدیدی بسازید، می‌توانید ساختار فایل ppmdfont را در فایل هدر رابط Netpbm با نام
\fBppmdfont.h\fP بیابید، هرچند برای ساخت آن باید ابزارهای اختصاصی خود را بسازید.
برنامه \fBppmdmkfont\fP فایل \fBstandard.ppmdfont\fP را تولید می‌کند، بنابراین
می‌توانید از آن به عنوان نمونه استفاده کنید.

.TP
line
رسم یک خط با ضخامت ۱ پیکسل با رنگ جاری. ۴ آرگومان آن عبارتند از:
ستون شروع، سطر شروع، ستون پایان، سطر پایان.
.sp
این دستور تاثیری روی موقعیت جاری ندارد.

.TP
line_here
این دستور مشابه \fBline\fP است، با این تفاوت که به صورت نسبی عمل می‌کند.
.sp
خط از نقطه جاری شروع می‌شود. دو آرگومان این دستور میزان جابه‌جایی به سمت راست
و به سمت پایین از نقطه جاری تا نقطه پایانی هستند. این دستور پس از رسم خط، موقعیت
جاری را به نقطه پایانی منتقل می‌کند.

.TP
spline3
رسم یک منحنی اسپلاین (Spline) با رنگ جاری بین ۲ نقطه، با استفاده از نقطه سوم
به عنوان نقطه کنترل. این دستور یک قطعه اسپلاین درجه سه (Cubic spline) را تقریب می‌زند.
.sp
شکل منحنی به گونه‌ای است که از نقاط انتهایی مشخص‌شده عبور می‌کند و خطوط مماس
بر منحنی در آن نقاط انتهایی، در نقطه کنترل یکدیگر را قطع می‌کنند. کنترل خطوط مماس
به شما اجازه می‌دهد این منحنی را به منحنی‌های دیگری که به همین روش ایجاد شده‌اند
متصل کنید بدون اینکه در نقاط اتصال گوشه‌های تیز ایجاد شود.
.sp
۶ آرگومان این دستور عبارتند از: ستون نقطه شروع، سطر نقطه شروع، ستون نقطه کنترل،
سطر نقطه کنترل، ستون نقطه پایان و سطر نقطه پایان.
.sp
این دستور تاثیری روی موقعیت جاری ندارد.

.TP
circle
رسم یک دایره توخالی با رنگ جاری. سه آرگومان آن عبارتند از شماره ستون و
شماره سطر مرکز دایره، و شعاع دایره بر حسب پیکسل.

.TP
filledcircle
مشابه \fBcircle\fP است با این تفاوت که دایره با رنگ جاری پر می‌شود. این رده از
دستورات در نسخه Netpbm 10.59 (ژوئن ۲۰۱۲) معرفی شد.

.TP
filledrectangle
رسم یک مستطیل توپر با رنگ جاری.
.sp
۴ آرگومان آن عبارتند از شماره ستون و سطر گوشه بالا-چپ مستطیل، عرض مستطیل و ارتفاع مستطیل.

.TP
text
رسم متن با رنگ جاری و با استفاده از قلم پیش‌ساخته. ۵ آرگومان آن عبارتند از:


.IP \(bu
شماره ستون نقطه شروع خط کرسی (Baseline)
.IP \(bu
شماره سطر نقطه شروع خط کرسی
.IP \(bu
ارتفاع نویسه‌ها بر حسب پیکسل
.IP \(bu
زاویه خط کرسی به درجه نسبت به افق
.IP \(bu
متن

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

.TP
text_here
این دستور مشابه \fBtext\fP است، با این تفاوت که خط کرسی از موقعیت جاری آغاز می‌شود
و دستور پس از رسم متن، موقعیت جاری را به انتهای دیگر خط کرسی به‌روزرسانی می‌کند.
.sp
به خاطر داشته باشید که اسکریپت با موقعیت جاری در بالاترین سطر شروع می‌شود،
بنابراین اگر آن را در همان‌جا رها کنید، فقط خط پایینی متن شما در داخل تصویر قرار خواهد گرفت!



.UN history
.SH "تاریخچه (HISTORY)"
.PP
دستور \fBppmdraw\fP در Netpbm 10.29 (اوت ۲۰۰۵) معرفی شد.


.UN seealso
.SH "همچنین ببینید (SEE ALSO)"
.BR "ppmlabel" (1)\c
\&،
.BR "ppm" (1)\c
\&،
.BR "libnetpbm_draw" (1)\c
\&
.SH "منبع سند (DOCUMENT SOURCE)"
این صفحه راهنما توسط ابزار 'makeman' از Netpbm و از روی منبع HTML تولید شده است.
مستندات مرجع اصلی در نشانی زیر قرار دارد:
.IP
.B http://netpbm.sourceforge.net/doc/ppmdraw.html
.PP