DOCSEARCHbyAlgolia
Submit Docs

XAML-Math

repository·master·Indexed 20 days ago

https://github.com/fornever/xaml-math

A collection of .NET libraries for rendering LaTeX-style mathematical formulae within WPF and Avalonia XAML-based frameworks. It provides specialized packages including WpfMath for WPF and AvaloniaMath for Avalonia, along with XamlMath.Shared for framework-independent logic. Features include support for static formula rendering via FormulaControl and FormulaBlock, programmatic PNG and bitmap export using WpfTeXFormulaParser and WpfTeXEnvironment, and extensive LaTeX command support for colors, matrices, and equation alignment.

Tokens
4K
Snippets
16
Records
22
Agent score
72%

What's inside XAML-Math

  1. Color syntax in XAML-Math

    master

    XAML-Math supports LaTeX-style commands for foreground and background colors: \color for foreground and \colorbox for background. Unlike standard LaTeX, XAML-Math allows you to define colors immediately within the command arguments using various modes.

    The general syntax is: \command [mode] {color} {text}

    • command: color or colorbox.
    • mode (optional): Defines how the {color} argument is parsed (e.g., gray, RGB, cmyk, HTML).
    • color: A predefined color name (if no mode is provided) or a color definition matching the specified mode.
    • text: The content to be colored.
    \command [mode] {color} {text}

  2. Understand the XAML-Math Runtime Support Policy

    master

    XAML-Math follows Microsoft's support lifecycle for .NET (both .NET Framework and modern .NET).

    • Supported Runtimes: Generally includes both basic and extended support versions, provided the maintenance cost is reasonable.
    • Deprecation: Support for a runtime version is typically removed once Microsoft stops supporting it or if the maintenance cost becomes unreasonable.
    • Breaking Changes: Removing a .NET runtime version from the list of compatible versions is treated as a breaking change under semantic versioning.

  3. Use environments with \begin and \end

    master
    XAML-Math supports environments to introduce specific context for nested markup. An environment is initiated with \begin{environment-name} and must be closed with a corresponding \end{environment-name}. Environments can be nested within one another.

  4. Use RGB-based modes (RGB, RGBA, ARGB, rgb, rgba, argb)

    master

    XAML-Math provides six RGB-based modes. The distinction between uppercase and lowercase modes determines the expected value range:

    • Uppercase (RGB, RGBA, ARGB): Accepts values from 0 to 255.
    • Lowercase (rgb, rgba, argb): Accepts values from 0.0 to 1.0.

    Opacity placement:

    • ARGB / argb: Opacity is the first value.
    • RGBA / rgba: Opacity is the last value.

    Examples:

    \colorbox[rgb]{0,0,0}{text}
\colorbox[rgba]{0,0,0, 0.5}{opacity = 0.5}
\colorbox[argb]{0.5, 0,0,0}{opacity = 0.5}
\colorbox[RGB]{255,255,255}{text}
\colorbox[RGBA]{255,255,255,128}{opacity = 128}
\colorbox[ARGB]{128, 255,255,255}{opacity = 128}
    \colorbox[rgba]{0,0,0, 0.5}{opacity = 0.5}

  5. Improve blurred formula rendering in FormulaControl

    master

    Because FormulaControl is a WPF control, you can use TextOptions properties to tune how formulas are rendered. While default settings work well for large font sizes, smaller formulas may appear blurred. You can improve sharpness by creating a custom Style for FormulaControl that overrides the text rendering, hinting, and formatting modes.

    To apply these improvements, define a Style in your Window.Resources (or ResourceDictionary) and apply it to your FormulaControl using the Style property.

    <Window ... xmlns:controls="clr-namespace:WpfMath.Controls;assembly=WpfMath">
    <Window.Resources>
        <Style x:Key="ClearTypeFormula" TargetType="controls:FormulaControl">
            <Setter Property="TextOptions.TextRenderingMode" Value="ClearType" />
            <Setter Property="TextOptions.TextHintingMode" Value="Fixed" />
            <Setter Property="TextOptions.TextFormattingMode" Value="Display" />
        </Style>
    </Window.Resources>

    <controls:FormulaControl Formula="\left(x^2 + 2 \cdot x + 2\right) = 0" 
                             Style="{StaticResource ClearTypeFormula}" />
</Window>

  6. Prepare DefaultTexFont.xml using Tool.TTFMetrics

    master

    If you need to generate data for the <Font> section of DefaultTexFont.xml, you can use the WPF-based Tool.TTFMetrics application.

    1. Launch the Tool.TTFMetrics application.
    2. Select your target .ttf font file.
    3. The tool will generate the necessary font information, which you can then paste directly into the <Font> section of your DefaultTexFont.xml file.

  7. Create matrices and matrix-like constructs

    master

    XAML-Math allows you to build grids of items using matrix commands. In these constructs, cells within a row are separated by the & symbol, and rows are separated by either \ or \cr.

    Supported types include:

    • \matrix: A matrix rendered without surrounding brackets.
    • \pmatrix: A matrix rendered within square brackets [].
    • \cases: A matrix-like construct used for piecewise functions and similar mathematical notation.
    % A 2x3 matrix without brackets
\matrix{1 & 2 & 3 \\ 4 & 5 & 6}

% A 2x3 matrix with square brackets
\pmatrix{1 & 2 & 3 \\ 4 & 5 & 6}

  8. Prepare DefaultTexFont.xml using the Manual Approach

    master

    If you prefer a manual approach using standard TeX and FontTools utilities, follow these steps to extract metrics and character data:

    1. Gather Font Metrics

    Use the ttf2tfm and tftopl utilities (available in TeX Live) to convert a TTF file into a readable .tpl format:

    $ ttf2tfm filename.ttf -v filename.vpl
$ tftopl filename.tfm > filename.tpl

    This generates a binary .tfm file and text-based .vpl and .tpl files.

    2. Extract Character Mappings

    Use the ttx utility from the fonttools package to generate an XML representation of the font, which helps map characters to specific codes:

    $ ttx filename.ttf

    3. Map TPL values to XML

    When parsing the .tpl file to populate DefaultTexFont.xml, use the following mapping:

    • XHEIGHT $\rightarrow$ xHeight attribute in <Font>
    • QUAD $\rightarrow$ quad attribute in <Font>
    • SPACE $\rightarrow$ space attribute in <Font>
    • CHARWD $\rightarrow$ width attribute in <Char>
    • CHARHT $\rightarrow$ height attribute in <Char>
    • CHARDP $\rightarrow$ depth (if used)
    • CHARIC $\rightarrow$ italic (if used)
    • Kerning values can be reconstructed from the kerning entries in the .tpl file.
    $ ttf2tfm filename.ttf -v filename.vpl
$ tftopl filename.tfm > filename.tpl
$ ttx filename.ttf

  9. Publish a new version of XAML-Math

    master

    To release a new version, follow these steps to ensure metadata, versioning, and automation are correctly synchronized:

    1. Update Metadata: Update the copyright year in LICENSE.md and Directory.Build.props if necessary.
    2. Update Changelog: Prepare an entry in CHANGELOG.md (typically by renaming the "Unreleased" section to the new version number).
    3. Set Version: Update the <Version> tag in the Directory.Build.props file.
    4. Merge Changes: Submit these updates via a pull request.
    5. Verify Credentials: Ensure your NuGet API key is valid.
    6. Trigger Release: Push a git tag in the format v<VERSION> (e.g., v2.1.0). This triggers GitHub Actions to automatically push the NuGet package.

  10. Install XAML-Math for WPF or Avalonia

    master

    XAML-Math provides specialized NuGet packages depending on your UI framework:

    • For WPF: Install the WpfMath package.
      • Supports .NET Framework 4.6.2+ and .NET 8+.
    • For Avalonia: Install the AvaloniaMath package.
      • Supports .NET Framework 4.6.2+, .NET Standard 2.0+, and .NET 8+.

    There is also a XamlMath.Shared package for logic independent of the UI frameworks.

    <!-- WPF NuGet -->
<PackageReference Include="WpfMath" Version="2.1.0" />

<!-- Avalonia NuGet -->
<PackageReference Include="AvaloniaMath" Version="2.1.0" />

  11. Rotate the NuGet publishing key

    master

    The CI pipeline uses a GitHub Secret named NUGET_TOKEN. If the key becomes obsolete, follow these steps to rotate it:

    1. Sign in to nuget.org.
    2. Create or update a key named xaml-math.github.
    3. Set the key permissions to Push only new package versions.
    4. Restrict the key to only allow publishing the following packages:
      • AvaloniaMath
      • WpfMath
      • XamlMath.Shared
    5. Copy the new key and update the NUGET_TOKEN variable in the GitHub Actions secrets for the repository.

  12. Use CMYK mode

    master

    The cmyk mode accepts four parameters (Cyan, Magenta, Yellow, Black) in the range from 0 to 1. You can optionally provide a fifth parameter for opacity (range 0 to 1).

    Examples:

    \colorbox[cmyk]{0,0,0,0}{text}
\colorbox[cmyk]{0,0,0,0, 0.5}{opacity = 0.5}
    \colorbox[cmyk]{0,0,0,0, 0.5}{opacity = 0.5}