USDGENSCHEMAFROMSDR(1) User Commands USDGENSCHEMAFROMSDR(1)

usdgenschemafromsdr - تولید خودکار شِمای USD بر اساس گره‌های SDR

کاربرد: usdgenschemafromsdr [-h] [--noreadme] [-v]

[schemaConfig] [schemaGenerationPath]
این اسکریپت فایل‌های پویای schema.usda، generatedSchema.usda و plugInfo.json را تولید می‌کند. فایل schema.usda با تجزیهٔ sdrNodes مناسب مشخص‌شده در یک فایل پیکربندی تولید می‌شود. در کنار ارائهٔ نوع‌ها و شناسهٔ sdrNodes، فایل پیکربندی همچنین فهرستی از subLayers را فراهم می‌کند که schema.usda پرشده باید آن‌ها را زیرلایه کند. تولید کد نیز می‌تواند به‌صورت اختیاری از طریق پیکربندی json فعال شود؛ توجه داشته باشید که تولید کد به‌طور پیش‌فرض غیرفعال است.
این اسکریپت ۳ آرگومان دریافت می‌کند:
- یک پیکربندی json که sdrNodes را از طریق sourceType، sdrNodeIdentifiers یا فهرستی صریح از مسیرهای مطلق فایل‌های دارایی (sourceAssetNodes) و فهرستی از زیرلایه‌ها (sublayers) فراهم می‌کند. مسیرهای فایل‌های دارایی ممکن است حاوی متغیرهای محیطی نیز باشند، بنابراین کاربران باید پیش از اجرای اسکریپت آن‌ها را مقداردهی کنند.
- یک دایرکتوری مقصد. توجه داشته باشید که یک schema.usda همراه با prim سراسری (GLOBAL) مناسب که در customData خود یک libraryName ارائه می‌دهد باید در این مکان وجود داشته باشد. این مکان همچنین محلی است که generatedSchema.usda و plugInfo.json در آن صادر خواهند شد. درصورتی‌که تولید کد به‌صورت صریح در پیکربندی فعال شده باشد، libraryPath نیز باید همراه با libraryName در customData ارائه گردد، در غیر این صورت usdGenSchema با خطا مواجه خواهد شد.
- یک آرگومان اختیاری noreadme برای صرف‌نظر از تولید فایل README.md که توضیح مختصری دربارهٔ محتویات دایرکتوری ارائه می‌دهد.
این اسکریپت usdGenSchema را روی schema.usda پرشده به‌طور خودکار اجرا خواهد کرد.
در صورت بازتولید شِماها، توصیه می‌شود متغیر محیطی USD_DISABLE_AUTO_APPLY_API_SCHEMAS روی true تنظیم شود تا از اعمال هرگونه شمای auto-apply API قبلاً تولیدشده بر پایه‌های شمای مشخص‌شده جلوگیری شود، چرا که این امر می‌تواند منجر به هرس (prune) شدن ویژگی‌های اضافی گردد.
مشخصات schema.usda با استفاده از UsdUtils.UpdateSchemaWithSdrNode از sdrNodes ارائه‌شده پر می‌شود و متادیتای skipCodeGeneration روی true تنظیم خواهد شد، مگر اینکه در پیکربندی برای این schema.usda صراحتاً False تعیین شده باشد.
تابع UsdUtils.UpdateSchemaWithSdrNode مسئول موارد زیر است:

به‌روزرسانی schemaLayer داده‌شده با primSpec و propertySpecs برگرفته از متادیتای sdrNode.

می‌توان یک renderContext ارائه داد که در تعیین فضای‌نام shaderId به کار می‌رود و از این الگو پیروی می‌کند: "<renderContext>:<SdrShaderNodeContext>:shaderId". توجه داشته باشید که در اینجا از کانتکست گره (SDR_NODE_CONTEXT_TOKENS) برای ساخت فضای‌نام shaderId استفاده می‌شود، بنابراین تجزیه‌کننده‌های شیدر باید اطمینان حاصل کنند که از SDR_NODE_CONTEXT_TOKENS مناسب در تعاریف گره استفاده می‌کنند.

پارامتر overrideIdentifier شناسه‌ای است که باید هنگامی استفاده شود که شناسهٔ گره در حال پردازش با شناسه‌ای که Sdr در زمان اجرا شناسایی می‌کند تفاوت داشته باشد؛ مانند زمانی که این تابع برای گره‌ای ساخته‌شده از یک مسیر داراییِ صریح تعریف می‌شود. این پارامتر تنها باید زمانی استفاده شود که کلاینت‌ها بدانند شناسهٔ ارائه‌شده همان شناسهٔ واقعی است که زمان اجرای Sdr هنگام پرس‌وجو با GetShaderNodeByIdentifierAndType و غیره ارائه خواهد داد.

این ابزار علاوه بر بسیاری از متادیتاهای استاندارد Sdr که مشخص و تجزیه شده‌اند (از طریق افزونهٔ تجزیه‌کنندهٔ آن)، مشخصه‌های زیر را (که به‌صورت متادیتای Sdr ظاهر می‌شوند) مصرف می‌کند:

- «schemaName»: نام شمای جدید پرشده از sdrNode ارائه‌شده
(الزامی)
- «schemaKind»: مقدار UsdSchemaKind را برای شمای در حال ساخت از sdrNode مشخص می‌کند. (توجه داشته باشید که این ویژگی از انواع شِماهای multiple apply پشتیبانی نمی‌کند).
- «schemaBase»: شمای پایه‌ای که شمای جدید باید از آن ارث‌بری کند. توجه داشته باشید که این مقدار به‌طور پیش‌فرض برای یک شمای API برابر "APISchemaBase" و برای یک شمای واقعی (concrete) برابر "Typed" است.
- «apiSchemasForAttrPruning»: فهرستی از شِماهای اصلی API که با یکدیگر ترکیب خواهند شد و هر ویژگی مشترک شیدر از این تعریف prim، از شمای حاصل هرس می‌شود.
- «typedSchemaForAttrPruning»: یک شمای دارای نوع (typed) اصلی که با apiSchemasForAttrPruning ترکیب خواهد شد و هر ویژگی مشترک شیدر از این تعریف prim، از شمای حاصل هرس می‌شود. اگر هیچ typedSchemaForAttrPruning ارائه‌نشود، تنها apiSchemasForAttrPruning برای ایجاد یک تعریف prim ترکیب می‌شوند. این مورد تنها هنگام ایجاد یک APISchema استفاده خواهد شد.
- «apiSchemaAutoApplyTo»: شِماهایی که شمای API پرشده از sdrNode به‌طور خودکار بر آن‌ها اعمال (autoApply) خواهد شد.
- «apiSchemaCanOnlyApplyTo»: در صورت مشخص شدن، شمای API تولیدشده از sdrNode تنها می‌تواند به‌طور معتبر بر این مجموعه از شِماها اعمال شود.
- «providesUsdShadeConnectableAPIBehavior»: برای فعال‌سازی رفتار اتصال‌پذیری در یک شمای API به کار می‌رود.
- «isUsdShadeContainer»: تنها زمانی استفاده می‌شود که
providesUsdShadeConnectableAPIBehavior روی true تنظیم شده باشد. prim اتصال‌پذیر را به‌عنوان نوع نگه‌دارندهٔ UsdShade علامت‌گذاری می‌کند.
- «requiresUsdShadeEncapsulation»: تنها زمانی استفاده می‌شود که
providesUsdShadeConnectableAPIBehavior روی true تنظیم شده باشد. قواعد کپسوله‌سازی UsdShade حاکم بر connectableBehavior آن را پیکربندی می‌کند.
- «tfTypeNameSuffix»: نام کلاسی که در سامانهٔ TfType ثبت خواهد شد.
این مقدار برای ثبت در TfType به انتهای نام دامنه الحاق می‌شود.
- «schemaPropertyNSPrefixOverride»: متادیتای سطح گره که می‌تواند پیشوند فضای‌نام تمامی ویژگی‌های گره را تعیین کند. این گزینه برای گره‌های غیرقابل‌اتصال که نباید پیشوند فضای‌نام ورودی‌ها و خروجی‌های UsdShade (یعنی inputs و outputs) را دریافت کنند کاربردی است.

- «usdVariability»: متادیتای سطح ویژگی که مشخص می‌کند آیا تغییرپذیری USD
برای یک sdrNodeProperty خاص باید روی Uniform یا Varying تنظیم شود.
- «usdSuppressProperty»: متادیتای سطح ویژگی که تعیین می‌کند آیا ویژگی باید در فرایند
ترجمه از آرگومان‌ها به مشخصهٔ ویژگی (property spec) نادیده گرفته (suppress) شود یا خیر.
- «propertyNSPrefixOverride»: روشی برای بازنویسی فضای‌نام یک ویژگی
از مقدار پیش‌فرض (inputs:/outputs:) یا از متادیتای schemaPropertyNSPrefixOverride گره فراهم می‌کند.

ترجمهٔ متادیتای ویژگی Sdr به SdfPropertySpec

- مقدار "null" برای متادیتای Widget در SdrShaderProperty به
'hidden' در دیکشنری متادیتای uiHints مربوط به SdfPropertySpec ترجمه می‌شود.
- متادیتای Help در SdrShaderProperty (یا متادیتای Label در صورت عدم ارائهٔ متادیتای Help)
به رشته‌های متادیتای سفارشی userDocBrief و userDoc در SdfPropertySpec ترجمه می‌شود.
- متادیتای Page در SdrShaderProperty به 'displayGroup'
در دیکشنری متادیتای uiHints مربوط به SdfPropertySpec ترجمه می‌شود.
- متادیتای Label در SdrShaderProperty به 'displayName'
در دیکشنری متادیتای uiHints مربوط به SdfPropertySpec ترجمه می‌شود.
- متادیتای Options در SdrShaderProperty به 'allowedTokens'
(هنگامی که برچسب‌ها یا مقادیر مشخص شده باشند) یا به 'valueLabels' (هنگامی که هر دوی برچسب‌ها و مقادیر مشخص شده باشند) در دیکشنری متادیتای uiHints مربوط به SdfPropertySpec ترجمه می‌شود. جهت سازگاری با گذشته، متغیر USD_POPULATE_LEGACY_ALLOWED_TOKENS را تنظیم کنید تا برای ویژگی‌های از نوع رشته (string) و توکن (token) که هم برچسب و هم مقدار دارند، allowedTokens علاوه بر valueLabels نوشته شود.
- مقدار Default در SdrShaderProperty به مقدار Default
در SdfPropertySpec ترجمه می‌شود.
- ویژگی‌های ورودی اتصال‌پذیر به مقدار InterfaceOnly
در CONNECTABILITY مربوط به SdfPropertySpec ترجمه می‌شوند.

یک پیکربندی json که sdrNodes را از طریق sourceType، sdrNodeIdentifiers یا فهرستی صریح از مسیرهای مطلق فایل دارایی (sourceAssetNodes) فراهم می‌کند. توجه داشته باشید که برای گره‌های مشخص‌شده در sourceAssetNodes، از نام پایه (basename) حذف‌شدهٔ پسوند به عنوان shaderId برای گره‌های ایجادشده استفاده خواهیم کرد. اگر مسیرهای گره مشخص‌شده در sourceAssetNodes حاوی متغیرهای محیطی باشند، کاربر ملزم است پیش از اجرای اسکریپت آن‌ها را مقداردهی کند. همچنین به‌صورت اختیاری فهرستی از زیرلایه‌ها (sublayers) را ارائه می‌دهد که schema.usda آن‌ها را زیرلایه خواهد کرد. تولید کد نیز می‌تواند به‌صورت اختیاری از طریق پیکربندی json فعال شود؛ توجه داشته باشید که تولید کد به‌طور پیش‌فرض غیرفعال است. [پیش‌فرض: ./schemaConfig.json]') نمونه فایل پیکربندی json:
{
"sdrNodes": {
"renderContext": "myRenderContext",
"sourceType": [
"sdrIdentifier1",
"sdrIdentifier2", "sdrIdentifier3"
],
"sourceAssetNodes": [
"/absolutepath/to/sdrNodeIdentifyingAsset1.extension,
"/absolutepath/to/sdrNodeIdentifyingAsset1.extension,
],
}, "sublayers": [
"usd/schema.usda",
"usdGeom/schema.usda", "usdLux/schema.usda" ],
"skipCodeGeneration": True
}
دایرکتوری مقصدی که کد باید در آن تولید شود. این اسکریپت فرض می‌کند یک schema.usda پایه در این مکان با یک prim از نوع GLOBAL و پیکربندی‌شده با libraryName مناسب تعریف شده است. [پیش‌فرض: .]

نمایش این پیام راهنما و خروج
در صورت تعیین، فایل README.md حاوی توضیحی دربارهٔ منبع محتویات این دایرکتوری در schemaGenerationPath ایجاد نخواهد شد.
این گزینه به usdGenSchema ارسال می‌شود تا بررسی کند که فایل‌های منبع بدون تغییر مانده‌اند.
September 2026 usdgenschemafromsdr 26.08