It is a dynamic, cross-platform, and embeddable LaTeX rendering library. Its main purpose is to display mathematical formulas written in LaTeX. It can be embedded in applications on various platforms (Android, iOS, Windows, Linux GTK, Qt...). The following pictures demonstrate the application run in Ubuntu (using GTK) and Windows.
Here contains more demos you may want to take a look.
Build demo
First make sure you have a C++ compiler that supports C++ 17 standard. It uses CMake to build the demo, make sure you have it installed. Currently support Windows and Linux on PC, the version on Mac OS is in the plan, and you can find the Android version in here.
CygWin or MinGW is recommended to be installed on Windows, and Gdiplus is required.
GTKMM and GSVMM must be installed on Linux for a GTK build.
Qt development packages must be installed for a Qt installation.
After all the dependencies have been satisfied, run the following commands to build:
cd your/project/dir
mkdir build
cd build
cmake ..
make -j32
After all the works have done, run the executable file LaTeX in the directory build to check the demo.
If you wish to build in Qt mode on your plaform add -DQT=ON to the cmake command above.
Headless mode
It supports to run with headless mode (no GUI) on Linux OS, check the scripts below to learn how to do this.
./LaTeX -headless \
"-input=\sqrt[3]{(x-y)^3}=x-y" \
-output=an_example.svg
# other options...
COMMON OPTIONS
-h: show usages and exit
-headless: tells the application to run with the headless mode, that converts the input LaTeX codes into SVG images
-textsize: config the font size (in point) to display formulas, the default is 20
-foreground: config the foreground color to display formulas; the value can be a color name or in the form of #AARRGGBB; default is black
-background: config the background color to display formulas; the value can be a color name or in the form of #AARRGGBB; default is transparent
-padding: config spaces to add to the SVG images, the default is 10
-maxwidth: config the max width of the graphics context, the default is 720 pixels; this option has weak limits on the SVG images, thus the width of the SVG image may be wider than the value defined by this option
BATCH MODE OPTIONS
The program will save the SVG images produced by the LaTeX codes that parsed from the given file (specified by the option '-samples') into the directory specified by the option '-outputdir'.
-outputdir: indicates the directory to save the SVG images
-samples: specifies the file that contains several LaTeX codes split by a line that consists of the character '%' only, the default is './res/SAMPLES.tex'; check this file to get more details
-prefix: specifies the prefix of the filename of the SVG images, the default is ''; for example if 2 pieces of code have given with the option '-prefix=a_', the filename of the SVG images will be 'a_0.svg' and 'a_1.svg'
SINGLE MODE OPTIONS
-input: the source code that is written in LaTeX
-output: indicates where to save the produced SVG image, only works if the option '-input' has given
NOTICE
If both '-outputdir' and '-input' are specified, the '-input' option wins. Run the command ./LaTeX -h to get helps.
The program can be built just fine using the default compilation options. However, if required, the options documented below can be used to omit some features (that can reduce the library size) and to check memory only.
HAVE_LOG
If HAVE_LOG is defined, the program will output some logs (e.g.: the symbols parse result, generated box tree and so on) during runtime to help us to find out if there're issues or bugs, the default is ON. The option will be disabled when building with release mode, you can set it to OFF manually to make double insurance. For example, when parsing the following LaTeX code with the option is defined:
If this macro is defined, then the custom command \debug and \undebug will be compiled, the default is ON. The program will draw some assisted information to help us to check if there're issues when draw formulas after run \debug, and \undebug will close this feature. For example, parse the LaTeX code below:
The red blocks represent the depth of the boxes, and these rectangles represent the boxes' bounds.
MEM_CHECK
Basically, the program implemented an empty graphics interface (check this file), all the other implementations will be ignored if the MEM_CHECK option is defined, the default is OFF. It is useful when using valgrind to detect memory leaks and memory misuse, make sure you have compiled it with the option -DCMAKE_BUILD_TYPE=Debug before using valgrind. The following script shows how to do memory check using valgrind.
==26443== HEAP SUMMARY:
==26443== in use at exit: 72,704 bytes in 1 blocks
==26443== total heap usage: 84,520 allocs, 84,519 frees, 12,515,092 bytes allocated
==26443==
==26443== Searching for pointers to 1 not-freed blocks
==26443== Checked 111,952 bytes
==26443==
==26443== LEAK SUMMARY:
==26443== definitely lost: 0 bytes in 0 blocks
==26443== indirectly lost: 0 bytes in 0 blocks
==26443== possibly lost: 0 bytes in 0 blocks
==26443== still reachable: 72,704 bytes in 1 blocks
==26443== suppressed: 0 bytes in 0 blocks
==26443== Reachable blocks (those to which a pointer was found) are not shown.
==26443== To see them, rerun with: --leak-check=full --show-leak-kinds=all
==26443==
==26443== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)
Meson build manifest
You can also build the cairo version of cLaTeXMath with Meson:
meson _build -DTARGET_DEMO=NONE # you can specify TARGET_DEMO=GTK if you want a GTK+ GUI to test cLaTeXMath, otherwise only the library (TARGET_DEVEL) will be built.
ninja -C _build
_build/clatexmath
Prebuilt packages
@sp1ritCS maintains more or less upto date packages of cLaTeXMath/cairo for Arch, CentOS, Debian, Fedora, Mageia, SLE, openSUSE & Ubuntu on the openSUSE Buildservice: home:sp1rit:notekit/clatexmath.
If you just want to use cLaTeXMath for your GTK/Cairo project, this may be best way to get started.
How to use
This section shows how to use this library to display mathematical formulas.
First, load the required resources at the very beginning:
#include"latex.h"usingnamespacetex;/** * Initialize the program with the default parameter (directory * path of the resources) value "res" to load required resources, * that may take a long time, you may call it from a background * thread. * * Also, you can use the code below to specifies your custom * resources directory: * * LaTex::init("your/resources/root/directory");*/LaTeX::init();
// After initialization, you could display your formulas now
You could set the point size (pixels per point) use the code below:
/** * Set the point size; the default value is 1 that means * use 1 pixel to represent 1 point.*/
TeXFormula::PIXELS_PER_POINT = 2;
Also, you could set the DPI (dots per inch) use the code below:
/** * For example, set the DPI-target to 74, the point size * will be 74/72*/TeXFormula::setDPITarget(74);
Write the code below to release resources before application exit, it is not necessary but is a good habit.
// ... some other code ...// before application exitLaTeX::release();
Display mathematical formulas
General mode:
// ... initialization .../** * The LaTeX code to parse. * * The program uses wide string to represent UTF characters, you * could use the code below to convert a string with UTF-8 encoding * to a wide string: * * wstring wstr = utf82wide("A string with UTF-8 encoding.");*/
wstring code = L"\\int_{now}^{+\\infty} \\text{Keep trying}";
// Convert the code to a paintable object (TeXRender)auto r = LaTeX::parse(
code, // LaTeX code to parse720, // logical width of the graphics context (in pixel)20, // font size (in point)10, // space between 2 lines (in pixel)
BLACK // foreground color
);
Builder mode:
wstring code = L"\\int_{now}^{+\\infty} \\text{Keep trying}";
TeXFormula formula;
TeXRenderBuilder builder;
formula.setLaTeX(code);
auto r = builder
// environment style, see TeXConstants (defined in common.h) to// get more details
.setStyle(STYLE_DISPLAY)
// text size (in point)
.setSize(20)
// the logical width and the alignment of the graphics context
.setWidth(UnitType::pixel, 720, Alignment::left)
// set if the logical width of the graphics context specified// above is the max width to display the formula, the formula// will be centered if set to true; you must call this method// after 'setWidth' has called, otherwise an ex_invalid_state // exception will be thrown
.setIsMaxWidth(false)
// space between 2 lines
.setLineSpace(UnitType::pixel, 10)
.setForground(tex::BLACK)
// convert the formula to a paintable object (TeXRender)
.build(formula);
NOTICE
A style and text size are required to build a TeXRender, in another word, you must call method setStyle and setSize before method build has been called, otherwise an ex_invalid_state exception will be thrown. If the logical width has not set, the generated TeXRender may be wide enough to overflow into the graphics context.
Now you can draw the generated TeXRender (take Graphics2D_cairo that uses cairomm to implement the graphics (2D) context that run in Linux as an example):
// cairomm implementation
Graphics2D_cairo g2;
// draw the formula on the coordinate (10, 10) of the graphics context
r->draw(10, 10);
// IMPORTANT: remember to delete the generated TeXRender after there// is no use on it.delete r;
The code above will produce:
Implement the graphical interfaces
Basically, you need to implement all the interfaces declared in this file. There're 4 implementations list below, check it out before the start.
graphic_cairo: that uses cairomm and gtkmm to implement these interfaces that run in Linux, declared in here, and implemented here.
graphic_win32: is a Windows implementation that uses gdiplus to implement these interfaces, please check here and here.
And implementations on Android OS can be found at here.
And the empty implementations to perform memory check are defined in here.
The following sections illustrate these interfaces.
tex::Font
This interface represents a font (typeface). The program uses it to draw characters and layout boxes. The code below shows how to implement this interface with the name Font_impl.
#include"graphic/graphic.h"namespacetex {
classFont_impl : publictex::Font {
public:Font_impl(const string& file, float size) {
// load platform-specific font from given file and size
}
Font_impl(const string& name, int style, float size) {
// create platform-specific font with given name, style// and size
}
// ... implementations of the other methods ...
};
/** * IMPORTANT: do not forget to implement the 2 static methods below, * it is the factory methods to create a new font.*/
Font* Font::create(const string& file, float size) {
returnnewFont_impl(file, size);
}
sptr<Font> Font::_create(const string& name, int style, float size) {
return sptrOf<Font_impl>(name, style, size);
}
} // namespace tex
tex::TextLayout
An alphabet contains several Unicode-blocks on a Basic Multilingual Plane (BMP), check here for more information.
For these characters in unregistered alphabets, the library uses tex::TextLayout to layout it. For example, parse the following LaTeX code:
\int_{now}^{\infty} \text{努力}
The character "努" and "力" are under the Unicode-block CJK Unified Ideographs belongs to the alphabet CJK that has not registered with the program, it will use the implementation of the class tex::TextLayout to layout the text "努力" and calculate the layout bounds. The tex::TextLayout_cairo implementation (declared in here) demonstrates how to do this.
The LaTeX code above will produce:
The predefined Unicode-blocks are list below, check this file for more details.
Write the code below to register a new alphabet with the program:
classNewAlphabetRegistration : publicAlphabetRegistration {
private:
vector<UnicodeBlock> _blocks;
public:NewAlphabetRegistration(const vector<UnicodeBlock>& blocks)
:_blocks(blocks) {}
const vector<UnicodeBlock>& getUnicodeBlock() constoverride {
return _blocks;
}
const string getPackage() constoverride {
// the root directory path of the font-mapping and// symbols-mapping for this alphabet
}
const string getTeXFontFile() constoverride {
// language settings (a xml file) for this alphabet
}
};
// ... some other code ...// Define a new Unicode-blockauto newBlock = UnicodeBlock::define(
newAlphabetCodePointStart,
newAlphabetCodePointEnd);
// Register the new alphabetDefaultTeXFont::registerAlphabet(new NewAlphabetRegistration({newBlock});
tex::Graphics2D
This interface defines a 2D graphics context, all the TeX drawing operations will on it. It declares various basic 2D graphics operations, including affine transformations and meta graphical operations. The class Graphics2D_cairo (defined in this file) uses cariomm to implement this interface, take it a look to learn how to achieve it. It is the most important part of the graphical environment, and also very simple, all you need to do is wrap these functions on a specific platform into the form of this interface declared. This file declares some built-in colors and various entity classes to support the graphical environment.
Custom commands and symbols
\debug and \undebug
As mentioned above, the command \debug and \undebug is used to switch graphical debug mode on/off, please check it out.
\fatalIfCmdConflict
This command takes a boolean argument to determine whether to raise an error that when defining a new command but it has defined already or redefining a command but it has not defined. The default value is true. The script below shows how to use it.
\fatalIfCmdConflict{true}
% define a new command with the name R\newcommand{\R}{\mathbb{R}}
\R% here will cause the program throws an error% use \fatalIfCmdConflict{false} to disable it\newcommand{\R}{\mathcal{R}}
\breakEverywhere
This command takes a boolean argument, the predefined value is false. Its functionality is hard to describe, an example worths thousands of words, the examples below show the difference between when it set to true and false.
\text{What is real? How do you define ‘real’? If you're talking about what you can feel, what you can smell, what you can taste and see, then ‘real’ is simply electrical signals interpreted by your brain. \bold{\text{― Morpheus The Matrix}}}
When with \breakEverywhere{false}, the result will be:
And with \breakEverywhere{true}, the result will be:
NOTICE
The program has a weak ability to handle line feeds when laying out texts, you should try to avoid using it to lay out large amounts of text, delegate these tasks to the text-layout system, and use this program to display formulas is a good choice.
\TeX and \AndroidTeX
The logo and the logo of the Android version are produced by the command \TeX and \AndroidTeX, take a quick look:
\TeX\\\AndroidTeX
Custom symbols
There're 4 custom symbols in the script below:
AB \varparallel CD
AB \nvarparallel CD
AB \varparalleleq CD
\parallelogram ABCD
that will produce:
TODO
port Gtk+ 3 to Windows and macOS
buitin resources
support for webassembly
native support for SVG
make the use of XML configurable
make the built-in resources a loadable/unloadable dynamic plugin
eliminate the use of 'dynamic_cast'
rewrite the parsing algorithm, make it more efficient
support for dynamic parsing
implement the \def command
License
Excluding the fonts and xml resources (under the directory res) that under different licenses (check out res/fonts/license, res/greek and res/cyrillic), this project is under the MIT license.
The MIT License (MIT)
Copyright (c) 2020 Nano Michael
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
AUT
请发表评论