کتاب جامع مهندسی MRI — ساخت یک دستگاه پیشرفته از صفر

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

این فایل، راهنمای راه‌اندازی محیط، ویرایش و ساختِ کتاب است. نقشهٔ کامل محتوا در outline/chapters.yml و واژگانِ کنترل‌شده در glossary/ است.

---

دربارهٔ کتاب

این کتاب یک رسالهٔ مهندسیِ به‌روز و حالت‌روز است که از ریاضیِ دبیرستان آغاز می‌کند و تا ابزارهای دقیقی که مهندسی MRI واقعاً نیاز دارد بالا می‌رود؛ سپس همان مبانی را به طراحی، ساخت، آزمون، ایمنی و نگه‌داریِ هر زیرسامانه تبدیل می‌کند. پوشش در ۱۱ جلد و ۷۷ فصل سازمان یافته است:

جلد	دامنه
۱	مبانی ریاضی و فیزیک (حساب برداری، اعداد مختلط، جبر خطی، فوریه، معادلات دیفرانسیل، احتمال، الکترومغناطیس، مکانیک کوانتومیِ اسپین، فیزیک دما-پایین)
۲	فیزیک تشدید مغناطیسی، شکل‌گیری سیگنال، معادلات بلاخ، فضای‑کی، توالی‌های پالس و شتاب‌دهی
۳	مهندسی آهنربا، ابررسانایی، کوئنچ، کرایوستات، آهنرباهای دائمی/میدان‑پایین و شیم
۴	الکترونیک گرادیان و رادیوفرکانس (سیم‌پیچ‌ها، تقویت‌کننده‌های توان، آرایه‌های گیرنده، زنجیرهٔ دیجیتال)
۵	کنسول، میان‌افزار FPGA، کنسول‌های متن‌باز، نرم‌افزار بی‌درنگ و Pulseq
۶	بازسازی تصویر و تصویربرداری محاسباتی (فوریه، آرتیفکت‌ها، حس‌گری فشرده، یادگیری ژرف)
۷	ساخت و یکپارچه‌سازی سامانه (مواد، ماشین‌کاری، PCB، اتاق حفاظ‌دار، ISO 13485)
۸	آزمون، راستی‌آزمایی، راه‌اندازی و برنامه‌های QA
۹	مهندسی ایمنیِ بیمار و دستگاه (ISO 14971، IEC 60601، ایمنی کرایوژنیک)
۱۰	سرویس، نگه‌داری و پایگاه دانشِ تعمیرات
۱۱	پزشکی، مقررات (FDA/CE/ایران) و تجاری‌سازی

زبان و قالب: بدنهٔ فارسیِ راست‌به‌چپ با «جزیره‌های چپ‌به‌راست» (LTR) برای ریاضی، کد و نمودارها. خروجی‌ها: وب‌سایت (HTML روی GitHub Pages)، PDF آمادهٔ چاپ، و EPUB — یک کتابِ الکترونیکیِ بازجریان‌پذیرِ (reflowable) راست‌به‌چپ با فونتِ Vazirmatnِ نهفته، ریاضیِ MathML و نمودارهای برداریِ SVG.

---

ساختار مخزن

.
├── _quarto.yml              # پیکربندی کتابِ Quarto  (تولیدشده توسط tools/gen_stubs.py)
├── index.qmd                # پیش‌گفتار / «چه خواهید توانست»
├── chapters/                # یک .qmd به‌ازای هر فصل (۷۷ فصل)
├── appendices/              # پیوست‌های A تا G (کلید پاسخ، واژه‌نامه، جدول‌ها، …)
├── outline/chapters.yml     # ★ سرفصلِ مرجع — تنها منبعِ حقیقت برای فهرست فصل‌ها
├── tools/gen_stubs.py       # تولید اسکلت فصل‌ها + _quarto.yml از روی سرفصل
├── tools/build_diagrams.py  # ★ سازندهٔ نمودارها (LuaLaTeX→PyMuPDF؛ روی همهٔ سکوها)
├── tools/build_diagrams.ps1 # پوستهٔ ویندوزیِ سازندهٔ نمودارها
├── tools/pdf_to_png.py      # رِستر کردنِ PDF برای بازبینیِ چشمی (PDFium)
├── glossary/                # واژگانِ کنترل‌شدهٔ فا–en + قراردادهای نگارش
├── templates/               # قالب‌های فصل/آزمون/ایمنی/تعمیرات
├── diagrams/                # منابع TikZ → SVG (وب) + PDF (چاپ)  + Makefile
├── references/refs.bib      # کتاب‌نامهٔ BibTeX
├── theme/                   # preamble.tex (babel/Vazirmatn) + ltr.lua + custom.scss (HTML) + epub.css (EPUB)
├── fonts/                   # فونت Vazirmatn (.ttf، درون مخزن، هنگام ساخت با مسیر بار می‌شود)
├── cover/                   # طرح جلد (png برای وب، pdf/tex برای چاپ)
├── smoke-test.qmd           # سندِ اعتبارسنجیِ زنجیرهٔ ابزار (فارسی+ریاضی+کد+TikZ)
└── .github/workflows/       # CI: رِندرِ PDF+HTML در هر push و استقرار روی Pages

مهم: فهرستِ فصل‌ها در _quarto.yml و اسکلتِ فایل‌های chapters/ تولیدشده‌اند. برای افزودن/جابه‌جاییِ فصل، سرفصل را در outline/chapters.yml ویرایش کنید و سپس python tools/gen_stubs.py را اجرا کنید (این کار محتوای فصل‌هایِ نوشته‌شده را پاک نمی‌کند، فقط اسکلتِ فصل‌های تازه را می‌سازد و _quarto.yml را به‌روزرسانی می‌کند).

---

راه‌اندازی محیط

این پروژه روی ویندوز و بدونِ دسترسیِ مدیر (per-user) راه‌اندازی شده است؛ همان ابزارها روی لینوکس/مک نیز کار می‌کنند (CI روی لینوکس می‌سازد). چهار مؤلفه لازم است:

۱. Quarto (≥ 1.4؛ این پروژه با 1.9 آزموده شده)

موتورِ انتشار که .qmd را به HTML/PDF تبدیل می‌کند — https://quarto.org/docs/get-started/. نصبِ قابل‌حملِ این محیط در %LOCALAPPDATA%\Programs\Quarto است؛ پوشهٔ bin آن را به PATH بیفزایید:

$env:Path = "$env:LOCALAPPDATA\Programs\Quarto\bin;$env:Path"
quarto --version

۲. توزیع TeX با LuaLaTeX (TinyTeX)

• PDFِ کتاب با LuaLaTeX + بستهٔ babel (bidi=basic) ساخته می‌شود (راست‌به‌چپِ فارسی).
• نمودارها نیز با همان LuaLaTeX + babel کامپایل می‌شوند و سپس با PyMuPDF به اندازهٔ محتوا بریده و به PDF (چاپ) و SVG (وب) تبدیل می‌شوند — نه با XeLaTeX/dvisvgm (جزئیات در «نکات کلیدی»).

نصبِ این محیط، TinyTeX در %APPDATA%\TinyTeX است و دودویی‌ها در %APPDATA%\TinyTeX\bin\windows قرار دارند. این پوشه را به PATH بیفزایید:

$env:Path = "$env:APPDATA\TinyTeX\bin\windows;$env:Path"
lualatex --version

بسته‌های لازم (نمودارها با لوآلاتکِ مستقیم ساخته می‌شوند، پس همه باید از پیش نصب باشند): fontspec, babel (locale فارسی درون خودِ babel است؛ بستهٔ جداگانهٔ babel-persian وجود ندارد)، luaotfload, tikz/pgf, pgfplots, geometry, amsmath, amsfonts, mathtools, xcolor, unicode-math, koma-script, fancyvrb, fvextra, framed, pdfpages, lm. روی TeX Live کامل همه موجودند؛ روی TinyTeX:

tlmgr install fontspec babel luaotfload unicode-math \
  geometry pgf pgfplots xcolor amsmath amsfonts mathtools \
  fancyvrb fvextra framed pdfpages koma-script lm

برشِ نمودارها به PyMuPDF (پایتون) نیاز دارد؛ pip install -r requirements.txt.

هشدارِ زنجیرهٔ ابزار (با هزینهٔ گزاف آموخته شده): از xepersian یا polyglossia استفاده نکنید. هر دو شکست خوردند (xepersian روی array/longtable می‌شکند و polyglossia فونت‌های اضافی می‌طلبد). مسیرِ معتبر و آزموده، LuaLaTeX به‌همراه babel با گزینهٔ bidi=basic است که در theme/preamble.tex پیکربندی شده.

۳. فونت Vazirmatn

فایل‌های .ttf در fonts/ درون مخزن‌اند و هنگام ساخت با مسیر بار می‌شوند — کتاب با Path=fonts/ و نمودارها با \babelfont{rm}[Renderer=Node, Path=../fonts/, …]{Vazirmatn}؛ نیازی به نصبِ سیستمی یا OSFONTDIR نیست. برای به‌روزرسانی فونت از https://github.com/rastikerdar/vazirmatn دوباره دریافت کنید.

۴. Python (≥ 3.10)

فقط برای تولیدِ اسکلت‌ها و چند ابزارِ کمکی لازم است.

pip install -r requirements.txt          # PyYAML و وابستگی‌های آزمایشگاه‌ها

نکتهٔ ویندوز: pythonِ خام ممکن است به stubِ فروشگاهِ مایکروسافت اشاره کند. در این محیط، مفسرِ واقعی C:\Program Files\Python\python.exe است؛ برای ابزارهای کمکی همان را صدا بزنید.

---

ساختِ کتاب (Build)

# ۱) (در صورت تغییرِ سرفصل) تولیدِ اسکلت فصل‌ها + _quarto.yml از روی outline
python tools/gen_stubs.py

# ۲) ساختِ نمودارهای برداری (PDF برای چاپ، SVG برای وب)
#    روی لینوکس/مک با make:
make -C diagrams
#    روی ویندوز (make روی PATH نیست) با اسکریپتِ هم‌ارز:
powershell -ExecutionPolicy Bypass -File tools/build_diagrams.ps1
#    ساختِ زیرمجموعه:  ... -Filter '33-*'

# ۳) رِندرِ کتاب (خروجی در _book/)
quarto render --to html     # وب‌سایت (روی GitHub Pages مستقر می‌شود)
quarto render --to pdf      # چاپ (LuaLaTeX + babel bidi=basic)
quarto render --to epub     # کتابِ الکترونیکی (EPUB3: راست‌به‌چپ، MathML، Vazirmatnِ نهفته، SVG)
quarto render               # همهٔ قالب‌های پیکربندی‌شده (HTML + PDF + EPUB)

EPUB: خروجیِ _book/*.epub یک کتابِ الکترونیکیِ EPUB3 است. راست‌به‌چپی از دو راه تأمین می‌شود: page-progression-direction: rtl در ستونِ فقراتِ (spine) فایل (ورق‌خوردنِ صفحات از راست) و قواعدِ direction: rtl در theme/epub.css (که فونتِ نهفتهٔ Vazirmatn را هم با @font-face به‌کار می‌گیرد و جزیره‌های LTRِ کد/ریاضی/اصطلاحات را ایزوله می‌کند). ریاضی به‌صورتِ MathML (معنایی، بدونِ جاوااسکریپت) و نمودارها همان SVGهای وب‌اند — چون Quarto در شاخهٔ when-format="html" خروجیِ EPUB را هم می‌سازد، نیازی به تغییرِ فصل‌ها نبود.

آزمونِ دود (نخست این را اجرا کنید)

پیش از سرمایه‌گذاری روی محتوا، smoke-test.qmd را به هر دو قالبِ PDF و HTML رِندر کنید و تأیید کنید که: نثرِ فارسی راست‌به‌چپ و با Vazirmatn جاری است؛ ریاضی/کد/اصطلاحاتِ انگلیسی چپ‌به‌راست و بدون آینه‌شدن هستند؛ بلوک‌های کد چپ‌چین‌اند؛ و نمودارِ TikZ به‌صورتِ برداریِ تیز دیده می‌شود.

quarto render smoke-test.qmd --to pdf
quarto render smoke-test.qmd --to html

---

نکاتِ کلیدیِ زنجیرهٔ ابزار (پیش از ویرایش بخوانید)

این‌ها مشکلاتی‌اند که حل شده‌اند؛ دست‌نخورده نگه‌شان دارید:

• بدونِ lang:ِ سراسری در _quarto.yml. تنظیمِ سراسریِ lang باعث می‌شود Pandoc برای PDF بسته‌های babel/polyglossia را بار کند و با preamble ما تداخل کند. lang/dir فقط روی قالبِ html تنظیم شده‌اند.
• نمودارها با LuaLaTeX + babel ساخته می‌شوند، نه XeLaTeX + بستهٔ bidi. در نسخهٔ پیشین (XeLaTeX + bidi)، متنِ چندخطیِ فارسیِ گره‌ها وارونه می‌شد: سطرِ اولِ گره‌های text width و کلِ گره‌های align چپ‌به‌راست درمی‌آمدند (این خطا در PDFِ نمودار بود و SVG صرفاً آن را بازتاب می‌داد). راه‌حلِ ریشه‌ای، استفاده از همان موتورِ بدنهٔ کتاب است: LuaLaTeX + babel bidi=basic + Renderer=Node که فارسی را درست می‌چیند. هر تصویر در \babelsublr{...} پیچیده می‌شود تا صفحهٔ راست‌به‌چپ هندسهٔ شکل را آینه نکند، حال‌آنکه متنِ گره‌ها از طریقِ bidi راست‌به‌چپ می‌ماند. سپس PyMuPDF صفحهٔ بزرگ را به اندازهٔ محتوا می‌برد و SVG را با گلیف‌های مسیر-شده (text_as_path، بدونِ <text>) می‌سازد — پس از bidiِ مرورگر هم مصون است. کلِ خط‌لوله در tools/build_diagrams.py است؛ Makefile و build_diagrams.ps1 فقط پوسته‌اند. هر فایلِ diagrams/*.tex اکنون با کلاسِ article + babel و یک \babelsublr نوشته شده است (نه standalone + \setRTL).
• بلوک‌های کد با پیچیدنِ کلِ بلوک در \begin{otherlanguage}{english} (از طریقِ CodeBlock در theme/ltr.lua) چپ‌به‌راست می‌شوند — هرگز خودِ محیطِ verbatim را نپیچید.
• رِندرِ Quarto اگر PDFِ کتاب در _book/ در یک نمایشگرِ PDF باز باشد شکست می‌خورد (safeRemoveDirSync). پیش از رِندرِ دوباره نمایشگر را ببندید (یا با --output-dir به جای دیگری بسازید).
• عمقِ فهرست: در _quarto.yml از toc-depth: 2 استفاده شده (Quarto آن را به tocdepth 1 نگاشت می‌کند) تا فهرستِ PDF فشرده بماند.
• کپی/جست‌وجوی متنِ فارسی در PDF توسطِ theme/pdf-copytext.lua (که از theme/preamble.tex بار می‌شود) درست شده است. خروجیِ خامِ LuaLaTeX سه عیب داشت: (۱) هر سطرِ راست‌به‌چپ به ترتیبِ منطقی و با قلمِ رو‌به‌چپ در جریانِ محتوا نوشته می‌شد، ولی نمایشگرها (PDFium/Chrome/Edge، Acrobat) ترتیبِ دیداری را فرض می‌کنند و حروفِ کپی‌شده وارونه درمی‌آمدند؛ (۲) فونتِ Vazirmatn گلیف‌های شکل‌گرفته را به کدهای «Presentation Forms» (مثلاً U+FBFE به جای ی) نگاشت می‌کند و همان به ToUnicode می‌رفت، پس متنِ کپی‌شده «عربی/غیراستاندارد» به نظر می‌رسید و با جست‌وجو یافت نمی‌شد؛ (۳) نیم‌فاصله (ZWNJ) هرگز به PDF نمی‌رسید: قالبِ LaTeXِ Pandoc آن را به \discretionary{-}{}{\kern.03em} (بدونِ گلیف) تبدیل می‌کند و luaotfload هم گلیفِ ZWNJ را با گلیفِ فاصله + kern جایگزین می‌کرد؛ «می‌شود» به «میشود» کپی می‌شد. مازول هنگامِ shipout هر hlistِ راست‌به‌چپ را به ترتیبِ دیداری بازمی‌سازد (با حفظِ دقیقِ پیوندها، رنگ‌ها، علائمِ ترکیبی و عرضِ جعبه‌ها) و ToUnicode را به حروفِ واقعی برمی‌گرداند؛ theme/preamble.tex هم \zerowidthnonjoiner را بازتعریف می‌کند تا گلیفِ واقعیِ U+200C درونِ همان discretionary بنشیند (چیدمان و شکستِ سطر یکسان) و با RawFeature={invisible=8204} در \babelfont آن گلیف را نگه می‌دارد. چیدمانِ صفحه تغییر نمی‌کند (تنها ترتیبِ نوشتنِ گلیف‌ها در جریانِ PDF؛ استثنا: نقطه‌چینِ فهرست که فاصله و هم‌ترازیِ عمودی‌اش یکسان می‌ماند ولی شبکهٔ نقطه‌ها می‌تواند کمتر از یک فاصلهٔ نقطه جابه‌جا شود)؛ با python tools/pdf_text_check.py قبل.pdf بعد.pdf --geometry می‌توان یکسانیِ هندسیِ دو PDF را و با python tools/pdf_text_check.py کتاب.pdf --page N کیفیتِ متنِ استخراج‌شده را سنجید. سطرهایی که یک پیوند/رنگِ آن‌ها به سطرِ بعد ادامه دارد به همان شکلِ پیشین (منطقی) می‌مانند و شمارشان در پایانِ لاگِ LaTeX گزارش می‌شود (pdf-copytext: … left as is).

---

قراردادهای نگارش

• جزیره‌های چپ‌به‌راست (اصطلاح انگلیسی، نماد، عدد در متن) را با اسپَنِ […]{.ltr} یا بلوکِ ::: {.ltr} بپیچید؛ theme/ltr.lua آن را به خروجیِ درست نگاشت می‌کند (HTML dir="ltr" / LaTeX \babelsublr/otherlanguage). ریاضی و کد خودکار مدیریت می‌شوند.
• از واژگانِ کنترل‌شدهٔ glossary/terms-fa-en.csv استفاده کنید؛ معادل‌ها را همان‌جا بیفزایید، نه به‌صورتِ درون‌خطی. قراردادهای کامل در glossary/conventions.md.
• هر ادعای فنی یک ارجاع در references/refs.bib می‌گیرد.
• فصل‌های تازه از templates/chapter-template.qmd آغاز می‌شوند.
• درستیِ عددی: ادعاهای کمّی (فرمول، نتیجهٔ شبیه‌سازی، مثال‌های عددی) با اسکریپت‌های کوتاهِ پایتون راستی‌آزمایی می‌شوند؛ این فایل‌های scratch با پیشوندِ _ نام‌گذاری و در .gitignore نادیده گرفته می‌شوند.

---

استقرار (GitHub Pages)

گردش‌کارِ .github/workflows/build.yml در هر push، کتاب را رِندر و سایت را روی GitHub Pages مستقر می‌کند. برای فعال‌سازی: مخزن را push کنید و در تنظیماتِ Pages، منبع را روی «GitHub Actions» بگذارید.

---

وضعیت پروژه

اسکلتِ پروژه و سرفصلِ کامل آماده است و نثرِ فصل‌ها جلدبه‌جلد و به‌ترتیبِ وابستگی (جلد ۱ → ۱۱) نوشته می‌شود. هدف‌ها، پیش‌نیازها، برآوردِ صفحات و پرچم‌های محتوای هر فصل در outline/chapters.yml آمده است.