Metadata-Version: 2.4
Name: manim-fa-lab
Version: 0.1.0
Summary: Persian-language chemistry laboratory equipment for Manim: reusable components (burette, beaker, flasks, pipette, condenser, lamps, ...) and ready-made scenes (titration, distillation, ...) with Persian explanations. ابزارها و صحنه‌های آزمایشگاه شیمی برای مانیمِ فارسی.
Author: Tabesh2020
License-Expression: MIT
Project-URL: Source, https://github.com/Tabesh2020/manim-fa-lab
Project-URL: Issue tracker, https://github.com/Tabesh2020/manim-fa-lab/issues
Project-URL: Homepage, https://github.com/Tabesh2020/manim-fa-lab
Project-URL: Changelog, https://github.com/Tabesh2020/manim-fa-lab/blob/main/CHANGELOG.md
Project-URL: Companion: manim-fa, https://github.com/Tabesh2020/manim-fa
Keywords: manim,manim-fa,persian,farsi,chemistry,laboratory,education,animation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: Persian
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: manim>=0.19.0
Requires-Dist: manim-fa>=1.1.0
Requires-Dist: numpy
Requires-Dist: svgelements
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# manim-fa-lab
### آزمایشگاه شیمی برای مانیمِ فارسی

[![PyPI](https://img.shields.io/pypi/v/manim-fa-lab.svg)](https://pypi.org/project/manim-fa-lab/)
[![Python](https://img.shields.io/pypi/pyversions/manim-fa-lab.svg)](https://pypi.org/project/manim-fa-lab/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
[![Manim](https://img.shields.io/badge/manim-0.19%2B-blue.svg)](https://www.manim.community/)

![ابزارهای manim-fa-lab](https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/components.png)

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

manim-fa-lab یک پلاگینِ مستقل برای [Manim](https://www.manim.community/) است که ابزارهای
آزمایشگاه شیمی (بورت، بشر، ارلن، پیپت، چگالنده، چراغ‌ها، …) را به‌صورتِ **کامپوننت‌های آماده**
و چند **صحنهٔ آمادهٔ آموزشی** (تیتراسیون، تقطیر، …) در اختیارتان می‌گذارد. توضیح‌ها با
[manim-fa](https://github.com/Tabesh2020/manim-fa) (متنِ فارسی و افکتِ نوشتن) روی صحنه می‌آیند.

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

# فهرست مطالب
- [ویژگی‌ها](#ویژگیها)
- [نصب](#نصب)
- [شروع سریع](#شروع-سریع)
- [صحنهٔ نمونهٔ ۱: تیتراسیون](#صحنهٔ-نمونهٔ-۱-تیتراسیون)
- [صحنهٔ نمونهٔ ۲: تقطیرِ جزء‌به‌جزء](#صحنهٔ-نمونهٔ-۲-تقطیرِ-جزءبهجزء)
- [گالریِ صحنه‌های دیگر](#گالریِ-صحنههای-دیگر)
- [ابزارها](#ابزارها)
- [معماری در یک نگاه](#معماری-در-یک-نگاه)
- [ساختنِ ابزارِ جدید](#ساختنِ-ابزارِ-جدید)
- [محدودیت‌ها](#محدودیتها)
- [توسعه و تست](#توسعه-و-تست)
- [مشارکت و راه ارتباطی](#مشارکت-و-راه-ارتباطی)
- [قدردانی و مجوز](#قدردانی-و-مجوز)

# ویژگی‌ها

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

# نصب

```bash
pip install manim-fa-lab
```

یا از سورس:

```bash
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](https://docs.manim.community/en/stable/installation.html)
(همراهِ Cairo، Pango و FFmpeg). پلاگین‌های `manim-fa` و `numpy` خودکار نصب می‌شوند.

# شروع سریع

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

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

```python
from manim_fa_lab.scenarios.titration import Titration as _Titration

class MyTitration(_Titration):
    pass
```

و اجرا کنید:

```bash
manim -pqm my_scene.py MyTitration
```

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

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

```python
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` و هر دستورِ دیگرِ مانیم
روی آن کار می‌کند. فهرستِ کاملِ دستورها در [مرجعِ فنی](https://github.com/Tabesh2020/manim-fa-lab/blob/main/docs/API.md) است.

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

![تیتراسیون](https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/titration.png)

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

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

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

```python
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                 # حجمِ اولیهٔ محلولِ مجهول
```

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

![تقطیر](https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/distillation.png)

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

```bash
manim -pqm examples/distillation.py Distillation
```

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

```python
from manim_fa_lab.scenarios.distillation import Distillation as _Distillation

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

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

<table dir="rtl">
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/burners.png" width="380"><br><b>چراغ الکلی و چراغ بونزن</b><br>شعلهٔ زنده؛ دریچهٔ هوا باز می‌شود و شعله آبی می‌شود<br><code>examples/burners.py Burners</code></td>
<td align="center"><img src="https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/separation.png" width="380"><br><b>جداسازیِ آب و روغن</b><br>قیفِ جداکننده روی پایه؛ لایهٔ پایین قطره‌قطره وارد بشر می‌شود<br><code>examples/separation.py Separation</code></td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/benedict.png" width="380"><br><b>آزمایشِ بندیکت (تشخیصِ قند)</b><br>پیپت، لولهٔ آزمایش و چراغِ الکلی؛ رنگ از آبی به آجری می‌رود<br><code>examples/benedict.py Benedict</code></td>
<td align="center"><img src="https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/heating.png" width="380"><br><b>گرم کردنِ آب روی سه‌پایه</b><br>سه‌پایه، جالِ فلزی و بشر؛ چراغِ الکلی و سپس بونزن<br><code>examples/heating.py Heating</code></td>
</tr>
<tr>
<td align="center" colspan="2"><img src="https://raw.githubusercontent.com/Tabesh2020/manim-fa-lab/main/docs/images/accuracy.png" width="380"><br><b>مسابقهٔ دقت</b><br>اندازه‌گیریِ ۲۵ میلی‌لیتر با بشر، ارلن و استوانهٔ مدرج (با قطره‌چکان)؛ استوانه برنده است<br><code>examples/accuracy.py Accuracy</code></td>
</tr>
</table>

# ابزارها

| ابزار | کلاس | نکته |
|---|---|---|
| بشر | `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 را کنارِ فایلِ پایتونِ کلاس بگذارید (حتی در پروژهٔ خودتان، بیرون از پلاگین):

```python
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 در [مرجعِ فنی](https://github.com/Tabesh2020/manim-fa-lab/blob/main/docs/API.md) آمده است.

# محدودیت‌ها

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

فهرستِ کاملِ محدودیت‌ها در [مرجعِ فنی](https://github.com/Tabesh2020/manim-fa-lab/blob/main/docs/API.md) است.

# توسعه و تست

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

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

پیشنهاد، باگ یا ابزارِ تازه‌ای دارید؟ از بخشِ
[Issues](https://github.com/Tabesh2020/manim-fa-lab/issues) در گیت‌هاب بنویسید. طراحیِ ابزارِ
جدید (فایلِ SVG) و ترجمهٔ بهترِ توضیح‌ها هم بسیار ارزشمند است.

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

- طراحیِ همهٔ فایل‌های SVGِ ابزارها: **Tabesh2020**.
- [Manim Community](https://www.manim.community/) برای موتورِ انیمیشن.
- [manim-fa](https://github.com/Tabesh2020/manim-fa) برای متنِ فارسی، افکتِ نوشتن و فونتِ وزیرمتن
  ([Vazirmatn](https://github.com/rastikerdar/vazirmatn) از صابر راستی‌کردار).
- مجوز: [MIT](LICENSE.md)
