هوش مصنوعی در Houdini؛ آموزش کامل Machine Learning، ساخت VFX و اتصال به API

Houdini یکی از قدرتمندترین نرم‌افزارهای سه‌بعدی برای ساخت جلوه‌های ویژه، شبیه‌سازی، مدل‌سازی Procedural، تخریب، آتش، دود، مایعات، پارچه، مو، محیط و محتوای بازی است. برخلاف بسیاری از نرم‌افزارهای سه‌بعدی که بر ویرایش مستقیم آبجکت‌ها تمرکز دارند، Houdini بیشتر عملیات را در قالب شبکه‌ای از Nodeها نگه می‌دارد.

این ساختار Node-based باعث می‌شود Houdini بستر مناسبی برای ترکیب فرایندهای Procedural با یادگیری ماشین و هوش مصنوعی باشد. هوش مصنوعی در Houdini فقط به تولید تصویر مرجع یا دریافت کد از یک مدل زبانی محدود نیست؛ خود Houdini زیرساختی برای تولید داده مصنوعی، آموزش مدل، اجرای Inference و استفاده از مدل‌های ONNX دارد.

کاربردهای هوش مصنوعی در Houdini را می‌توان به چند گروه تقسیم کرد:

• تولید و پردازش داده برای Machine Learning
• ساخت Terrain با مدل‌های عصبی
• افزایش جزئیات دود و Volume
• آموزش ML Deformer
• اجرای مدل‌های ONNX روی Geometry و Volume
• ساخت داده مصنوعی برای آموزش مدل
• طراحی شبکه Nodeها با کمک مدل زبانی
• تولید VEX و Python
• تحلیل و مستندسازی شبکه‌های Houdini
• ساخت ابزار هوشمند داخل HDA
• اتصال Houdini به مدل‌های هوش مصنوعی از طریق API
• ساخت Pipeline خودکار با PDG و TOPs

در این مقاله با قابلیت‌های واقعی و داخلی Houdini آشنا می‌شویم و یک جریان کاری عملی برای اتصال آن به API هوش مصنوعی درواره می‌سازیم.

آیا Houdini هوش مصنوعی داخلی دارد؟

بله. Houdini دارای یک چارچوب Machine Learning است که مراحل مختلف کار با مدل‌های یادگیری ماشین را پوشش می‌دهد:

• تولید داده
• ساخت نمونه‌های دارای Label
• پیش‌پردازش داده
• آموزش مدل
• ارزیابی مدل
• ذخیره و Export مدل
• اجرای مدل آموزش‌دیده
• استفاده از ONNX برای Inference
• پردازش موازی داده با PDG و TOPs

براساس مستندات رسمی Machine Learning در Houdini، Houdini بستری برای تولید داده مصنوعی، پیش‌پردازش، آموزش، Export و استقرار مدل آموزش‌دیده فراهم می‌کند.

این موضوع با ابزارهای مولد عمومی تفاوت دارد. Houdini را نباید صرفاً یک ابزار تبدیل متن به صحنه سه‌بعدی دانست. نقطه قوت آن استفاده از Machine Learning داخل یک Pipeline کنترل‌پذیر و Procedural است.

تفاوت هوش مصنوعی، Machine Learning و Procedural Workflow در Houdini

همه عملیات خودکار Houdini هوش مصنوعی نیستند.

ابزار Procedural طبق Rule و شبکه‌ای که هنرمند ساخته عمل می‌کند. مدل Machine Learning رفتار را از داده‌های آموزشی یاد می‌گیرد.

ترکیب این دو روش بسیار قدرتمند است. برای مثال، شبکه Procedural هزاران Terrain متفاوت تولید می‌کند، این داده‌ها برای آموزش مدل استفاده می‌شوند و مدل آموزش‌دیده بعداً نتیجه مشابه را با سرعت بیشتری تخمین می‌زند.

هوش مصنوعی در Houdini برای چه کسانی مفید است؟

این قابلیت‌ها برای گروه‌های زیر کاربرد بیشتری دارند:

• هنرمندان جلوه‌های ویژه
• Technical Artistها
• توسعه‌دهندگان ابزارهای سه‌بعدی
• استودیوهای بازی‌سازی
• متخصصان شبیه‌سازی
• طراحان محیط و Terrain
• توسعه‌دهندگان Houdini Digital Asset
• متخصصان Pipeline
• پژوهشگران Computer Graphics
• تیم‌های تولید داده مصنوعی
• هنرمندان Procedural
• برنامه‌نویسان Python و VEX

برای استفاده روزمره از بعضی قابلیت‌ها مانند ML Volume Upres لازم نیست متخصص یادگیری ماشین باشید. اما آموزش مدل اختصاصی، طراحی Dataset و ارزیابی خروجی به دانش فنی بیشتری نیاز دارد.

مهم‌ترین قابلیت‌های هوش مصنوعی Houdini

Neural Terrain Paint

Neural Terrain Paint برای ایجاد و ویرایش Heightfield با استفاده از مدل یادگیری ماشین طراحی شده است. هنرمند می‌تواند به‌صورت تعاملی روی Terrain کار کند و مدل عصبی الگوهای بزرگ‌تر و پیچیده‌تر زمین را تولید کند.

SideFX در معرفی قابلیت‌های Machine Learning هودینی، Neural Terrain Paint را به‌عنوان نمونه‌ای از ترکیب مدل ML با Heightfield SOPها برای ساخت محیط‌های وسیع معرفی کرده است. قابلیت‌های Machine Learning در Houdini

ML Volume Upres

ML Volume Upres برای افزایش وضوح و جزئیات Volume به کار می‌رود. این Node می‌تواند یک VDB یا Volume داخلی Houdini را دریافت کند و با استفاده از مدل ONNX آموزش‌دیده، خروجی را Upscale و Sharpen کند.

براساس مستندات ML Volume Upres، این Node برای پردازش VDB و Houdini Volume طراحی شده و می‌توان مدل اختصاصی آن را نیز با Recipe مربوط به Volume Upres آموزش داد.

ML Deformer

ML Deformer می‌تواند تغییر شکل پیچیده یک Geometry را از روی داده‌های آموزشی تقریب بزند. این روش برای فرایندهایی مناسب است که اجرای کامل آن‌ها در هر فریم هزینه زیادی دارد.

نمونه کاربردها:

• تقریب شبیه‌سازی Muscle
• Deformation لباس
• تغییر شکل Soft Body
• اصلاح Skinning
• تقریب نتیجه یک شبکه پیچیده
• ساخت Deformer سریع‌تر برای استفاده تعاملی
• انتقال نتیجه شبیه‌سازی سنگین به Pipeline سبک‌تر

ONNX Inference

ONNX یک قالب استاندارد برای انتقال مدل‌های آموزش‌دیده میان ابزارهای مختلف است. مدلی که در PyTorch یا TensorFlow آموزش داده شده می‌تواند به ONNX تبدیل و داخل Houdini اجرا شود.

Node مربوط به ONNX Inference می‌تواند مدل آموزش‌دیده را روی Point Data یا Volume اجرا کند. مستندات ONNX Inference در Houdini

Synthetic Data Generation

Houdini به دلیل ماهیت Procedural خود برای تولید داده مصنوعی بسیار مناسب است. می‌توان هزاران نسخه متفاوت از یک صحنه تولید کرد و برای هر نمونه، Label و Metadata دقیق داشت.

برای مثال:

• تولید تصاویر خودرو با زاویه‌های مختلف
• تولید اشیای صنعتی با تغییرات کنترل‌شده
• ساخت Terrainهای مختلف
• تولید داده شبیه‌سازی دود
• ساخت تصاویر دارای Mask و Depth
• تولید Bounding Box و Segmentation
• ساخت داده برای تشخیص اشیا
• تولید نمونه‌های آموزشی برای Deformer

PDG و TOPs

PDG و TOPs برای تقسیم یک فرایند بزرگ به Work Itemهای کوچک و قابل زمان‌بندی استفاده می‌شوند. خود PDG هوش مصنوعی نیست، اما برای تولید Dataset، آموزش چند مدل، ارزیابی Hyperparameterها و اجرای Batch Inference بسیار مفید است.

Neural Terrain چیست؟

در روش سنتی ساخت Terrain معمولاً چند Noise، Mask، Erosion و Heightfield Operation را با هم ترکیب می‌کنیم. این روش کنترل زیادی دارد، اما ساخت فرم‌های طبیعی و متنوع می‌تواند زمان‌بر باشد.

Neural Terrain یک مدل Machine Learning را وارد این جریان می‌کند. مدل می‌تواند الگوهایی را که از Terrainهای آموزشی یاد گرفته است روی ورودی جدید اعمال کند.

مزایای Neural Terrain

• ساخت سریع تنوع‌های مختلف
• ایجاد جزئیات طبیعی‌تر
• تعامل مستقیم هنرمند با Terrain
• ترکیب با Heightfield SOPها
• حفظ کنترل Procedural
• استفاده از داده اختصاصی پروژه
• ساخت ابزار HDA برای طراح محیط

محدودیت‌ها

• کیفیت خروجی به Dataset وابسته است.
• مدل ممکن است Formهای تکراری تولید کند.
• Scale زمین باید با داده آموزشی هماهنگ باشد.
• مدل از هدف داستانی یا طراحی مرحله اطلاع ندارد.
• رودخانه، مسیر و محل ساختمان‌ها باید کنترل شوند.
• خروجی همچنان به Mask، Erosion و اصلاح Procedural نیاز دارد.

آموزش عملی جریان کاری Neural Terrain

رابط و نام دقیق HDAها ممکن است با نسخه Houdini و فایل‌های نمونه SideFX تغییر کند، اما ساختار کلی فرایند ثابت است.

مرحله اول: ساخت Heightfield پایه

یک Geometry Object بسازید و داخل آن شبکه پایه را ایجاد کنید:

HeightField
    ↓
HeightField Noise
    ↓
HeightField Mask by Feature
    ↓
HeightField Erode

هدف این مرحله ساخت زمین کامل نیست. فقط باید ورودی مناسبی برای مدل یا ابزار Neural Terrain فراهم شود.

مرحله دوم: تعیین Scale

ابعاد Heightfield را با Scale مورد انتظار مدل هماهنگ کنید. اگر مدل با Terrainهای کوچک آموزش دیده باشد، ورودی بسیار بزرگ ممکن است نتیجه نامناسبی ایجاد کند.

این موارد را ثبت کنید:

• Width
• Height
• Grid Spacing
• ارتفاع حداقل و حداکثر
• واحد اندازه‌گیری
• محورهای مختصات
• رزولوشن Heightfield

مرحله سوم: افزودن Neural Terrain HDA

HDA یا فایل نمونه Neural Terrain را وارد پروژه کنید و Heightfield پایه را به ورودی آن متصل کنید.

سپس پارامترهای اصلی را به‌صورت تدریجی تغییر دهید:

• شدت تأثیر مدل
• اندازه قلم
• نوع Terrain
• Seed
• Blend
• Mask
• تعداد Iteration
• Scale جزئیات

مرحله چهارم: ساخت Mask

اثر مدل را روی تمام Terrain اعمال نکنید. با Mask مشخص کنید کدام مناطق اجازه تغییر دارند.

برای مثال:

• محل جاده بدون تغییر بماند.
• اطراف ساختمان‌ها Flat باشد.
• دره فقط در منطقه مشخص ساخته شود.
• کوه‌ها در پس‌زمینه قرار بگیرند.
• مسیر رودخانه حفظ شود.

مرحله پنجم: ترکیب نتیجه ML با شبکه Procedural

خروجی Neural Terrain را مستقیماً نهایی نکنید. آن را با Nodeهای دیگر ترکیب کنید:

Neural Terrain
    ↓
HeightField Blur
    ↓
HeightField Erode
    ↓
HeightField Terrace
    ↓
HeightField Mask by Feature
    ↓
HeightField Scatter

مدل فرم کلی یا جزئیات یادگرفته‌شده را می‌سازد و Nodeهای Procedural کنترل نهایی را در اختیار شما می‌گذارند.

مرحله ششم: کنترل کیفیت

موارد زیر را بررسی کنید:

• تکرار الگو
• شیب‌های غیرواقعی
• حفره‌های ناخواسته
• مسیر جریان آب
• محل قابل ساخت
• Scale سنگ‌ها و دره‌ها
• اتصال Terrain به مرزها
• کیفیت تبدیل به Mesh
• هزینه حافظه و Polygon
• سازگاری با موتور بازی

آموزش ML Volume Upres برای دود و Volume

شبیه‌سازی دود با رزولوشن بالا هزینه زیادی دارد. ML Volume Upres می‌تواند یک Volume کم‌وضوح را دریافت کند و جزئیات بیشتری به آن اضافه کند.

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

جریان کاری پایه

Pyro Simulation کم‌وضوح
    ↓
Cache به VDB
    ↓
ML Volume Upres
    ↓
بررسی و اصلاح Density
    ↓
Shader و Render

مرحله اول: شبیه‌سازی کم‌وضوح

یک Pyro Simulation با رزولوشن مدیریت‌پذیر بسازید. قبل از Upres، حرکت اصلی دود باید صحیح باشد:

• سرعت
• جهت
• Buoyancy
• Dissipation
• Turbulence
• Collision
• شکل منبع
• زمان‌بندی

هوش مصنوعی نباید برای اصلاح حرکت اشتباه دود استفاده شود. ML Volume Upres بیشتر برای بازسازی جزئیات فضایی است.

مرحله دوم: Cache کردن

شبیه‌سازی را به VDB یا فرمت مناسب Cache کنید. Cache باعث می‌شود هنگام آزمایش مدل، شبیه‌سازی از ابتدا اجرا نشود.

ساختار نام‌گذاری پیشنهادی:

pyro_lowres_v001.$F4.vdb
pyro_mlupres_v001.$F4.vdb
pyro_final_v001.$F4.vdb

مرحله سوم: افزودن ML Volume Upres

Node مربوط به ML Volume Upres را بعد از ورودی Volume قرار دهید.

پارامترها را متناسب با مدل نصب‌شده تنظیم کنید و ابتدا فقط یک فریم را آزمایش کنید.

فریم آزمایشی باید شامل بخش‌های زیر باشد:

• ناحیه دارای جزئیات کم
• ناحیه متراکم
• مرز دود
• بخش دارای Turbulence
• قسمت نزدیک نور

مرحله چهارم: مقایسه خروجی

سه نسخه را کنار هم مقایسه کنید:

1. Low Resolution
2. ML Upres
3. شبیه‌سازی واقعی High Resolution در چند فریم مرجع

موارد ارزیابی:

• Silhouette
• جزئیات کوچک
• پیوستگی Density
• حفظ حرکت
• Artifact
• جزئیات ساختگی
• Flicker میان فریم‌ها
• زمان پردازش
• حجم Cache

مرحله پنجم: تست زمانی

کیفیت یک فریم کافی نیست. حداقل یک بازه کوتاه از انیمیشن را بررسی کنید.

مشکلات احتمالی:

• تغییر ناگهانی جزئیات
• لرزش لبه دود
• ظهور و ناپدیدشدن Featureها
• Sharpen بیش‌ازحد
• الگوی تکراری
• تغییر Density میان فریم‌ها

چه زمانی ML Volume Upres مناسب نیست؟

• زمانی که حرکت اصلی شبیه‌سازی اشتباه است.
• زمانی که برخوردها دقیق نیستند.
• وقتی خروجی علمی یا مهندسی می‌خواهید.
• وقتی مدل با نوع Volume پروژه آموزش ندیده است.
• وقتی Temporal Consistency کافی نیست.
• وقتی جزئیات تولیدشده با سبک پروژه هماهنگ نیستند.

ML Deformer چیست؟

یک Deformer سنتی ورودی Geometry و پارامترها را دریافت و خروجی را با فرمول یا شبیه‌سازی محاسبه می‌کند. ML Deformer تلاش می‌کند رابطه میان ورودی و خروجی را از نمونه‌های آموزشی یاد بگیرد.

فرض کنید یک شبیه‌سازی Muscle برای هر فریم چند ثانیه یا چند دقیقه زمان می‌برد. می‌توان تعداد زیادی Pose و نتیجه شبیه‌سازی متناظر تولید کرد و مدلی آموزش داد که تغییر شکل را تقریب بزند.

ساختار Dataset

هر نمونه آموزشی دو بخش دارد:

Input: وضعیت Skeleton یا Geometry اولیه
Target: Geometry تغییرشکل‌یافته نهایی

Node مربوط به ML Example ورودی و Target را در قالب یک نمونه دارای Label نگه می‌دارد. مستندات SideFX توضیح می‌دهد که این ساختار برای ساخت Dataset و جلوگیری از ناهماهنگی میان ورودی و Target مفید است. مستندات ML Example

مراحل کلی آموزش ML Deformer

۱. Rig یا ورودی پارامتریک را آماده کنید.

۲. مجموعه‌ای از Poseهای متنوع بسازید.

۳. نتیجه دقیق Deformation را برای هر Pose محاسبه کنید.

۴. ورودی و Target را به نمونه‌های آموزشی تبدیل کنید.

۵. Dataset را به Training، Validation و Test تقسیم کنید.

۶. مدل را آموزش دهید.

۷. خطای مدل را روی داده دیده‌نشده بررسی کنید.

۸. مدل را Export کنید.

۹. Inference را داخل شبکه Houdini اجرا کنید.

۱۰. نتیجه را با روش اصلی مقایسه کنید.

SideFX برای این فرایند Recipe مربوط به ML Train Deformer ارائه کرده است. مستندات ML Train Deformer

تولید Dataset مصنوعی در Houdini

یکی از باارزش‌ترین کاربردهای Houdini در هوش مصنوعی، تولید Synthetic Data است.

نمونه پروژه: تولید داده تشخیص بسته‌های صنعتی

فرض کنید می‌خواهید مدلی برای تشخیص چند نوع بسته در تصویر آموزش دهید. در Houdini می‌توان:

• مدل بسته‌ها را وارد کرد.
• موقعیت و چرخش آن‌ها را تصادفی کرد.
• رنگ و متریال را تغییر داد.
• نور را تصادفی کرد.
• دوربین را جابه‌جا کرد.
• پس‌زمینه‌های مختلف ساخت.
• Occlusion ایجاد کرد.
• تصویر RGB رندر گرفت.
• Mask هر آبجکت را ذخیره کرد.
• Depth Map تولید کرد.
• Class ID و Transform را ثبت کرد.

پارامترهایی که باید تصادفی شوند

جلوگیری از Dataset غیرواقعی

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

باید توزیع داده را کنترل کنید:

• تعداد نمونه هر کلاس متعادل باشد.
• زاویه‌های غیرممکن حذف شوند.
• رنگ‌ها از محدوده واقعی خارج نشوند.
• نورپردازی با شرایط واقعی شباهت داشته باشد.
• ابعاد آبجکت‌ها منطقی باشد.
• داده Validation جدا تولید شود.
• بخشی از ارزیابی با داده واقعی انجام شود.

ONNX در Houdini چگونه کار می‌کند؟

ONNX قالبی برای نمایش مدل آموزش‌دیده است. مزیت آن این است که مدل می‌تواند خارج از Houdini آموزش ببیند و سپس برای Inference وارد Houdini شود.

جریان کاری:

تولید Dataset در Houdini
    ↓
آموزش مدل در PyTorch یا TensorFlow
    ↓
Export به ONNX
    ↓
ورود مدل به Houdini
    ↓
ONNX Inference
    ↓
تبدیل خروجی به Attribute، Geometry یا Volume

مواردی که قبل از اجرای ONNX باید مشخص باشند

• نام Inputها
• Shape ورودی
• نوع داده
• ترتیب Channelها
• Normalization
• حداقل و حداکثر مقادیر
• نام Outputها
• نسخه Opset
• Dynamic یا Fixed بودن Dimensionها
• نحوه تبدیل خروجی به داده Houdini

بخش بزرگی از خطاهای ONNX به خود مدل مربوط نیست، بلکه از تفاوت پیش‌پردازش داده در Training و Inference ناشی می‌شود.

استفاده از مدل زبانی برای ساخت شبکه Houdini

مدل زبانی می‌تواند طرح اولیه یک Node Network را پیشنهاد دهد، اما نباید انتظار داشت همیشه نام Node، Parameter یا مسیر Context را دقیق بیان کند.

پرامپت مناسب:

شما یک Senior Houdini FX Artist هستید.

برای ساخت یک شبیه‌سازی تخریب دیوار آجری در Houdini،
یک شبکه Node-based قابل اجرا طراحی کن.

مشخصات:
- نسخه فعلی Houdini
- استفاده از RBD
- امکان کنترل نقطه برخورد
- شکستگی در محل برخورد بیشتر باشد
- قطعات دورتر بزرگ‌تر بمانند
- خروجی برای رندر Karma آماده شود

خروجی شامل:
1. Nodeها به ترتیب
2. Context هر Node
3. ورودی و خروجی هر مرحله
4. Attributeهای مهم
5. پارامترهای قابل Expose در HDA
6. Cacheهای لازم
7. روش عیب‌یابی

با این روش مدل یک نقشه فنی می‌سازد. سپس باید Nodeها را در Houdini ایجاد و نام پارامترها را با مستندات نسخه خود بررسی کنید.

تولید VEX با هوش مصنوعی

VEX زبان مهم پردازش Geometry در Houdini است. مدل‌های مناسب کدنویسی می‌توانند در تولید Wrangleهای اولیه کمک کنند.

مثال پرامپت برای Point Wrangle

برای Houdini یک کد VEX مناسب Point Wrangle بنویس.

هدف:
- نقاط براساس فاصله از یک نقطه مرجع رنگ شوند.
- رنگ نزدیک قرمز و رنگ دور آبی باشد.
- فاصله قابل کنترل با پارامتر max_distance باشد.
- مقدار نهایی Clamp شود.
- یک Attribute به نام distance_mask نیز ساخته شود.
- کد را خط‌به‌خط توضیح بده.

خروجی احتمالی:

vector target = chv("target_position");
float max_distance = max(chf("max_distance"), 0.0001);

float d = distance(@P, target);
float mask = clamp(d / max_distance, 0.0, 1.0);

vector near_color = set(1.0, 0.0, 0.0);
vector far_color = set(0.0, 0.2, 1.0);

@Cd = lerp(near_color, far_color, mask);
f@distance_mask = mask;

این کد ساده است، اما حتی کد ساده نیز باید روی Geometry آزمایشی اجرا شود.

تولید Python برای Houdini

Houdini Object Model یا HOM از طریق پکیج hou در دسترس است. این پکیج امکان دسترسی به Nodeها، Parameterها، Networkها، فایل HIP و رابط کاربری را فراهم می‌کند. مستندات رسمی Python Scripting در Houdini

از Python می‌توان برای این کارها استفاده کرد:

• ساخت Node
• اتصال Nodeها
• تنظیم Parameter
• ایجاد HDA
• ساخت ابزار Pipeline
• بررسی شبکه
• ساخت Cache
• مدیریت فایل
• تولید گزارش
• پردازش Batch با Hython
• اتصال به API هوش مصنوعی

اتصال Houdini به API هوش مصنوعی درواره

API درواره ساختاری سازگار با OpenAI دارد و می‌توان آن را با Python از Houdini فراخوانی کرد.

در نمونه عملی زیر، اطلاعات Nodeهای انتخاب‌شده جمع‌آوری می‌شود و مدل هوش مصنوعی برای آن‌ها یک مستند فنی تولید می‌کند.

این ابزار می‌تواند برای موارد زیر مفید باشد:

• مستندسازی HDA
• تحویل پروژه به عضو دیگر تیم
• توضیح شبکه قدیمی
• ساخت گزارش Pipeline
• ثبت هدف هر Node
• تهیه توضیحات Asset Library

پروژه عملی: مستندسازی خودکار Nodeهای انتخاب‌شده

معماری

Nodeهای انتخاب‌شده
    ↓
استخراج نام، نوع و اتصال‌ها
    ↓
حذف اطلاعات غیرضروری
    ↓
ارسال به API درواره
    ↓
تولید مستند فنی
    ↓
نمایش و کپی نتیجه

کد کامل Python

import json
import urllib.request
import urllib.error
import hou

API_URL = "https://api.darvareh.ir/v1/chat/completions"
API_KEY = "YOUR_DARVAREH_API_KEY"
MODEL_ID = "YOUR_MODEL_ID"

MAX_NODES = 40


def get_selected_node_data():
    nodes = hou.selectedNodes()

    if not nodes:
        raise RuntimeError("هیچ Nodeای انتخاب نشده است.")

    if len(nodes) > MAX_NODES:
        raise RuntimeError(
            "حداکثر {} Node را انتخاب کنید.".format(MAX_NODES)
        )

    result = []

    for node in nodes:
        inputs = []

        for input_node in node.inputs():
            if input_node is not None:
                inputs.append(input_node.path())

        outputs = [
            output_node.path()
            for output_node in node.outputs()
        ]

        result.append({
            "path": node.path(),
            "name": node.name(),
            "type": node.type().name(),
            "category": node.type().category().name(),
            "inputs": inputs,
            "outputs": outputs,
            "comment": node.comment() or ""
        })

    return result


def build_prompt(nodes):
    node_json = json.dumps(
        nodes,
        ensure_ascii=False,
        indent=2
    )

    return """
شبکه انتخاب‌شده Houdini را تحلیل و مستند کن.

قواعد:
- فقط براساس داده ارائه‌شده توضیح بده.
- درباره Parameterهایی که در داده نیستند ادعای قطعی نکن.
- تفاوت SOP، DOP، LOP، COP و TOP را رعایت کن.
- اگر هدف یک Node از روی نام و اتصال مشخص نیست، آن را نامطمئن اعلام کن.
- پاسخ فارسی روان باشد.
- اصطلاحات فنی مانند Node، SOP، Cache و Attribute را حفظ کن.

ساختار خروجی:
1. هدف احتمالی شبکه
2. جدول Nodeها و نقش هرکدام
3. جریان داده
4. ورودی‌ها و خروجی‌های مهم
5. نقاطی که نیاز به توضیح هنرمند دارند
6. پیشنهاد برای نام‌گذاری و کامنت‌گذاری
7. خلاصه مناسب مستندات HDA

داده شبکه:
{}
""".format(node_json)


def call_darvareh(prompt):
    payload = {
        "model": MODEL_ID,
        "messages": [
            {
                "role": "system",
                "content": (
                    "شما یک Houdini Technical Director هستید "
                    "که شبکه‌های Procedural و VFX را مستند می‌کند."
                )
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.2,
        "max_tokens": 1800
    }

    request = urllib.request.Request(
        API_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": "Bearer {}".format(API_KEY),
            "Content-Type": "application/json"
        },
        method="POST"
    )

    try:
        with urllib.request.urlopen(request, timeout=90) as response:
            data = json.loads(response.read().decode("utf-8"))
            return data["choices"][0]["message"]["content"]

    except urllib.error.HTTPError as error:
        details = error.read().decode("utf-8", errors="replace")

        raise RuntimeError(
            "HTTP {}: {}".format(error.code, details)
        )

    except urllib.error.URLError as error:
        raise RuntimeError(
            "Network error: {}".format(error.reason)
        )


def show_result(content):
    hou.ui.copyTextToClipboard(content)

    preview = content

    if len(preview) > 3500:
        preview = preview[:3500] + "\n\n[ادامه متن در Clipboard کپی شده است]"

    hou.ui.displayMessage(
        preview,
        title="Darvareh AI - Houdini Network Documentation",
        severity=hou.severityType.Message
    )


def main():
    if API_KEY == "YOUR_DARVAREH_API_KEY":
        hou.ui.displayMessage(
            "ابتدا کلید API درواره را وارد کنید.",
            severity=hou.severityType.Warning
        )
        return

    if MODEL_ID == "YOUR_MODEL_ID":
        hou.ui.displayMessage(
            "ابتدا Model ID درواره را وارد کنید.",
            severity=hou.severityType.Warning
        )
        return

    try:
        nodes = get_selected_node_data()
        prompt = build_prompt(nodes)
        documentation = call_darvareh(prompt)
        show_result(documentation)

    except Exception as error:
        hou.ui.displayMessage(
            str(error),
            title="خطا",
            severity=hou.severityType.Error
        )


main()

روش اجرای اسکریپت

۱. در درواره ثبت‌نام کنید.

۲. یک کلید API بسازید.

۳. از صفحه مدل‌های درواره مدل مناسب را انتخاب کنید.

۴. مقدار YOUR_DARVAREH_API_KEY را با کلید خود جایگزین کنید.

۵. مقدار YOUR_MODEL_ID را مطابق شناسه مدل در درواره وارد کنید.

۶. Houdini را باز کنید.

۷. چند Node مرتبط را انتخاب کنید.

۸. Python Shell یا Python Source Editor را باز کنید.

۹. کد را وارد و اجرا کنید.

۱۰. مستند تولیدشده را بررسی کنید.

۱۱. متن کامل از طریق Clipboard قابل استفاده است.

برای استفاده مداوم، می‌توانید کد را به Shelf Tool یا Python Module یک HDA تبدیل کنید.

تبدیل ابزار به Shelf Tool

برای تبدیل اسکریپت به ابزار قابل استفاده:

۱. یک Shelf جدید بسازید.

۲. یک Tool جدید ایجاد کنید.

۳. زبان Script را Python قرار دهید.

۴. کد را در بخش Script وارد کنید.

۵. Label و Tooltip مشخص تعریف کنید.

۶. یک آیکون مناسب انتخاب کنید.

۷. ابزار را ابتدا در پروژه آزمایشی اجرا کنید.

۸. برای توزیع تیمی، کلید API را از Script خارج کنید.

نام پیشنهادی:

Darvareh AI Network Documenter

توضیح:

Generate technical documentation for selected Houdini nodes
using Darvareh AI API.

معماری امن‌تر برای استودیو

قرار دادن مستقیم کلید API در Shelf Tool برای محیط تیمی مناسب نیست. معماری حرفه‌ای‌تر:

Houdini Shelf Tool
    ↓
Backend داخلی استودیو
    ↓
احراز هویت کاربر
    ↓
حذف داده حساس
    ↓
محدودیت مصرف و Cache
    ↓
API درواره
    ↓
اعتبارسنجی پاسخ
    ↓
نمایش در Houdini

مزایای این روش:

• کلید API بین کاربران توزیع نمی‌شود.
• مصرف هر پروژه قابل اندازه‌گیری است.
• مدل از Backend قابل تغییر است.
• درخواست‌های تکراری Cache می‌شوند.
• دسترسی کاربران قابل محدودکردن است.
• اطلاعات ارسالی قابل کنترل است.
• خطاها در یک محل ثبت می‌شوند.

چه اطلاعاتی را برای مدل ارسال نکنیم؟

برای مستندسازی Node Network معمولاً ارسال این اطلاعات ضروری نیست:

• مسیر کامل فایل‌های محرمانه
• نام کارفرما
• اطلاعات ورود به Render Farm
• کلیدهای API
• Tokenهای سرویس
• آدرس سرور داخلی
• اطلاعات مالی پروژه
• فایل کامل HIP
• Assetهای اختصاصی
• Source Code غیرضروری

اصل Data Minimization را رعایت کنید: فقط داده‌ای را ارسال کنید که مدل برای انجام وظیفه نیاز دارد.

استفاده از هوش مصنوعی برای عیب‌یابی Houdini

برای دریافت پاسخ مفید، فقط تصویر خطا یا عبارت «Houdini کار نمی‌کند» کافی نیست.

پرامپت عیب‌یابی باید شامل موارد زیر باشد:

نسخه Houdini:
سیستم‌عامل:
Context:
نوع Node:
پیام خطا:
نتیجه مورد انتظار:
نتیجه فعلی:
ورودی Node:
Attributeهای موجود:
تغییرات اخیر:

نمونه:

در Houdini یک Attribute Wrangle داخل SOP دارم.

ورودی دارای Attributeهای زیر است:
- @P
- @N
- i@class

هدف:
نقاط هر class حول مرکز همان class حرکت کنند.

خطا:
تمام نقاط حول مرکز کل Geometry حرکت می‌کنند.

کد فعلی:
[کد]

مشکل را تحلیل کن، نسخه اصلاح‌شده VEX را بده
و روش بررسی در Geometry Spreadsheet را توضیح بده.

مدل با Context دقیق احتمال بیشتری دارد که راه‌حل قابل اجرا ارائه دهد.

انتخاب مدل مناسب برای Houdini

برای بررسی Model ID و قیمت‌های به‌روز، صفحه مدل‌های درواره را مشاهده کنید.

کاهش هزینه API در Houdini

• تمام فایل HIP را ارسال نکنید.
• فقط Nodeهای انتخاب‌شده را پردازش کنید.
• تعداد Nodeها را محدود کنید.
• Parameterهای پیش‌فرض را حذف کنید.
• درخواست‌های مشابه را Cache کنید.
• برای مستندسازی ساده از مدل اقتصادی استفاده کنید.
• خروجی را به تعداد توکن مشخص محدود کنید.
• از Batch برای Assetهای مشابه استفاده کنید.
• مستند تولیدشده را کنار HDA ذخیره کنید.
• برای هر پروژه سقف مصرف تعریف کنید.

اشتباهات رایج

تصور اینکه Houdini تمام صحنه را از پرامپت می‌سازد

قدرت اصلی Houdini در Pipelineهای Procedural، Machine Learning، Simulation و کنترل داده است؛ نه ساخت بی‌نقص پروژه نهایی با یک جمله.

اشتباه‌گرفتن Procedural با هوش مصنوعی

VEX، SOP، DOP، PDG و HDA به‌خودی‌خود هوش مصنوعی نیستند.

استفاده از ML Volume Upres برای اصلاح Simulation اشتباه

حرکت، برخورد و رفتار اصلی Volume باید پیش از Upres صحیح باشند.

استفاده از Dataset کوچک و تکراری

مدل فقط الگوهای موجود در داده را یاد می‌گیرد. Dataset محدود باعث خروجی ضعیف روی نمونه‌های جدید می‌شود.

ناهماهنگی Training و Inference

Normalization، ترتیب Channel، Scale و Shape ورودی باید در آموزش و اجرا یکسان باشند.

اجرای کد تولیدشده بدون بررسی

VEX و Python تولیدشده را ابتدا روی شبکه آزمایشی اجرا کنید.

ارسال اطلاعات کامل پروژه به API

برای اغلب وظایف فقط Metadata، نام Node و اتصال‌ها کافی است.

ساخت Nodeهای زیاد با دستور مستقیم مدل

مدل بهتر است ابتدا Plan یا JSON تولید کند؛ سپس یک لایه قطعی و اعتبارسنجی‌شده Nodeها را ایجاد کند.

چک‌لیست پروژه هوش مصنوعی در Houdini

تعریف مسئله

• هدف استفاده از ML مشخص است.
• روش Procedural ساده‌تر بررسی شده است.
• معیار موفقیت تعریف شده است.
• زمان و هزینه Training تخمین زده شده است.
• محدودیت نسخه و License مشخص است.

Dataset

• ورودی و Target هماهنگ هستند.
• داده تکراری کنترل شده است.
• داده Training، Validation و Test جداست.
• Scale و Normalization ثبت شده است.
• نمونه‌های نامعتبر حذف شده‌اند.
• داده واقعی برای ارزیابی وجود دارد.

Training

• مدل پایه ذخیره شده است.
• Hyperparameterها ثبت شده‌اند.
• Checkpoint وجود دارد.
• Overfitting بررسی شده است.
• مدل روی داده دیده‌نشده آزمایش شده است.
• فرمت ONNX اعتبارسنجی شده است.

Houdini Pipeline

• Input Shape درست است.
• Attributeها وجود دارند.
• Nodeها نام‌گذاری شده‌اند.
• Cacheها Version دارند.
• خروجی ML با مرجع مقایسه شده است.
• Temporal Consistency بررسی شده است.
• مسیر بازگشت به روش اصلی وجود دارد.

اتصال API

• کلید API داخل فایل HIP نیست.
• Timeout تعریف شده است.
• تعداد Nodeهای ارسالی محدود است.
• اطلاعات حساس حذف می‌شوند.
• پاسخ قبل از اجرا اعتبارسنجی می‌شود.
• عملیات تغییردهنده نیازمند تأیید کاربر است.
• مصرف API مانیتور می‌شود.

پرسش‌های متداول

آیا Houdini قابلیت Machine Learning داخلی دارد؟

بله. Houdini زیرساخت تولید Dataset، پیش‌پردازش، آموزش، Export و اجرای مدل‌های Machine Learning را فراهم می‌کند.

Neural Terrain در Houdini چیست؟

Neural Terrain یک جریان کاری مبتنی بر مدل عصبی برای تولید و ویرایش Heightfield است که با Nodeهای Procedural زمین ترکیب می‌شود.

ML Volume Upres چه کاری انجام می‌دهد؟

این Node یک VDB یا Houdini Volume را دریافت می‌کند و با مدل ONNX آموزش‌دیده، وضوح و جزئیات آن را افزایش می‌دهد.

آیا ML Volume Upres جایگزین شبیه‌سازی High Resolution است؟

نه در تمام پروژه‌ها. برای بعضی خروجی‌ها مناسب است، اما باید با شبیه‌سازی مرجع و چند فریم متوالی مقایسه شود.

ONNX در Houdini چه کاربردی دارد؟

ONNX امکان اجرای مدل‌هایی را فراهم می‌کند که خارج از Houdini و با ابزارهایی مانند PyTorch یا TensorFlow آموزش دیده‌اند.

آیا برای هوش مصنوعی در Houdini باید برنامه‌نویسی بدانیم؟

برای استفاده از HDAهای آماده الزاماً نه؛ اما برای آموزش مدل اختصاصی، ساخت Pipeline و اتصال API، آشنایی با Python، VEX و ساختار داده بسیار مفید است.

آیا می‌توان Houdini را به API هوش مصنوعی متصل کرد؟

بله. با Python و پکیج hou می‌توان اطلاعات شبکه را جمع‌آوری و از طریق HTTP به API درواره ارسال کرد.

آیا API درواره با Houdini کار می‌کند؟

بله. API درواره با ساختار سازگار با OpenAI ارائه می‌شود و از Python داخل Houdini، Hython یا Backend استودیو قابل استفاده است.

آیا هوش مصنوعی می‌تواند شبکه Houdini بسازد؟

مدل می‌تواند طرح شبکه، VEX، Python یا JSON ساختاریافته تولید کند. اجرای نهایی باید توسط یک لایه اعتبارسنجی‌شده و با تأیید کاربر انجام شود.

آیا می‌توان با Houdini داده مصنوعی تولید کرد؟

بله. ماهیت Procedural، سیستم‌های رندر، Attributeها و PDG، هودینی را به ابزار قدرتمندی برای Synthetic Data Generation تبدیل کرده‌اند.

Houdini Apprentice برای یادگیری این قابلیت‌ها مناسب است؟

بسیاری از قابلیت‌ها و نمونه‌های آموزشی را می‌توان با نسخه Apprentice آزمایش کرد، اما محدودیت‌های License و خروجی هر نسخه باید در صفحه رسمی محصولات SideFX بررسی شوند.

جمع‌بندی

Houdini یکی از جدی‌ترین نرم‌افزارهای سه‌بعدی برای ترکیب Procedural Workflow و Machine Learning است. برخلاف ابزارهایی که فقط یک خروجی تصویری یا مدل سه‌بعدی از پرامپت می‌سازند، Houdini اجازه می‌دهد کل چرخه داده و مدل را کنترل کنید:

• داده تولید کنید.
• نمونه‌ها را برچسب‌گذاری کنید.
• مدل آموزش دهید.
• آن را به ONNX تبدیل کنید.
• Inference را داخل شبکه اجرا کنید.
• نتیجه را با SOP، DOP، VEX و PDG ترکیب کنید.
• خروجی را در یک HDA قابل استفاده مجدد قرار دهید.

Neural Terrain برای طراحی محیط، ML Volume Upres برای افزایش جزئیات Volume، ML Deformer برای تقریب تغییر شکل و ONNX برای اجرای مدل‌های آموزش‌دیده از مهم‌ترین کاربردهای این حوزه هستند.

مدل‌های زبانی نیز می‌توانند در تولید VEX، Python، طراحی Node Network، مستندسازی HDA و عیب‌یابی کمک کنند. برای استفاده حرفه‌ای، مدل باید نقش پیشنهاددهنده یا تولیدکننده داده ساختاریافته داشته باشد و اجرای نهایی توسط کد قطعی، اعتبارسنجی‌شده و قابل کنترل انجام شود.

برای اتصال Houdini به مدل‌های مختلف هوش مصنوعی، ساخت ابزارهای اختصاصی VFX و استفاده از API سازگار با OpenAI می‌توانید در درواره ثبت‌نام کنید. برای مشاهده مدل‌ها، Model ID و قیمت‌های به‌روز نیز صفحه مدل‌های درواره را ببینید.

مقالات مرتبط

• هوش مصنوعی در Blender؛ آموزش ساخت مدل سه‌بعدی با متن و عکس
• ساخت انیمیشن با هوش مصنوعی؛ آموزش کامل از ایده تا ویدئو
• ساخت بازی با هوش مصنوعی؛ راهنمای کامل و کاربردی
• ساخت اکشن فیگور با هوش مصنوعی
• راهنمای کامل مهندسی پرامپت
• API تولید تصویر درواره
• خروجی ساختاریافته با JSON Schema در API هوش مصنوعی
• API هوش مصنوعی چیست؟

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.