3D troubleshooting

BerryStudio has two 3D systems: 3D Preview (a fast, always-available procedural avatar) and 3D Cloth Lab / Fit Studio (a real GPU cloth simulation of your actual pattern). Most issues below are specific to one or the other.

"My machine can't run Fit Studio" / blank canvas

Open /3d-test.html — BerryStudio's own capability probe. It reports WebGL2/WebGPU support, float-texture render support (the GPU cloth solver needs this), and max texture size, and gives you a clear verdict before you wait for a load that might fail. If it reports your device can't run the GPU solver, 3D Preview (which doesn't need it) still works fully.

Zoom feels wrong, or the avatar doesn't fit the view

This was a real, now-fixed bug (see the main README's Honest notes): Cloth Lab's standalone build was missing one link in its CSS height chain, so the whole page silently sized itself to its sidebar's content height instead of the real window — which made every zoom/distance calculation wrong and the avatar look oversized. If you still see this after updating, hard-refresh (clear the page's cached service-worker assets) before reporting it as a new issue.

GLB avatar doesn't load, or looks wrong

  • VRM files (a common photoreal-avatar format) are detected and shown an honest "not supported yet" message rather than silently mispositioned — full VRM humanoid-bone retargeting is a different bone-naming spec from the Mixamo/Ready Player Me convention this app parses, and hasn't been built.
  • A GLB loads but looks stretched or oddly proportioned — the loader deforms your model to match your actual measurements (bust/waist/hip/shoulder/arm/inseam move independently via a free-form lattice), so an avatar built for very different proportions than your current measurement set can look unusual. This is expected behaviour, not a bug — try adjusting your measurements or using a different source model.
  • The model fails to load at all — check the URL is a direct, public, CORS-permitted .glb link (a Ready Player Me export link works well). BerryStudio falls back to its built-in procedural body automatically if the URL fails, rather than showing a broken scene.

Pose looks off

Seated/A-pose/T-pose/Contrapposto/Walk all work on the built-in procedural avatar. On a loaded GLB, Seated's knee-bend direction is derived from the character's own hip bones, which is ambiguous by 180° for some third-party rigs — an unlucky rig can end up seated facing backward. Walk only animates a GLB that ships its own embedded walk/idle clip; the procedural avatar has no skeleton to animate and stays standing. Whichever pose is shown, simulated cloth still collides against the standing arms-down body — a seated garment's drape isn't re-simulated for that pose.

Cloth looks stiff, or a seam "pops" on the very first frame

The solver uses a distance-based hinge/fold spring for bend resistance (not a true dihedral-angle constraint) and brute-force self-collision — deliberate trade-offs matched to this app's particle counts, tuned as "feel" sliders rather than lab-calibrated fabric values. Seams weld at mesh-build time without a gradual sewing ramp-in, so a garment can show a brief pop right after a pattern change — this settles within the first second and isn't visible during normal wear/draping afterward.

3D export

GLB, OBJ, PNG-sequence turntables, and MP4/WebM turntable recording are all confirmed working. USDZ (for iOS AR Quick Look) produces a structurally valid file with no runtime errors, but hasn't been confirmed on real iOS hardware in this project — if you test it, that's genuinely useful signal for a future update. GIF export isn't offered (every JS GIF encoder is a dependency this project deliberately avoids) — use MP4/WebM/PNG-sequence and convert externally if you need one.

If you're driving BerryStudio from a browser-automation tool rather than a real browser and see TypeError: Failed to resolve module specifier 'three' or similar, that's a known limitation of some WebKit-based automation tools' dynamic import() handling of import maps — confirmed not to reproduce in real Chromium/desktop browsers. It's a tooling quirk, not an app bug.

حل مشاكل العرض ثلاثي الأبعاد

يملك BerryStudio نظامين ثلاثيي الأبعاد: المعاينة ثلاثية الأبعاد (صورة رمزية إجرائية سريعة ومتاحة دائمًا) و3D Cloth Lab / Fit Studio (محاكاة قماش حقيقية بمعالج الرسوميات لباترونك الفعلي). معظم المشاكل أدناه خاصة بأحدهما.

"جهازي لا يستطيع تشغيل Fit Studio" / لوحة فارغة

افتح /3d-test.html — فاحص القدرات الخاص بـBerryStudio نفسه. يُبلغ عن دعم WebGL2/WebGPU، ودعم عرض النسيج العائم (float-texture، يحتاجه محلل القماش بمعالج الرسوميات)، والحجم الأقصى للنسيج، ويعطيك حكمًا واضحًا قبل انتظار تحميل قد يفشل. إذا أفاد أن جهازك لا يستطيع تشغيل المحلل، تبقى المعاينة ثلاثية الأبعاد (التي لا تحتاجه) تعمل بالكامل.

التكبير يبدو خاطئًا، أو الصورة الرمزية لا تناسب العرض

كانت هذه علة حقيقية وتم إصلاحها الآن (راجع ملاحظات الصدق في README الرئيسي): كان بناء Cloth Lab المستقل يفتقد حلقة واحدة في سلسلة ارتفاع CSS، فكانت الصفحة بأكملها تتحجّم بصمت وفق ارتفاع محتوى الشريط الجانبي بدلًا من النافذة الحقيقية — ما جعل كل حساب تكبير/مسافة خاطئًا وجعل الصورة الرمزية تبدو كبيرة الحجم. إذا استمر ظهور هذا بعد التحديث، حدّث الصفحة بقوة (لمسح أصول عامل الخدمة (service worker) المخزّنة مؤقتًا) قبل الإبلاغ عنها كمشكلة جديدة.

الصورة الرمزية GLB لا تُحمَّل، أو تبدو خاطئة

  • ملفات VRM (صيغة صورة رمزية واقعية شائعة) تُكتشف وتُعرض برسالة صادقة "غير مدعومة بعد" بدلًا من وضعها بشكل خاطئ بصمت — إعادة توجيه العظام البشرية الكاملة لـVRM مواصفة تسمية عظام مختلفة عن اتفاقية Mixamo/Ready Player Me التي يحلّلها هذا التطبيق، ولم تُبنَ بعد.
  • نموذج GLB يُحمَّل لكن يبدو ممطوطًا أو بنسب غريبة — يشوّه المحمّل نموذجك ليطابق قياساتك الفعلية (الصدر/الخصر/الورك/الكتف/الذراع/الفخذ تتحرك بشكل مستقل عبر شبكة حرة الشكل)، فقد تبدو صورة رمزية بُنيت لنسب مختلفة جدًا عن مجموعة قياساتك الحالية غير معتادة. هذا سلوك متوقع، وليس علة — جرّب تعديل قياساتك أو استخدام نموذج مصدر مختلف.
  • النموذج يفشل بالتحميل كليًا — تأكد أن الرابط رابط .glb مباشر وعام ومسموح به عبر CORS (رابط تصدير من Ready Player Me يعمل جيدًا). يتراجع BerryStudio تلقائيًا إلى جسمه الإجرائي المدمج إذا فشل الرابط، بدلًا من عرض مشهد معطّل.

الوضعية (Pose) تبدو غير صحيحة

كل من الجلوس/A-pose/T-pose/Contrapposto/المشي يعمل على الصورة الرمزية الإجرائية المدمجة. مع نموذج GLB محمّل، يُشتق اتجاه انحناء الركبة في الجلوس من عظام الورك الخاصة بالشخصية نفسها، وهذا غامض بمقدار 180° لبعض الهياكل العظمية الخارجية — قد ينتهي هيكل غير محظوظ جالسًا مواجهًا للخلف. المشي يحرّك فقط نموذج GLB يشحن مقطع مشي/خمول مدمجًا خاصًا به؛ الصورة الرمزية الإجرائية ليس لها هيكل عظمي لتحريكه وتبقى واقفة. أيًّا كانت الوضعية المعروضة، يظل القماش المحاكى يصطدم بالجسم الواقف بذراعين للأسفل — تدلي قطعة جالسة لا يُعاد محاكاته لتلك الوضعية.

القماش يبدو صلبًا، أو تظهر "قفزة" في خط الخياطة في الإطار الأول

يستخدم المحلل نابضًا للطيّ/الانحناء قائمًا على المسافة (وليس قيدًا حقيقيًا بزاوية ثنائية السطح) وتصادمًا ذاتيًا بالقوة الغاشمة — تنازلات متعمّدة تناسب أعداد الجسيمات في هذا التطبيق، مضبوطة كمنزلقات "إحساس" وليس قيمًا معايرة مخبريًا. تُلحَم الخياطات وقت بناء الشبكة دون تدرّج خياطة تدريجي، لذا قد تظهر قفزة قصيرة فور تغيير الباترون — تستقر خلال الثانية الأولى ولا تظهر أثناء الارتداء/التدلي العادي بعدها.

التصدير ثلاثي الأبعاد

تصدير GLB وOBJ ومتواليات صور PNG الدوّارة وتسجيل الفيديو الدوّار MP4/WebM كلها مؤكدة العمل. USDZ (لـiOS AR Quick Look) ينتج ملفًا صحيحًا بنيويًا بلا أخطاء تشغيل، لكن لم يُؤكَّد على جهاز iOS حقيقي في هذا المشروع — إذا جرّبته، فتلك إشارة مفيدة فعليًا لتحديث مستقبلي. تصدير GIF غير متاح (كل مُرمِّز GIF بجافاسكريبت هو تبعية يتجنّبها هذا المشروع عمدًا) — استخدم MP4/WebM/متوالية PNG وحوّلها خارجيًا إن احتجت GIF.

إذا كنت تشغّل BerryStudio من أداة أتمتة متصفح بدلًا من متصفح حقيقي ورأيت TypeError: Failed to resolve module specifier 'three' أو ما شابه، فتلك محدودية معروفة في بعض أدوات الأتمتة المبنية على WebKit في التعامل مع import() الديناميكي لخرائط الاستيراد — مؤكَّد عدم تكرارها في متصفحات Chromium/سطح المكتب الحقيقية. إنها غرابة أداة، وليست علة في التطبيق.