Metadata-Version: 2.4
Name: manim-fa-chemistry
Version: 0.2.0
Summary: Persian-language (فارسی) fork of manim-Chemistry, localized for use with manim-fa to create Persian chemistry animations.
Author-email: UMDQ <unmoldequimica@gmail.com>
Maintainer: Tabesh2020
License: MIT License
        
        Copyright (c) 2023 UMDQ
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Source, https://github.com/Tabesh2020/manim-fa-chemistry
Project-URL: Issue tracker, https://github.com/Tabesh2020/manim-fa-chemistry/issues
Project-URL: Homepage, https://github.com/Tabesh2020/manim-fa-chemistry
Project-URL: Upstream, https://github.com/UnMolDeQuimica/manim-Chemistry
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: Persian
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: manim
Requires-Dist: manim-fa
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pytest
Requires-Dist: xmltodict
Requires-Dist: requests
Dynamic: license-file

# manim-fa-chemistry (نسخه‌ی فارسی)

این ریپو نسخه‌ی فارسی‌سازی‌شده‌ی [manim-Chemistry](https://github.com/UnMolDeQuimica/manim-Chemistry)
است که برای کار با پلاگین [manim-fa](https://github.com/Tabesh2020/manim-fa)
بازنویسی شده تا بتوان با آن ویدیوهای آموزشی شیمی به زبان فارسی ساخت. جدول
تناوبی، نام‌گذاری مولکول‌ها و فرمول‌های شیمیایی اکنون از فونت Vazirmatn و
رندر راست‌چین صحیح (به کمک `FaText`) پشتیبانی می‌کنند؛ بقیه‌ی رفتار کتابخانه
(پارس فایل‌های `.mol`/`.sdf`/...، مولکول‌های سه‌بعدی، اوربیتال‌ها و نمودار
بور) بدون تغییر و کاملاً سازگار با نسخه‌ی فعلی Manim (v0.21) باقی مانده است.

## مثال سریع فارسی

```python
from manim import *
from manim_fa_chemistry import *

class PeriodicTableFa(Scene):
    def construct(self):
        # به‌صورت پیش‌فرض از داده‌های فارسی (Elements_FA.csv) استفاده می‌کند
        self.add(PeriodicTable())

class NamedMoleculeFa(Scene):
    def construct(self):
        morphine = NamedMolecule.from_mol_file(
            name="مورفین",
            filename="morphine.mol",
        )
        self.add(morphine)

class NamedFormulaFa(Scene):
    def construct(self):
        self.add(NamedFormula(metal_name="سدیم", non_metal_name="کلرید", formula="NaCl"))
```

برای استفاده از داده‌های انگلیسی اصلی، فایل `Elements_EN.csv` را به‌صورت
دستی به `PeriodicTable(data_file=...)` بدهید.

---

# مستندات
برای توضیحات کامل‌تر، [مستندات پروژه‌ی اصلی](https://manim-chemistry.readthedocs.io/en/latest/) (به انگلیسی) را ببینید.


# فهرست مطالب:
- [نصب](#نصب)
- [manim-Chemistry چیست؟](#manim-chemistry-چیست)
- [manim-Chemistry الان چه کارهایی می‌تواند بکند؟](#manim-chemistry-الان-چه-کارهایی-می‌تواند-بکند)
- [ساخت مولکول‌های دوبعدی](#ساخت-مولکول‌های-دوبعدی)
- [ساخت مولکول سه‌بعدی](#ساخت-مولکول-سه‌بعدی)
- [ساخت جدول تناوبی](#ساخت-جدول-تناوبی)
- [ساخت اوربیتال‌های اتمی](#ساخت-اوربیتال‌های-اتمی)
- [ساخت نمودار بور](#ساخت-نمودار-بور)
- [خواندن فایل‌های .mol](#خواندن-فایلهای-mol)
- [نمونه‌کارها](#نمونه‌کارها)
- [ساخته‌شده با manim_fa_chemistry](#ساخته‌شده-با-manim_fa_chemistry)
- [راه ارتباطی](#راه-ارتباطی)
- [مشارکت‌کنندگان بزرگ](#مشارکت‌کنندگان-بزرگ)

# نصب

می‌توانید با pip نصب کنید:

```
pip install manim-fa-chemistry
```

یا ریپو را کلون کرده و از همان‌جا نصب کنید:

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

یا

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

اگر پکیج را قبلاً نصب کرده‌اید و فقط می‌خواهید آن را به آخرین نسخه به‌روزرسانی کنید:

```
python -m pip install --upgrade manim-fa-chemistry
```

# manim-Chemistry چیست؟

manim-Chemistry یک پلاگین برای Manim است که ساخت انیمیشن‌های شیمی را آسان‌تر می‌کند.

تا جایی که نویسنده‌ی اصلی اطلاع دارد، تنها پلاگین دیگر مرتبط با شیمی [chanim](https://github.com/kilacoda/chanim) است که تلاش می‌کند پکیج chemfig را به Manim وارد کند (و کار فوق‌العاده‌ای هم انجام می‌دهد!).

فلسفه‌ی manim-Chemistry مسیر متفاوتی را دنبال می‌کند: این پلاگین سعی می‌کند ابزارهای Manim را با فایل‌های داده‌ی شیمیایی (`.mol`، `.sdf`، `.json`، `.asnt` و `.xlm`) ترکیب کند تا با کلاس‌هایی ساده اما کاربردی، انیمیشن‌های زیبای شیمیایی مثل جدول تناوبی یا ساختارهای دو و سه‌بعدی بسازد.

همچنین، manim-Chemistry تلاش می‌کند تا حد امکان همه‌چیز را از صفر بسازد. یعنی از کتابخانه‌هایی مثل [Mendeleev](https://mendeleev.readthedocs.io/en/stable/)، [RDKit](https://www.rdkit.org/)، [PyMOL](https://pymol.org/2/)، [Open Babel](https://openbabel.org/wiki/Main_Page) و مانند آن‌ها پرهیز می‌شود. دلیلش این است که وابستگی به پکیج‌های شخص‌ثالثی که ممکن است نگهداری سنگینی بخواهند، کم شود. با این حال، کاربران می‌توانند قدرت آن کتابخانه‌ها را با manim-Chemistry ترکیب کنند تا کارشان راحت‌تر شود. تنها کتابخانه‌ی شخص‌ثالثی که استفاده شده PubChem است، به‌خاطر سادگی وارد کردن مستقیم مولکول‌ها از وب‌سایتش.

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

# manim-Chemistry الان چه کارهایی می‌تواند بکند؟

در ادامه خلاصه‌ای از قابلیت‌های manim-Chemistry آمده است. چون پروژه‌ی اصلی هنوز در حال توسعه است، ممکن است این خلاصه کاملاً به‌روز نباشد. برای دید بهتر، نمونه‌کارها (examples) را ببینید. همچنین فایل TODO می‌تواند نشان بدهد چه چیزهایی در راه است. اگر پیشنهادی برای پلاگین اصلی دارید، در ریپوی upstream ایشو یا پول‌ریکوئست باز کنید.

## ساخت مولکول‌های دوبعدی

برای ساخت مولکول دوبعدی فقط کافی است یک فایل `.mol` با داده‌ی اتم‌ها و پیوندها داشته باشید. فایل morphine.mol داخل پوشه‌ی examples را ببینید تا بدانید ساختار فایل چه شکلی باید باشد.

برای ساخت یک صحنه با یک مولکول دوبعدی، ساختار کد باید این‌طور باشد:

```
from manim import *
from manim_fa_chemistry import *

class TwoDMoleculeScene(Scene):
   def construct(self):
        morphine = MMoleculeObject.molecule_from_file("morphine.mol")
        self.add(morphine)
```

مثل همیشه می‌توانید Manim را اجرا کنید:

`manim .\examples.py -ps`

نتیجه این‌طوری می‌شود:

![plot](/examples/examples_assets/2D_morphine_bad.png)

خیلی خوب به نظر نمی‌رسد، درسته؟ پیوندهای دوگانه در جای درستی قرار نگرفته‌اند. می‌توانیم این را حل کنیم!

می‌توانید یک گزینه را روی True بگذارید تا شماره‌ی پیوندها را ببینید. کار مشابهی هم برای اتم‌ها می‌توانید انجام دهید. این شماره‌گذاری از فایل `.mol` می‌آید و ربطی به ساختار شیمیایی ندارد.

```
from manim import *
from manim_fa_chemistry import *

class TwoDMoleculeScene(Scene):
   def construct(self):
        morphine = MMoleculeObject.molecule_from_file("morphine.mol", add_bonds_numbering=True)
        self.add(morphine)
```

نتیجه:

![plot](/examples/examples_assets/2D_morphine_bond_numbering.png)

پس باید پیوندهای شماره‌ی ۷ و ۲۰ را بچرخانیم. می‌توانیم با اضافه کردن اندیس آن‌ها به لیست rotate_bonds این کار را انجام دهیم:

```
from manim import *
from manim_fa_chemistry import *

class TwoDMoleculeScene(Scene):
   def construct(self):
        morphine = MMoleculeObject.molecule_from_file("morphine.mol", rotate_bonds=[7, 20])
        self.add(morphine)
```

نتیجه:
![plot](/examples/examples_assets/2D_morphine_corrected_bonds.png)

حالا شد!

### مولکول‌های نام‌گذاری‌شده (Named Molecules):

شاید بخواهید به یک مولکول یک نام هم اضافه کنید. کار بسیار ساده‌ای است، اما انجام همه‌چیز در یک آبجکت واحد راحت است. می‌توانید یک NamedMolecule بسازید، شبیه به همان روشی که یک MMoleculeObject می‌سازید:

```
from manim import *
from manim_fa_chemistry import *

class NamedMoleculeExample(Scene):
    def construct(self):
        named_molecule = NamedMolecule.molecule_from_file(name="مورفین", filename="morphine.mol")
        self.add(named_molecule)
```
![plot](/examples/examples_assets/NamedMoleculeExample_ManimCE_v0.17.3.png)

می‌توانید یک مولکول یا یک متن از پیش ساخته‌شده هم بدهید و کلاس NamedMolecule آن‌ها را با هم گروه می‌کند. این کنترل بیشتری به کاربر می‌دهد.

### GraphMolecule:
یک نوع دیگر از مولکول‌های دوبعدی، GraphMolecule است. این‌ها بر پایه‌ی کلاس Graph در Manim ساخته شده‌اند که قابلیت‌های زیادی به آن‌ها می‌دهد!

می‌توانید تقریباً به همان شکلی که با MMolecule و NamedMolecule کار کردید، از این‌ها هم استفاده کنید:

```
from manim import *
from manim_fa_chemistry import *

class GraphMoleculeExample(Scene):
    def construct(self):
        graph_molecule = GraphMolecule.molecule_from_file(filepath="morphine.mol")
        self.add(graph_molecule)
```
![plot](/examples/examples_assets/DrawGraphMorphine_ManimCE_v0.17.3.png)

بفرمایید!

همچنین می‌توانید با تنظیم `label=True` هنگام ساخت GraphMolecule، برچسب هم اضافه کنید:
```
from manim import *
from manim_fa_chemistry import *

class GraphMoleculeExample(Scene):
    def construct(self):
        graph_molecule = GraphMolecule.molecule_from_file(
            mol_file="morphine.mol",
            label=True
        )
        self.add(graph_molecule)
```
![plot](/examples/examples_assets/DrawLabeledGraphMorphine_ManimCE_v0.17.3.png)

با استفاده از `label=True` و `numeric_label=True` مولکول را با اتم‌های برچسب‌خورده بر اساس فایل mol می‌گیرید:
```
from manim import *
from manim_fa_chemistry import *

class GraphMoleculeExample(Scene):
    def construct(self):
        graph_molecule = GraphMolecule.molecule_from_file(
            mol_file="morphine.mol",
            label=True,
            numeric_label=True
        )
        self.add(graph_molecule)
```
![plot](/examples/examples_assets/DrawLabeledWithIndexGraphMorphine_ManimCE_v0.17.3.png)

### انتخاب بخشی از مولکول و انیمیشن‌های سفارشی در GraphMolecule:
قدرت گراف‌ها واقعاً در GraphMolecule نمایان می‌شود. یکی از نمونه‌های این قدرت استفاده از `networkx` برای گرفتن بخشی از مولکول با مشخص کردن اتم شروع و پایان است. مثلاً می‌توانیم بخشی از مولکول را رنگ کنیم:


```python
class GraphMoleculeExample(Scene):
    def construct(self):
        molecule = GraphMolecule.molecule_from_file(asset, label=True, numeric_label=True)
        atoms_and_bonds = molecule.get_connected_atoms_and_bonds(1, 3)
        atoms_and_bonds.set_color(GREEN)
        self.add(molecule)
```
![plot](/examples/examples_assets/PartiallyColoredGraphMolecule.png)



همچنین می‌توانید با GMAnimationBuilder انیمیشن‌های سفارشی هم بسازید: rotate_atoms_about_bond و change_color:

![plot](/examples/examples_assets/CustomGraphMoleculeAnimation.gif)



## ساخت مولکول سه‌بعدی:

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

۱. یک فایل `.mol` (مثل قبل)
۲. یک فایل داده‌ی csv با داده‌ی اتم‌ها. نمونه‌ای از آن را داخل پوشه‌ی examples با نام "Elementos.csv" پیدا می‌کنید.

فایل `.mol` پارس می‌شود و فایل csv برخی داده‌ها، مخصوصاً رنگ، را به manim-Chemistry می‌گوید. با استفاده از همان فایل قبلی می‌توانیم یک ساختار سه‌بعدی برای مورفین بسازیم:

```
from manim import *
from manim_fa_chemistry import *

class Draw3DMorphine(ThreeDScene):
    def construct(self):
        config.renderer = "opengl"
        three_d_morphine = ThreeDMolecule.molecule_from_file("morphine.mol")
        self.add(three_d_morphine)
        self.wait()
```

برای اجرای این کد باید Manim را با رندرر opengl اجرا کنید:

`manim .\examples.py Draw3DMorphine -ps --renderer=opengl`

نتیجه این است!

![plot](/examples/examples_assets/Draw3DMorphine_ManimCE_v0.17.3.png)


## ساخت جدول تناوبی:
مثل قبل، برای رسم همه‌چیز به یک فایل منبع نیاز داریم. باز هم می‌توانید فایل خودتان را از روی یک کپی از "Elementos.csv" بسازید.

می‌توانید قاب یک عنصر را این‌طور بسازید:

```
from manim import *
from manim_fa_chemistry import *

class DrawCarbonElement(Scene):
    def construct(self):
        carbon = MElementObject.from_csv_file_data(filename="Elementos.csv", atomic_number=6)
        self.add(carbon)
```

و همینه!

![plot](/examples/examples_assets/DrawCarbonElement_ManimCE_v0.17.3.png)


برای ساخت کل جدول تناوبی، باید داده‌ی هر عنصر داخل آن فایل منبع باشد. فایل Elementos.csv از قبل این داده را دارد، پس فقط کافیست آن را کپی کرده و متناسب با نیازتان تغییر دهید. با رنگ‌بندی cpk و کد زیر، آن جدول تناوبی زیبا را می‌گیریم:

```
from manim import *
from manim_fa_chemistry import *

class DrawPeriodicTable(Scene):
    def construct(self):
        self.add(PeriodicTable(data_file="Elementos.csv"))
```

![plot](/examples/examples_assets/DrawPeriodicTable_FA_ManimCE_v0.21.0.png)


## ساخت اوربیتال‌های اتمی:

اوربیتال‌های مولکولی برای یک اسکریپت پایتون ساده بسیار پیچیده و سنگین هستند، اما می‌توانیم اوربیتال‌های اتمی را با انتخاب سطح l و m به‌سادگی بگیریم:

```
from manim import *
from manim_fa_chemistry import *

class DrawPOrbital(Scene):
    def construct(self):
        orbital = Orbital(l=1, m=-1)
        self.add(orbital)
```

این‌جا هم باید از رندرر opengl استفاده کنید:

`manim .\examples.py DrawPOrbital -ps --renderer=opengl`

![plot](/examples/examples_assets/orbitals_example.png)

## ساخت نمودار بور:

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

```
from manim import *
from manim_fa_chemistry import *

class DrawBohrDiagram(Scene):
    def construct(self):
        diagram = BohrAtom(e=14, p=14, n=10)
        self.add(diagram)
```
نمودار زیبای‌تان را داشته باشید!

![plot](/examples/examples_assets/BohrDiagram_ManimCE_v0.17.3.png)


# نمونه‌کارها:

داخل این ریپو یک پوشه‌ی examples با فایل‌ها و دارایی‌های پایه وجود دارد که ممکن است مفید باشند. حتماً آن‌ها را ببینید!

# ساخته‌شده با manim_fa_chemistry

چند نمونه از کارهای ساخته‌شده با manim_fa_chemistry را ببینید. خوشحال می‌شویم انیمیشن‌ها و ویدیوهای خودتان را هم به این لیست اضافه کنید!

فولرین:
![plot](/examples/examples_assets/Fullerene.png)

ساختارهای بتا و آلفای قلع:
![plot](/examples/examples_assets/TinPhases.png)

ویدیوهایی با manimChemistry:

https://www.youtube.com/watch?v=L7OXe94_WmA

https://youtu.be/KgiCl_o_Aws


# راه ارتباطی
این ریپو فورک فارسی **manim-fa-chemistry** است — برای مشکلات مربوط به فارسی‌سازی (برچسب‌ها، فونت، یکپارچه‌سازی `FaText`)، لطفاً در
[Tabesh2020/manim-fa-chemistry](https://github.com/Tabesh2020/manim-fa-chemistry/issues) ایشو باز کنید.

برای پروژه‌ی اصلی و upstream یعنی manim-Chemistry، می‌توانید همان‌جا ایشو یا پول‌ریکوئست باز کنید، یا مستقیم با نویسنده‌ی اصلی تماس بگیرید:
- ایمیل: unmoldequimica@gmail.com
- یوتیوب: https://www.youtube.com/@unmoldequimica
- توییتر: https://twitter.com/unmoldequimica


# مشارکت‌کنندگان بزرگ!
- [@chemnerd28](https://github.com/chemnerd28)
- [@Ant-28](https://github.com/Ant-28)
- [@davidmariscalf](https://github.com/davidmariscalf) (David Mariscal Fernández)


تشکر ویژه از [@Rodrigo-Tenorio](https://github.com/Rodrigo-Tenorio) برای کمکش در ساخت نسخه‌ی قابل‌انتشار این پکیج.
