manim-fa-lab

آزمایشگاه شیمی برای مانیمِ فارسی

این پلاگین برای جامعهٔ فارسی‌زبان ساخته شده است. مانیم ابزارِ فوق‌العاده‌ای برای ساختنِ ویدیوهای آموزشی است، ولی منابعِ فارسیِ آن هنوز کم است: نه ابزارِ آماده‌ای برای صحنه‌های آزمایشگاه هست، نه نمونه‌ای به فارسیِ درست که یک معلم یا دانشجو بتواند برش دارد و تغییرش بدهد. manim-fa-lab را ساخته‌ایم تا این خلأ را کمی پر کند: هر برچسب و هر توضیحِ داخلِ صحنه‌ها فارسیِ راست‌چین است، و کدها و توضیحاتِ داخلِ پروژه هم به فارسیِ ساده نوشته شده تا کسی که برنامه‌نویسِ حرفه‌ای نیست هم بتواند از آن استفاده کند و گسترشش بدهد. خدا کند این پلاگین بخشی از خلأِ منابع را در دنیای مانیمِ فارسی پر کند و ساختنِ ویدیوهای آموزشیِ فارسی را برای معلم‌ها، دانشجوها و علاقه‌مندها آسان‌تر کند.

manim-fa-lab یک پلاگینِ مستقل برای Manim است که ابزارهای آزمایشگاه شیمی (بورت، بشر، ارلن، پیپت، چگالنده، چراغ‌ها، …) را به‌صورتِ کامپوننت‌های آماده و چند صحنهٔ آمادهٔ آموزشی (تیتراسیون، تقطیر، …) در اختیارتان می‌گذارد. توضیح‌ها با manim-fa (متنِ فارسی و افکتِ نوشتن) روی صحنه می‌آیند.

این پلاگین عضوی از خانوادهٔ پلاگین‌های فارسیِ مانیم است: manim-fa (متنِ فارسی)، manim-fa-physics و manim-fa-chemistry.

فهرست مطالب

• ویژگی‌ها
• نصب
• شروع سریع
• صحنهٔ نمونهٔ ۱: تیتراسیون
• صحنهٔ نمونهٔ ۲: تقطیرِ جزء‌به‌جزء
• گالریِ صحنه‌های دیگر
• ابزارها
• معماری در یک نگاه
• ساختنِ ابزارِ جدید
• محدودیت‌ها
• توسعه و تست
• مشارکت و راه ارتباطی
• قدردانی و مجوز

ویژگی‌ها

• ۱۹ ابزارِ مستقل: بشر، بورت، ارلن، بالنِ ته‌گرد، لولهٔ آزمایش، استوانهٔ مدرج، پیپت، قیفِ جداکننده، پایه، جک، سه‌پایه، جالِ فلزی، گرمکن، چراغِ الکلی، چراغ بونزن، چگالنده، ستونِ تقطیر، ترمومتر و پایهٔ چگالنده. هر ابزار یک فایل SVG و یک کلاسِ پایتونِ کوچک است.
• ۱۰ صحنهٔ آماده که فقط ابزارها را می‌چینند و اجرا می‌کنند؛ پس اگر ظاهرِ یک ابزار را عوض کنید، همهٔ صحنه‌ها خودکار نسخهٔ جدید را می‌گیرند.
• معرفیِ گام‌به‌گام: هر ابزار یک‌بار ظاهر می‌شود، هایلایت می‌شود و یک جملهٔ فارسی با افکتِ نوشتن و یک فلشِ افقی به آن اشاره می‌کند؛ بعد نوبتِ ابزارِ بعدی است.
• مایعِ واقعی: مایع «کپیِ خودِ مسیرِ بدنهٔ ظرف» است، پس با شکلِ واقعیِ ظرف (حتی بالنِ گرد و ارلنِ مخروطی) بالا و پایین می‌رود. مایعِ چندلایه (آب و روغن)، تغییرِ رنگ و ریختنِ قطره‌قطره هم دارد.
• شعلهٔ زنده: شعلهٔ چراغ الکلی و بونزن مثلِ شعلهٔ واقعی می‌لرزد و زبانه می‌کشد؛ با باز کردنِ دریچهٔ هوا از زردِ پر‌دود به آبیِ داغ‌تر می‌رود.
• جلوه‌های علمی: حباب‌های جوشیدن، بخار در ستونِ تقطیر، امولسیون پس از تکان دادنِ قیف، ترمومترِ متحرک با عددِ فارسیِ دما و زومِ دوربین.
• اعدادِ فارسی روی ظرف‌ها: استوانهٔ مدرج (۱۰ تا ۵۰) و بشر (۲۰ تا ۸۰) با مقیاسِ واقعی.
• چیدمانِ خودکار: ابزارها با «نقطه‌های اتصال» به هم می‌چسبند؛ هیچ مختصاتِ دستی نیست.
• متنِ فارسیِ درست: همهٔ نوشته‌ها راست‌چین و با فونتِ وزیرمتن (از طریق FaText) و افکتِ نوشتنِ fa_write از manim-fa (نسخهٔ ۱٫۲ به بعد): متنِ چندخطی خط‌به‌خط نوشته می‌شود، و کلمه‌های لاتین و عددها (مثل H2O و ۲۵) از چپ به راست.
• آزمایش‌شده: ۱۶۰ تستِ خودکار (با Manim ۰٫۱۹ و ۰٫۲۱) و رندرِ کاملِ همهٔ صحنه‌ها.

نصب

pip install manim-fa-lab

یا از سورس:

git clone https://github.com/Tabesh2020/manim-fa-lab.git
cd manim-fa-lab
python -m pip install -e .

برای به‌روزرسانی: python -m pip install --upgrade manim-fa-lab

پیش‌نیازها: Python ‏۳٫۱۰ یا بالاتر و Manim Community (همراهِ Cairo، Pango و FFmpeg). پلاگین‌های manim-fa و numpy خودکار نصب می‌شوند.

شروع سریع

۱) اجرای یک صحنهٔ آماده

فایلی مثلِ my_scene.py بسازید:

from manim_fa_lab.scenarios.titration import Titration as _Titration

class MyTitration(_Titration):
    pass

و اجرا کنید:

manim -pqm my_scene.py MyTitration

(-ql سریع و کم‌کیفیت، -qm متوسط، -qh کیفیتِ بالا. مانیم فقط صحنه‌هایی را پیدا می‌کند که داخلِ همان فایل تعریف شده‌اند؛ برای همین یک زیرکلاسِ خالی می‌سازیم.)

۲) ساختنِ صحنهٔ خودتان (چند خط!)

from manim import LEFT
from manim_fa_lab import LabScene, Stand, Burette, Beaker

class MyScene(LabScene):
    def construct(self):
        stand   = Stand(height=5.8)
        burette = Burette(height=5)
        beaker  = Beaker(height=1.2)

        burette.attach_to(stand, mine="grip", theirs="clamp")       # بورت در گیره
        beaker.attach_to(stand, mine="bottom", theirs="base_top")   # بشر روی پایه

        burette.set_liquid(ml=0, color="#3B9DDD")   # رنگِ مایع (حجمِ اولیه صفر)
        beaker.set_liquid(ml=0, color="#F5D76E")

        self.introduce(stand, "پایه: بورت را نگه می‌دارد", side=LEFT, point=0.35)
        self.introduce(burette, "بورت: محلولِ معلوم داخل آن است", point=0.85)
        self.introduce(beaker, "بشر: محلولِ مجهول", point=0.5)

        self.play(burette.animate_volume(40), run_time=2)           # پر شدنِ بورت
        self.play(burette.drip(into=beaker, drops=12))              # قطره‌قطره
        self.play(beaker.animate_color("#E8548F"))                  # تغییرِ رنگ

هر ابزار یک VGroup معمولیِ مانیم است؛ پس .shift، .scale، .animate و هر دستورِ دیگرِ مانیم روی آن کار می‌کند. فهرستِ کاملِ دستورها در مرجعِ فنی است.

صحنهٔ نمونهٔ ۱: تیتراسیون

پایه، بورت، شیر و بشر یکی‌یکی معرفی می‌شوند (هر کدام با یک جملهٔ فارسی و یک فلش)، بورت با محلولِ آبی پر می‌شود، محلول قطره‌قطره وارد بشر می‌شود، دوربین روی سطحِ مایع زوم می‌کند و در پایان رنگِ بشر از زرد به صورتی می‌رود، یعنی واکنش کامل شده است. مدتِ صحنه حدودِ ۵۵ ثانیه است.

manim -pqm examples/titration.py Titration              # با بشر
manim -pqm examples/titration.py TitrationErlenmeyer    # همان صحنه با ارلن

ظرفِ زیرِ بورت با چهار مشخصه عوض می‌شود؛ بقیهٔ صحنه دست‌نخورده می‌ماند:

from manim_fa_lab import Erlenmeyer
from manim_fa_lab.scenarios.titration import Titration as _Titration

class TitrationErlenmeyer(_Titration):
    container_class = Erlenmeyer   # کلاسِ ظرف
    container_name = "ارلن"        # نامی که در جمله‌ها می‌آید
    container_height = 1.3         # ارتفاع در صحنه
    sample_ml = 80                 # حجمِ اولیهٔ محلولِ مجهول

صحنهٔ نمونهٔ ۲: تقطیرِ جزء‌به‌جزء

بزرگ‌ترین صحنهٔ پلاگین (حدودِ ۱۱۰ ثانیه): اول هر ابزار (بالن، گرمکن، ستونِ تقطیر، ترمومتر، چگالنده، پایهٔ چگالنده، جک، ارلن) تنها در وسطِ صحنه معرفی می‌شود؛ بعد دستگاه چیده می‌شود، مخلوط در بالن ریخته می‌شود و ارتفاعِ ارلن با جک تنظیم می‌شود. با روشن شدنِ گرمکن، دوربین روی ترمومتر زوم می‌کند و دما با عددِ فارسی از ۲۵ تا ۷۸ درجه بالا می‌رود؛ بخار از بالن به ستون و لولهٔ جانبی می‌رود، در چگالنده مایع می‌شود و قطره‌قطره در ارلن جمع می‌شود؛ مایعِ بالن غلیظ‌تر و تیره‌تر می‌شود و در پایان دما به ۹۰ درجه می‌رسد (مادهٔ بعدی می‌جوشد).

manim -pqm examples/distillation.py Distillation

جای هر ابزار از «نقطه‌های اتصال» حساب می‌شود، پس با یک عدد می‌توانید جزئیات را تنظیم کنید:

from manim_fa_lab.scenarios.distillation import Distillation as _Distillation

class Distillation(_Distillation):
    condenser_lift = 0.03   # چگالنده ۰٫۰۳ واحد بالاتر (منفی = پایین‌تر)

گالریِ صحنه‌های دیگر

چراغ الکلی و چراغ بونزن شعلهٔ زنده؛ دریچهٔ هوا باز می‌شود و شعله آبی می‌شود examples/burners.py Burners	جداسازیِ آب و روغن قیفِ جداکننده روی پایه؛ لایهٔ پایین قطره‌قطره وارد بشر می‌شود examples/separation.py Separation
آزمایشِ بندیکت (تشخیصِ قند) پیپت، لولهٔ آزمایش و چراغِ الکلی؛ رنگ از آبی به آجری می‌رود examples/benedict.py Benedict	گرم کردنِ آب روی سه‌پایه سه‌پایه، جالِ فلزی و بشر؛ چراغِ الکلی و سپس بونزن examples/heating.py Heating
مسابقهٔ دقت اندازه‌گیریِ ۲۵ میلی‌لیتر با بشر، ارلن و استوانهٔ مدرج (با قطره‌چکان)؛ استوانه برنده است examples/accuracy.py Accuracy

ابزارها

ابزار	کلاس	نکته
بشر	Beaker	اعدادِ فارسیِ ۲۰ تا ۸۰ (با numbers=False بدونِ عدد)
بورت	Burette	شیرِ قطره‌ریز؛ drip
ارلن	Erlenmeyer	درجه‌ها تقریبی‌اند
بالنِ ته‌گرد	RoundFlask	جای ورودِ ستون؛ روی گرمکن می‌نشیند
لولهٔ آزمایش	TestTube	حبابِ جوشیدن (tube.bubbles)
استوانهٔ مدرج	GraduatedCylinder	مقیاسِ واقعیِ ۰ تا ۵۰ میلی‌لیتر با اعدادِ فارسی؛ level_y(ml)
پیپت	Pipette	مخزنِ قابلِ فشردن؛ برداشتن و ریختنِ قطره‌قطره
قیفِ جداکننده	SeparatingFunnel	مایعِ دولایه، شیر، درب، تکان دادن و امولسیون
پایه و گیره	Stand	نقطهٔ clamp برای نگه داشتنِ ابزار
پایهٔ چگالنده	CondenserSupport	لولهٔ مایلِ چگالنده را نگه می‌دارد
جک	LabJack	ارتفاعش با انیمیشن عوض می‌شود؛ carry
سه‌پایه	LabTripod	جال و ظرف روی حلقهٔ آن می‌نشینند
جالِ فلزی	WireGauze	ظاهرِ فلزیِ گرادیانتیِ فایل حفظ می‌شود
گرمکن	Heater	حمامِ حبابدار؛ boil
چراغِ الکلی	AlcoholLamp	شعلهٔ زنده و الکلِ واقعی که کم می‌شود
چراغ بونزن	BunsenBurner	دریچهٔ هوا: animate_air(1) ← شعلهٔ آبی
چگالنده	Condenser	ورودِ بخار، نوک و شلنگ‌ها
ستونِ تقطیر	FractionalColumn	جای ترمومتر و لولهٔ جانبی
ترمومتر	Thermometer	animate_temperature(78) و readout() با رقمِ فارسی

معماری در یک نگاه

src/manim_fa_lab/
├─ theme.py            ← رنگ، ضخامتِ خط، اندازهٔ نوشته‌ها (فقط همین‌جا)
├─ core/               ← موتورِ مشترک: مایع، قطره، شعله، حباب، توضیح + فلش، صحنهٔ پایه
├─ components/         ← هر ابزار یک پوشه: فایلِ SVG + یک کلاسِ پایتونِ کوچک
└─ scenarios/          ← فقط مونتاژ و اجرا (تیتراسیون، تقطیر، …)

فلسفهٔ پروژه: ابزارها چیزی دربارهٔ صحنه نمی‌دانند و صحنه‌ها چیزی دربارهٔ ظاهرِ ابزارها. یک ابزار فقط شکل، نقطه‌های اتصال و رفتارِ خودش را می‌داند؛ صحنه فقط آن‌ها را می‌چیند و دستور می‌دهد.

ساختنِ ابزارِ جدید

ابزارِ تازه یعنی یک فایلِ SVG (بدنهٔ ظرف یک مسیرِ بستهٔ جدا) و یک کلاسِ چندخطی. فایلِ SVG را کنارِ فایلِ پایتونِ کلاس بگذارید (حتی در پروژهٔ خودتان، بیرون از پلاگین):

from manim_fa_lab.core.component import LabComponent

class Condenser(LabComponent):
    svg_file = "condenser.svg"
    default_height = 3
    fill_range = (0.0, 1.0)            # مایع از کجا تا کجا پر می‌شود (کسری از ارتفاع)
    capacity_ml = 100
    anchors = {"inlet": (0.9, 0.2)}    # نقطه‌های اتصال (x, y) بین ۰ و ۱

راهنمای گام‌به‌گام، ابزارِ پیدا کردنِ شماره و مختصاتِ مسیرها (examples/inspect_parts.py) و نکته‌های طراحیِ SVG در مرجعِ فنی آمده است.

محدودیت‌ها

• چرخاندنِ ظرفِ دارای مایع (ریختن با کج کردن) هنوز پشتیبانی نمی‌شود؛ سطحِ مایع همیشه افقی است.
• درجه‌های ارلن و ظرف‌های مخروطی تقریبی‌اند؛ استوانهٔ مدرج مقیاسِ واقعی دارد و بشر تقریباً هم‌تراز است.
• با Manim Community نسخه‌های ۰٫۱۹ و ۰٫۲۱ آزمایش شده است؛ نسخه‌های دیگر را گزارش دهید.

فهرستِ کاملِ محدودیت‌ها در مرجعِ فنی است.

توسعه و تست

git clone https://github.com/Tabesh2020/manim-fa-lab.git
cd manim-fa-lab
python -m pip install -e ".[dev]"
pytest

مشارکت و راه ارتباطی

پیشنهاد، باگ یا ابزارِ تازه‌ای دارید؟ از بخشِ Issues در گیت‌هاب بنویسید. طراحیِ ابزارِ جدید (فایلِ SVG) و ترجمهٔ بهترِ توضیح‌ها هم بسیار ارزشمند است.

قدردانی و مجوز

• طراحیِ همهٔ فایل‌های SVGِ ابزارها: Tabesh2020.
• Manim Community برای موتورِ انیمیشن.
• manim-fa برای متنِ فارسی، افکتِ نوشتن و فونتِ وزیرمتن (Vazirmatn از صابر راستی‌کردار).
• مجوز: MIT