A desktop math workspace for capture -> recognize -> handwrite -> edit -> compute

FAQ · Releases

Star History

LaTeXSnipper is no longer just a "screenshot formula -> LaTeX" utility. It is a desktop workspace built for end-to-end math content workflows:

• Capture and recognize mathematical content from screenshots
• Continue editing and computing in the integrated math workbench
• Handwrite expressions in a dedicated canvas and convert to LaTeX
• Send results back to the main editor or copy to clipboard

The Math Workbench supports a complete workflow:

1. Capture and recognize formulas from the main window
2. Load results into the workbench in one click
3. Edit expressions in the MathLive area
4. Use the virtual math keyboard for fractions, superscripts, integrals, series, and more
5. Run Compute / Simplify / Numeric / Expand / Factor / Solve
6. Write results back to the editor or copy as LaTeX / MathJSON

The Auto Typesetting Document Window supports source-level editing with synchronized preview:

1. Open "Auto Typesetting" from the handwriting window
2. Edit full source in the left TeX Document pane
3. Insert complex expressions with the built-in formula editor
4. Compile and preview PDF directly
5. Navigate bi-directionally between source and PDF via SyncTeX
6. Export .tex or PDF when needed

The handwriting window supports the following flow:

1. Open "Handwriting Recognition" from the main window
2. Write formulas directly on an isolated canvas
3. Trigger MathCraft mixed OCR automatically after pen-up, so handwritten text and formulas can be kept together
4. See live LaTeX output and rendered preview on the right
5. Use "Auto Typesetting" when handwritten notes contain document text, Chinese or English labels, and multi-line formulas
6. Copy LaTeX directly or insert it back into the main editor

The main window includes PDF recognition and a separate bilingual reading tool:

1. Use "PDF Recognition" to select page count, output format, and render DPI
2. Built-in MathCraft PDF recognition uses mixed mode for text and formula recovery
3. External PDF recognition supports OpenAI-compatible, Ollama, and MinerU providers
4. Save editable Markdown or LaTeX results from the PDF result window
5. Use "Bilingual Reading" to open a text-layer PDF, view the current page, and translate with Argos, Azure, Google Cloud, or DeepL

The workbench currently covers common scenarios such as:

• Polynomial expansion
• Factorization
• Equation solving
• Irrational/complex root fallback solving
• Definite and improper integrals
• Infinite series
• Infinite products
• Limits
• Derivatives
• Numeric approximation and constant recognition

For heavy expressions, the engine uses automatic fallback:

1. Try frontend Compute Engine first
2. Switch to local advanced engine on timeout/failure/unreliable results
3. Use SymPy/mpmath for robust fallback
4. Recover closed forms for selected known constants from numeric output

LaTeXSnipper exposes a shared export menu in the main window and favorites window.

Built-in formula export formats:

• LaTeX inline, display, and equation
• Markdown inline and block math
• MathML standard, .mml, <m>, and attribute forms
• HTML, Word OMML, and SVG code

Optional Pandoc export formats are enabled after installing the PANDOC layer in the dependency wizard:

• Word .docx, ODT .odt, EPUB .epub, InDesign .icml
• RTF, plain text, standalone HTML, LaTeX .tex, Typst .typ
• GitHub Markdown, CommonMark, reStructuredText
• MediaWiki, DokuWiki, Org-mode, Textile, Jira Wiki, and man page output

Pandoc is optional. If it is not installed, the core recognition, editing, handwriting, preview, and built-in export formats continue to work normally.

1. Visit the Releases page
2. Download the latest LaTeXSnipperSetup-<version>.exe
3. Run the installer
4. Complete environment setup via the dependency wizard on first launch
5. Start capturing, handwriting, or using the math workbench

Windows:

git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
cd LaTeXSnipper

python -m venv .venv
.\.venv\Scripts\activate

pip install -r requirements.txt
python src/main.py

Linux:

git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
cd LaTeXSnipper

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements-linux.txt
python src/main.py

macOS:

git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
cd LaTeXSnipper

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements-macos.txt
python src/main.py

Close/background behavior follows each desktop platform. Windows hides the main window to the system tray when it is closed. Linux does the same when a system tray is available, and asks before exiting if no tray is available. macOS keeps the app running when the main window is closed/minimized; Dock or menu Quit is the explicit exit path. The macOS global hotkey uses Carbon and normally does not require Accessibility permission, while screenshot capture requires Screen Recording permission.

The dependency wizard manages Python dependency layers only. It does not install or uninstall system packages. On Linux, tools such as grim, maim, and gnome-screenshot can improve screenshot fallback behavior, but they are installed by the user or distribution package manager, not by LaTeXSnipper. The default screenshot shortcut is Ctrl+F on all three platforms. The shortcut setting currently accepts Ctrl+letter and Ctrl+Shift+letter combinations so custom shortcuts remain inside the cross-platform supported set. Linux global shortcuts are still subject to desktop environment and Wayland compositor policy. Linux and macOS both create optional runtime dependency environments in the user state directory, so they need a usable system Python 3.10+ with venv/pip support. Debian/Ubuntu .deb installs declare python3 and python3-venv; macOS users should install Python through Homebrew (brew install python) or the official python.org macOS installer when the system does not provide a usable python3. The dependency wizard shows its UI before running ensurepip, pip upgrade, or setuptools/wheel repair; those steps run after the user starts dependency installation.

Windows packaging:

• LaTeXSnipper.spec
• Inno/latexsnipper.iss
• scripts/build_store_msix.ps1

Linux packaging:

• LaTeXSnipper-linux.spec
• scripts/build_deb.sh
• packaging/debian/

macOS packaging:

• LaTeXSnipper-macos.spec
• scripts/build_macos.sh

Linux/macOS build scripts prepare isolated, platform-scoped build runtimes under tools/deps/, for example tools/deps/python311-linux-x86_64. The Windows IDE interpreter is tools/deps/python311. The repository-root python311 directory is treated as a template runtime and must not be mutated by packaging scripts.

GitHub Actions release builds run the platform package jobs in one workflow:

• Windows: Inno installer; SignPath-signed artifact is preferred, with an unsigned fallback when signing is unavailable.
• Linux: Debian/Ubuntu .deb package from scripts/build_deb.sh.
• macOS: .app.zip and .dmg artifacts from scripts/build_macos.sh.

The release workflow expects these GitHub Actions variables: SIGNPATH_ORGANIZATION_ID, SIGNPATH_PROJECT_SLUG, SIGNPATH_SIGNING_POLICY_SLUG, and SIGNPATH_ARTIFACT_CONFIGURATION_SLUG. It also requires the SIGNPATH_API_TOKEN secret. The SignPath artifact configuration is mirrored in .signpath/artifact-configurations/windows-installer.xml; copy that XML into the matching SignPath project artifact configuration.

LaTeXSnipper/
|-- mathcraft_ocr/                 # Standalone MathCraft OCR runtime and CLI
|-- src/
|   |-- main.py                    # Main desktop application entry
|   |-- backend/                   # OCR wrapper, CUDA diagnostics, capture, platform services
|   |-- bootstrap/                 # Dependency wizard and runtime verification
|   |-- capture/                   # Screenshot capture controllers
|   |-- core/                      # Document composition, export contracts, restart contracts
|   |-- cross_platform/            # OS-specific screenshot and platform helpers
|   |-- editor/                    # Math workbench and formula editing UI
|   |-- exporting/                 # Formula, Markdown, Pandoc, and document export helpers
|   |-- handwriting/               # Handwriting canvas, PDF preview, document tools
|   |-- preview/                   # MathJax preview and render helpers
|   |-- recognition/               # OCR and PDF recognition controllers
|   |-- runtime/                   # Startup, config, history, logging, distribution, runtime helpers
|   |-- ui/                        # Main window, settings, dialogs, and UI controllers
|   |-- update/                    # GitHub release update checks and installer launch flow
|   |-- workers/                   # Background worker helpers
|   `-- assets/                    # Icons and bundled web/math resources
|-- tools/
|   `-- deps/                      # Local developer/build dependency environment
|-- user_manual/                   # Local manual source and generated PDF
|-- Inno/                          # GitHub Release installer scripts
|-- packaging/                     # Debian and MSIX packaging resources
|-- scripts/                       # Build, release, and regression utilities
|-- docs/                          # Design and architecture notes
|-- LaTeXSnipper.spec              # PyInstaller GitHub build (Windows)
|-- LaTeXSnipper-linux.spec        # PyInstaller Linux build
|-- LaTeXSnipper-macos.spec        # PyInstaller macOS build
|-- pyproject.toml
|-- requirements.txt
|-- requirements-linux.txt
|-- requirements-macos.txt
|-- requirements-build.txt
|-- version_info.txt
`-- README.md

Contributions are welcome:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push your branch
5. Open a Pull Request

All pull requests must follow Developer Code Standards. Before requesting review, run:

.\tools\deps\python311\python.exe -m ruff check .
.\tools\deps\python311\python.exe -m pytest test
.\tools\deps\python311\python.exe -m pyright
.\tools\deps\python311\python.exe -m compileall -q src mathcraft_ocr test

Cross-platform PRs must not change the Windows dependency surface or installer behavior unless Windows is explicitly in scope and separately validated.

Recommended focus areas:

• Handwriting UX
• Math workbench UX
• Advanced solver stability
• Packaged runtime verification
• Theme consistency across windows

This project is open-sourced under the MIT License.

Special thanks to:

• pix2tex
• MathLive
• MathLive Compute Engine
• SymPy
• mpmath
• MathJax
• PyQt6
• QFluentWidgets