diff --git a/README.md b/README.md index 2ae3ec9..1fc4ad3 100755 --- a/README.md +++ b/README.md @@ -1,107 +1,178 @@ +
+ # SwiftMath -`SwiftMath` provides a full Swift implementation of [iosMath](https://travis-ci.org/kostub/iosMath) -for displaying beautifully rendered math equations in iOS and MacOS applications. It typesets formulae written -using LaTeX in a `UILabel` equivalent class. It uses the same typesetting rules as LaTeX and -so the equations are rendered exactly as LaTeX would render them. +### Beautiful LaTeX Math Rendering for iOS, macOS & visionOS + +[![Swift Version](https://img.shields.io/badge/Swift-5.0+-orange.svg)](https://swift.org) +[![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20macOS%20%7C%20visionOS-lightgrey.svg)](https://github.com/mgriebling/SwiftMath) +[![SPM Compatible](https://img.shields.io/badge/SPM-compatible-brightgreen.svg)](https://swift.org/package-manager/) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Examples](#-examples) • [Fonts](#-fonts) • [Demo](#-demo) + +
+ +--- + +## 📖 Overview + +**SwiftMath** is a full Swift implementation of [iosMath](https://github.com/kostub/iosMath) for displaying beautifully rendered math equations in native iOS, macOS, and visionOS applications. It typesets formulae written in **LaTeX** using the same rules as LaTeX itself, ensuring pixel-perfect mathematical typography. + +### Why SwiftMath? -Please also check out [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo.git) for examples of how to use `SwiftMath` -from SwiftUI. +- ✨ **Native Performance** - Significantly faster than `UIWebView` or `WKWebView` based solutions +- 🎯 **LaTeX Compatible** - Renders equations exactly as LaTeX would +- 📦 **Zero Dependencies** - No need for MathJax, KaTeX, or JavaScript +- 🎨 **SwiftUI Ready** - Easy integration with modern Swift frameworks +- 🌍 **Multi-Platform** - Works seamlessly on iOS 11+, macOS 12+, and visionOS -`SwiftMath` is similar to [MathJax](https://www.mathjax.org) or -[KaTeX](https://github.com/Khan/KaTeX) for the web but for native iOS or MacOS -applications without having to use a `UIWebView` and Javascript. More -importantly, it is significantly faster than using a `UIWebView`. +> Think of it as **MathJax** or **KaTeX** for native Apple platforms, but faster! -`SwiftMath` is a Swift translation of the latest `iosMath` v0.9.5 release but includes bug fixes -and enhancements like a new \lbar (lambda bar) character and cyrillic alphabet support. -The original `iosMath` test suites have also been translated to Swift and run without errors. -Note: Error test conditions are ignored to avoid tagging everything with silly `throw`s. -Please let me know of any bugs or bug fixes that you find. +Check out [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo.git) for SwiftUI examples. -`SwiftMath` prepackages everything needed for direct access via the Swift Package Manager. +--- -## Examples -Here are screenshots of some formulae that were rendered with this library: +## ✨ Features -```LaTeX + + + + + +
+ +### Core Capabilities +- ✓ Algebraic equations +- ✓ Fractions & continued fractions +- ✓ Exponents & subscripts +- ✓ Trigonometric formulae +- ✓ Roots (square & n-th) +- ✓ Calculus symbols (limits, derivatives, integrals) +- ✓ Big operators (sum, product, etc.) +- ✓ Big delimiters (`\left`, `\right`) +- ✓ Greek alphabet & Cyrillic support + + + +### Advanced Features +- ✓ Matrices & equation alignment +- ✓ Combinatorics (`\binom`, `\choose`) +- ✓ Geometry symbols +- ✓ Math accents, overline & underline +- ✓ Font styles (`\bf`, `\text`, `\mathcal`, etc.) +- ✓ Text & background colors +- ✓ Custom commands (LaTeX macros) +- ✓ **12 beautiful math fonts included** + +
+ +--- + +## 🎨 Examples + +### Quadratic Formula +```latex x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} ``` -![Quadratic Formula](img/quadratic-light.png#gh-light-mode-only) -![Quadratic Formula](img/quadratic-dark.png#gh-dark-mode-only) +![Quadratic Formula](img/quadratic-light.png#gh-light-mode-only) +![Quadratic Formula](img/quadratic-dark.png#gh-dark-mode-only) -```LaTeX +### Fourier Transform +```latex f(x) = \int\limits_{-\infty}^\infty\!\hat f(\xi)\,e^{2 \pi i \xi x}\,\mathrm{d}\xi ``` -![Calculus](img/calculus-light.png#gh-light-mode-only) -![Calculus](img/calculus-dark.png#gh-dark-mode-only) +![Calculus](img/calculus-light.png#gh-light-mode-only) +![Calculus](img/calculus-dark.png#gh-dark-mode-only) -```LaTeX +### AM-GM Inequality +```latex \frac{1}{n}\sum_{i=1}^{n}x_i \geq \sqrt[n]{\prod_{i=1}^{n}x_i} ``` -![AM-GM](img/amgm-light.png#gh-light-mode-only) -![AM-GM](img/amgm-dark.png#gh-dark-mode-only) +![AM-GM](img/amgm-light.png#gh-light-mode-only) +![AM-GM](img/amgm-dark.png#gh-dark-mode-only) -```LaTex -\frac{1}{\left(\sqrt{\phi \sqrt{5}}-\phi\\right) e^{\frac25 \pi}} +### Ramanujan's Identity +```latex +\frac{1}{\left(\sqrt{\phi \sqrt{5}}-\phi\right) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1 +\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots} } } } ``` -![Ramanujan Identity](img/ramanujan-light.png#gh-light-mode-only) -![Ramanujan Identity](img/ramanujan-dark.png#gh-dark-mode-only) +![Ramanujan Identity](img/ramanujan-light.png#gh-light-mode-only) +![Ramanujan Identity](img/ramanujan-dark.png#gh-dark-mode-only) + +> 📚 **More examples:** See [EXAMPLES.md](EXAMPLES.md) for additional formula demonstrations -More examples are included in [EXAMPLES](EXAMPLES.md) +--- -## Fonts -Here are previews of the included fonts: +## 🎭 Fonts -![](img/FontsPreview.png#gh-dark-mode-only) -![](img/FontsPreviewLight.png#gh-light-mode-only) - -## Requirements -`SwiftMath` works on iOS 11+ or MacOS 12+. It depends -on the following Apple frameworks: +SwiftMath includes **12 professionally crafted math fonts**: -* Foundation.framework -* CoreGraphics.framework -* QuartzCore.framework -* CoreText.framework +![Font Preview Dark](img/FontsPreview.png#gh-dark-mode-only) +![Font Preview Light](img/FontsPreviewLight.png#gh-light-mode-only) -Additionally for iOS it requires: -* UIKit.framework +**Default:** Latin Modern Math | **Also includes:** XITS Math, TeX Gyre Termes, and more! -Additionally for MacOS it requires: -* AppKit.framework +> 💡 You can use any OTF math font with SwiftMath. A Python script is included to generate the necessary `.plist` files. -## Installation +--- -### Swift Package +## 📦 Installation -`SwiftMath` is available from [SwiftMath](https://github.com/mgriebling/SwiftMath.git). -To use it in your code, just add the https://github.com/mgriebling/SwiftMath.git path to -XCode's package manager. +### Swift Package Manager -## Usage +Add SwiftMath to your project via Xcode: -The library provides a class `MTMathUILabel` which is a `UIView` that -supports rendering math equations. To display an equation simply create -an `MTMathUILabel` as follows: +1. **File** → **Add Packages...** +2. Enter the repository URL: + ``` + https://github.com/mgriebling/SwiftMath.git + ``` +3. Click **Add Package** + +Or add to your `Package.swift`: ```swift +dependencies: [ + .package(url: "https://github.com/mgriebling/SwiftMath.git", from: "1.0.0") +] +``` + +### Requirements + +| Platform | Minimum Version | +|----------|----------------| +| iOS | 11.0+ | +| macOS | 12.0+ | +| visionOS | 1.0+ | + +**Frameworks:** +- Foundation +- CoreGraphics +- QuartzCore +- CoreText +- UIKit (iOS/visionOS) or AppKit (macOS) + +--- + +## 🚀 Usage + +### Basic UIKit Example +```swift import SwiftMath let label = MTMathUILabel() label.latex = "x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}" - ``` -Adding `MTMathUILabel` as a sub-view of your `UIView` will render the -quadratic formula example shown above. -The following code creates a SwiftUI component called `MathView` encapsulating the MTMathUILabel: +Add the label to your view hierarchy, and you're done! + +### SwiftUI Integration (iOS) ```swift import SwiftUI @@ -114,11 +185,12 @@ struct MathView: UIViewRepresentable { var fontSize: CGFloat = 30 var labelMode: MTMathUILabelMode = .text var insets: MTEdgeInsets = MTEdgeInsets() - + func makeUIView(context: Context) -> MTMathUILabel { let view = MTMathUILabel() return view } + func updateUIView(_ view: MTMathUILabel, context: Context) { view.latex = equation view.font = MTFontManager().font(withName: font.rawValue, size: fontSize) @@ -130,7 +202,7 @@ struct MathView: UIViewRepresentable { } ``` -For code that works with SwiftUI running natively under MacOS use the following: +### SwiftUI Integration (macOS) ```swift import SwiftUI @@ -143,12 +215,12 @@ struct MathView: NSViewRepresentable { var fontSize: CGFloat = 30 var labelMode: MTMathUILabelMode = .text var insets: MTEdgeInsets = MTEdgeInsets() - + func makeNSView(context: Context) -> MTMathUILabel { let view = MTMathUILabel() return view } - + func updateNSView(_ view: MTMathUILabel, context: Context) { view.latex = equation view.font = MTFontManager().font(withName: font.rawValue, size: fontSize) @@ -160,163 +232,139 @@ struct MathView: NSViewRepresentable { } ``` -### Included Features -This is a list of formula types that the library currently supports: - -* Simple algebraic equations -* Fractions and continued fractions -* Exponents and subscripts -* Trigonometric formulae -* Square roots and n-th roots -* Calculus symbos - limits, derivatives, integrals -* Big operators (e.g. product, sum) -* Big delimiters (using \\left and \\right) -* Greek alphabet -* Combinatorics (\\binom, \\choose etc.) -* Geometry symbols (e.g. angle, congruence etc.) -* Ratios, proportions, percentages -* Math spacing -* Overline and underline -* Math accents -* Matrices -* Equation alignment -* Change bold, roman, caligraphic and other font styles (\\bf, \\text, etc.) -* Most commonly used math symbols -* Colors for both text and background - -Note: SwiftMath only supports the commands in LaTeX's math mode. There is -also no language support for other than west European langugages and some -Cyrillic characters. There would be two ways to support more languages: - -1) Find a math font compatible with `SwiftMath` that contains all the glyphs -for that language. -2) Add support to `SwiftMath` for standard Unicode fonts that contain all -langauge glyphs. - -Of these two, the first is much easier. However, if you want a challenge, -try to tackle the second option. - -### Example - -The [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo) is a SwiftUI version -of the Objective-C demo included in `iosMath` that uses `SwiftMath` as a Swift package dependency. - -### Advanced configuration - -`MTMathUILabel` supports some advanced configuration options: - -##### Math mode - -You can change the mode of the `MTMathUILabel` between Display Mode -(equivalent to `$$` or `\[` in LaTeX) and Text Mode (equivalent to `$` -or `\(` in LaTeX). The default style is Display. To switch to Text -simply: +--- + +## ⚙️ Configuration + +### Math Display Modes ```swift +// Display mode (equivalent to $$ or \[ in LaTeX) +label.labelMode = .display + +// Text mode (equivalent to $ or \( in LaTeX) label.labelMode = .text ``` -##### Text Alignment -The default alignment of the equations is left. This can be changed to -center or right as follows: +### Text Alignment ```swift +label.textAlignment = .left // Default label.textAlignment = .center +label.textAlignment = .right ``` -##### Font size -The default font-size is 30pt. You can change it as follows: +### Font Customization ```swift +// Change font size label.fontSize = 25 + +// Change font family +label.font = MTFontManager.fontmanager.termesFont(withSize: 20) ``` -##### Font -The default font is *Latin Modern Math*. This can be changed as: + +### Colors ```swift -label.font = MTFontManager.fontmanager.termesFont(withSize:20) -``` +// Change text color +label.textColor = .red -This project has 12 fonts bundled with it, but you can use any OTF math -font. A python script is included that generates the `.plist` files -required for an `.otf` font to work with `SwiftMath`. If you generate -(and test) any other fonts please contribute them back to this project for -others to benefit. +// Or set colors for specific parts via displayList +// Access displayList and modify individual display elements +``` +### Content Insets +```swift +label.contentInsets = UIEdgeInsets(top: 0, left: 10, bottom: 0, right: 20) +``` -Note: The `KpMath-Light`, `KpMath-Sans`, `Asana` fonts currently incorrectly -render very large radicals. It appears that the font files do -not properly define the offsets required to typeset these glyphs. If -anyone can fix this, it would be greatly appreciated. +### Custom LaTeX Commands -##### Text Color -The default color of the rendered equation is black. You can change -it to any other color as follows: +Define your own macros: ```swift -label.textColor = .red +MTMathAtomFactory.addLatexSymbol("lcm", + value: MTMathAtomFactory.operator(withName: "lcm", limits: false)) ``` -It is also possible to set different colors for different parts of the -equation. Just access the `displayList` field and set the `textColor` -of the underlying displays of which you want to change the color. +Now you can use `\lcm` in your LaTeX! -##### Custom Commands -You can define your own commands that are not already predefined. This is -similar to macros is LaTeX. To define your own command use: +### Error Handling ```swift -MTMathAtomFactory.addLatexSymbol("lcm", value: MTMathAtomFactory.operator(withName: "lcm", limits: false)) +// Check for errors +if let error = label.error { + print("LaTeX error: \(error)") +} + +// Hide inline error display +label.displayErrorInline = false ``` -This creates an `\lcm` command that can be used in the LaTeX. +--- -##### Content Insets -The `MTMathUILabel` has `contentInsets` for finer control of placement of the -equation in relation to the view. +## 🎮 Demo -If you need to set it you can do as follows: +The [**SwiftMathDemo**](https://github.com/mgriebling/SwiftMathDemo) project showcases SwiftMath in action with SwiftUI. It's a complete rewrite of the original iosMath demo using modern Swift and SwiftUI patterns. -```swift -label.contentInsets = UIEdgeInsets(top: 0, left: 10, bottom: 0, right: 20) -``` +--- -##### Error handling +## 🗺️ Roadmap -If the LaTeX text given to `MTMathUILabel` is -invalid or if it contains commands that aren't currently supported then -an error message will be displayed instead of the label. +Future enhancements planned: -This error can be programmatically retrieved as `label.error`. If you -prefer not to display anything then set: +- [ ] Support for explicit big delimiters (`\bigl`, `\bigr`, etc.) +- [ ] Additional plain TeX commands +- [ ] Extended language support beyond Western European and Cyrillic -```swift -label.displayErrorInline = true -``` +--- + +## 🤝 Contributing + +Contributions are welcome! If you: + +- Generate and test new font `.plist` files +- Fix font rendering issues (especially KpMath-Light, KpMath-Sans, Asana radicals) +- Discover and fix bugs +- Add new features + +Please submit a pull request or open an issue! + +--- + +## 📄 License + +SwiftMath is available under the **MIT License**. See [LICENSE](./LICENSE) for details. + +### Font Licenses + +Included fonts are licensed as follows: + +| Font | License | +|------|---------| +| Latin Modern Math | [GUST Font License](GUST-FONT-LICENSE.txt) | +| TeX Gyre Termes | [GUST Font License](GUST-FONT-LICENSE.txt) | +| [XITS Math](https://github.com/khaledhosny/xits-math) | [Open Font License](OFL.txt) | +| KpMath Light/Sans | [SIL Open Font License](OFL.txt) | + +--- + +## 🙏 Acknowledgments -## Future Enhancements +SwiftMath is a Swift translation of [iosMath](https://github.com/kostub/iosMath) v0.9.5, with additional bug fixes and enhancements including: +- Lambda bar (`\lbar`) character support +- Cyrillic alphabet support +- visionOS compatibility +- Various bug fixes and improvements -Note this is not a complete implementation of LaTeX math mode. There are -some important pieces that are missing and will be included in future -updates. This includes: +--- -* Support for explicit big delimiters (bigl, bigr etc.) -* Addition of missing plain TeX commands +
-## License +**Made with ❤️ for the Swift community** -`SwiftMath` is available under the MIT license. See the [LICENSE](./LICENSE) -file for more info. +[⭐ Star this repo](https://github.com/mgriebling/SwiftMath) • [🐛 Report a bug](https://github.com/mgriebling/SwiftMath/issues) • [💡 Request a feature](https://github.com/mgriebling/SwiftMath/issues) -### Fonts -This distribution contains the following fonts. These fonts are -licensed as follows: -* Latin Modern Math: - [GUST Font License](GUST-FONT-LICENSE.txt) -* Tex Gyre Termes: - [GUST Font License](GUST-FONT-LICENSE.txt) -* [XITS Math](https://github.com/khaledhosny/xits-math): - [Open Font License](OFL.txt) -* [KpMath Light/KpMath Sans](http://scripts.sil.org/OFL): - [SIL Open Font License](OFL.txt) +