Batch rendering LaTeX to PNG is a common requirement for web documentation, knowledge bases, and math-heavy applications. Aspose.TeX for .NET provides a straightforward API to convert .tex sources into raster images with control over output directories and resolution. This article shows a minimal single-file converter and a robust batch pipeline you can drop into any .NET app.

Prerequisites

  • .NET 6 or later
  • NuGet package: Aspose.TeX
  • LaTeX sources that compile under the Object LaTeX engine used by Aspose.TeX

Aspose.TeX exposes TeXOptions.ConsoleAppOptions(TeXConfig.ObjectLaTeX), ImageDevice, and PngSaveOptions to produce PNG output.

Minimal conversion: one LaTeX file to PNG

This example converts hello-world.ltx (or .tex) to PNG in an output folder. The device writes image files directly.

// File: Program.cs
// NuGet: Aspose.TeX

using System;
using System.IO;
using Aspose.TeX;

class Program
{
    static void Main()
    {
        var inputFile  = Path.GetFullPath("hello-world.tex"); // or .ltx
        var outputDir  = Path.GetFullPath("out-png");
        Directory.CreateDirectory(outputDir);

        // 1) Create conversion options for Object LaTeX
        TeXOptions options = TeXOptions.ConsoleAppOptions(TeXConfig.ObjectLaTeX);

        // 2) Choose where to write output files
        options.OutputWorkingDirectory = new OutputFileSystemDirectory(outputDir);

        // 3) Save as PNG (you can set resolution if required)
        var png = new PngSaveOptions
        {
            // Resolution = 300 // uncomment to render at 300 DPI
        };
        options.SaveOptions = png;

        // 4) Run the job. ImageDevice writes PNG files into the output directory.
        var device = new ImageDevice();
        new TeXJob(inputFile, device, options).Run();

        Console.WriteLine("PNG written to: " + outputDir);
    }
}

This follows the documented pattern: create TeXOptions, set OutputWorkingDirectory, set PngSaveOptions, then run a TeXJob with an ImageDevice.

Batch conversion: all .tex files in a folder

The batch version scans an input directory and converts each .tex to PNG. It also shows how to control where dependencies and included graphics are read from.

// File: BatchLatexToPng.cs
// NuGet: Aspose.TeX

using System;
using System.IO;
using Aspose.TeX;

public static class BatchLatexToPng
{
    public static int Run(string inputDir, string outputDir, int? dpi = null)
    {
        if (!Directory.Exists(inputDir))
        {
            Console.Error.WriteLine("Input directory not found: " + inputDir);
            return 1;
        }
        Directory.CreateDirectory(outputDir);

        // Configure conversion options once and reuse
        var options = TeXOptions.ConsoleAppOptions(TeXConfig.ObjectLaTeX);

        // Where to read auxiliary inputs (e.g., included images)
        options.InputWorkingDirectory = new InputFileSystemDirectory(inputDir);

        // Where to read extra required packages (if you supply them)
        // options.RequiredInputDirectory = new InputFileSystemDirectory(Path.Combine(inputDir, "texmf"));

        // Where to write PNG, log, aux, etc.
        options.OutputWorkingDirectory = new OutputFileSystemDirectory(outputDir);

        // PNG save options (set DPI if needed)
        var png = new PngSaveOptions();
        if (dpi.HasValue) png.Resolution = dpi.Value;
        options.SaveOptions = png;

        int ok = 0, err = 0;
        var device = new ImageDevice(); // will write images to OutputWorkingDirectory

        foreach (var texPath in Directory.GetFiles(inputDir, "*.tex", SearchOption.AllDirectories))
        {
            try
            {
                // Optional: set a job name so output files have predictable names
                options.JobName = Path.GetFileNameWithoutExtension(texPath);

                new TeXJob(texPath, device, options).Run();
                Console.WriteLine("OK  " + Path.GetRelativePath(inputDir, texPath));
                ok++;
            }
            catch (Exception ex)
            {
                Console.WriteLine("ERR " + Path.GetRelativePath(inputDir, texPath) + " | " + ex.Message);
                err++;
            }
        }

        Console.WriteLine($"Done. Success: {ok}, Failed: {err}");
        return err == 0 ? 0 : 2;
    }
}

Key points for batch jobs:

  • Use InputWorkingDirectory for included assets like \includegraphics{img.png}.
  • Use RequiredInputDirectory if you must provide additional LaTeX packages outside the built-in set.
  • Set JobName to influence output filenames per document.

Capturing images in memory instead of writing files

If you prefer to stream PNG bytes yourself, let the device buffer them by turning off direct file writes. Then save each page to your own filenames.

using System;
using System.IO;
using Aspose.TeX;

static void ConvertToStreams(string inputFile, string outputDir)
{
    Directory.CreateDirectory(outputDir);

    var options = TeXOptions.ConsoleAppOptions(TeXConfig.ObjectLaTeX);
    var png     = new PngSaveOptions { DeviceWritesImages = false };
    options.SaveOptions = png;

    var device = new ImageDevice();
    new TeXJob(inputFile, device, options).Run();

    for (int i = 0; i < device.Result.Length; i++)
    {
        var pageBytes = device.Result[i];
        var outPath   = Path.Combine(outputDir, $"page-{i + 1}.png");
        File.WriteAllBytes(outPath, pageBytes);
    }
}

This mirrors the documented “alternative way” to write main output PNG files.

Troubleshooting and tips

  • Resolution: increase PngSaveOptions.Resolution for sharper formulas in retina screenshots or print assets.
  • Dependencies: place custom packages and inputs in the directories specified by RequiredInputDirectory and InputWorkingDirectory.
  • Naming: set options.JobName for predictable output file names in batch runs.
  • Logging: the engine writes a transcript .log to the output directory, which is useful for debugging missing packages and LaTeX errors.

When to choose other formats

PNG is ideal for web publishing and UI embedding. If you need vector output for infinite zoom or small text at scale, switch to SVG by using SvgSaveOptions and an SvgDevice, or to PDF for paged documents. The conversion flow stays the same.

With these patterns, you can automate LaTeX to PNG at scale in .NET while keeping full control over resolution, directories, and file handling.

More in this category