tikz.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_IO_TIKZ_H
#define LINE_IO_TIKZ_H
 
/**
 * @file
 * @ingroup line_io
 * Port of `jline.io.tikz.TikZExporter`, the network diagram behind MATLAB's
 * `MNetwork.toTikZ`, `exportTikZToFile`, `exportTikZ` and `tikzExportPNG`.
 *
 * `to_tikz` returns a complete `standalone` LaTeX document: the JAR's preamble
 * and styles, one TikZ node per network node at its layered-layout position
 * (tikz/tikz_layout.h), then one arrow per connection, routed around the nodes
 * in its way (tikz/tikz_edge_router.h). The text is the JAR's for the same
 * model and options, byte for byte.
 *
 * EDGE ORDER. Source nodes in model order (the drawn ones), and for each its
 * targets in ascending node index, the order of the connection-matrix row,
 * whether they are reached directly or through hidden class switches. The JAR
 * writes the same order (a node-index `TreeSet`, since it replaced a `HashSet`
 * of identity-hashed nodes), and so does MATLAB, which draws through the JAR.
 *
 * Every arrow is unlabelled: `generateTikZ` passes a NaN probability for every
 * edge, so `show_routing_prob` never takes effect, here as there.
 *
 * `export_tikz` and `tikz_export_png` shell out to `pdflatex` (and `pdftoppm`,
 * from poppler-utils) through `util::capture`; `tikz_pdflatex_available` says
 * whether the first can run. `tikz_view` is `MNetwork.tikzView` (the JAR's
 * `TikZExporter.display`): it compiles the PDF into a directory it leaves in
 * place and opens it in a standalone viewer when asked to and one is on PATH.
 */
 
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <sstream>
#include <string>
#include <vector>
 
#include <sys/stat.h>
 
#include "line/io/tikz/tikz_edge_router.h"
#include "line/io/tikz/tikz_graph.h"
#include "line/io/tikz/tikz_layout.h"
#include "line/io/tikz/tikz_node_renderer.h"
#include "line/io/tikz/tikz_options.h"
#include "line/lang/qn/network_builder.h"
#include "line/lang/qn/network_struct.h"
#include "line/util/error.h"
#include "line/util/subprocess.h"
#include "line/util/tempdir.h"
 
namespace line {
namespace io {
 
namespace tikz_detail {
 
/** `isAutoGeneratedNode`: a ClassSwitch named `CS_..._to_...`, the name `link` gives the switch it inserts. */
inline bool is_auto_generated(const TikzNode& nd) {
    return nd.type == lang::NodeType::ClassSwitch && nd.name.compare(0, 3, "CS_") == 0 &&
           nd.name.find("_to_") != std::string::npos;
}
 
/** `getOutputAnchor`: a Queue's arrows leave its server circle when one is drawn; every other node, a Delay included, its box. */
inline std::string output_anchor(const TikzNode& nd, const TikzOptions& opt) {
    return nd.type == lang::NodeType::Queue && opt.show_server_count ? "_server.east" : ".east";
}
 
/** `renderSelfLoop`: the wide loop from the server circle of a Queue that draws one, the plain-node loop otherwise. */
inline std::string self_loop(const std::string& id, const TikzNode& nd, const TikzOptions& opt) {
    if (nd.type == lang::NodeType::Queue && opt.show_server_count)
        return "\\draw[conn] (" + id + "_server.north) -- ++(0,0.6) -- ++(-1.8,0) -- ++(0,-0.6) -- (" +
               id + ".west);\n";
    return "\\draw[conn] (" + id + ".north) -- ++(0,0.5) -- ++(-0.8,0) -- ++(0,-0.5) -- (" + id +
           ".west);\n";
}
 
inline bool file_exists(const std::string& p) {
    struct stat st;
    return ::stat(p.c_str(), &st) == 0 && S_ISREG(st.st_mode);
}
 
inline bool ends_with(const std::string& s, const std::string& suf) {
    return s.size() >= suf.size() && s.compare(s.size() - suf.size(), suf.size(), suf) == 0;
}
 
inline void write_text(const std::string& path, const std::string& text) {
    std::ofstream out(path.c_str(), std::ios::binary);
    if (!out) throw InputError("tikz: cannot write '" + path + "'");
    out << text;
    if (!out) throw InputError("tikz: failed writing '" + path + "'");
}
 
inline void copy_file(const std::string& from, const std::string& to) {
    std::ifstream in(from.c_str(), std::ios::binary);
    if (!in) throw InputError("tikz: cannot read '" + from + "'");
    std::ofstream out(to.c_str(), std::ios::binary);
    if (!out) throw InputError("tikz: cannot write '" + to + "'");
    out << in.rdbuf();
    if (!out) throw InputError("tikz: failed writing '" + to + "'");
}
 
/** Seconds a pdflatex or pdftoppm run may take before it is killed; a TikZ picture needs a few. */
constexpr int kToolTimeout = 600;
 
/**
 * `exportToPDF`: compile `tex` in a fresh directory and return the PDF path.
 * The directory belongs to `dir`, so the caller copies the PDF out before it goes.
 */
inline std::string compile_pdf(const std::string& tex, const util::TempDir& dir) {
    if (util::capture({"pdflatex", "--version"}, 60, true).exitCode != 0)
        throw Error("pdflatex is not available. Please install TeX Live or MiKTeX.");
    const std::string texfile = dir.file("network.tex");
    const std::string pdffile = dir.file("network.pdf");
    write_text(texfile, tex);
    const util::ProcResult r = util::capture(
        {"pdflatex", "-interaction=nonstopmode", "-output-directory=" + dir.path(), texfile},
        kToolTimeout, true);
    if (r.timedOut)
        throw Error("pdflatex did not finish within " + std::to_string(kToolTimeout) + " s");
    if (r.exitCode != 0 || !file_exists(pdffile))
        throw Error("pdflatex compilation failed:\n" + r.out);
    return pdffile;
}
 
}  // namespace tikz_detail
 
/** `TikZExporter.generateTikZ` over an extracted graph. */
inline std::string to_tikz(const TikzGraph& g, const TikzOptions& opt = TikzOptions()) {
    const TikzLayout L = tikz_layout(g, opt);
    const std::size_t n = g.nodes.size();
    std::ostringstream sb;
    sb << tikz_preamble(opt) << "\n";
    sb << "\\begin{document}\n\\begin{tikzpicture}\n\n";
 
    std::vector<std::size_t> visible;
    std::vector<bool> is_visible(n, false);
    for (std::size_t v = 0; v < n; ++v)
        if (!opt.hide_auto_generated_nodes || !tikz_detail::is_auto_generated(g.nodes[v])) {
            visible.push_back(v);
            is_visible[v] = true;
        }
 
    sb << "% Nodes\n";
    for (std::size_t v : visible) sb << tikz_render_node(g.nodes[v], L.x[v], L.y[v], opt);
    sb << "\n";
 
    sb << "% Connections\n";
    TikzEdgeRouter router(L.x, L.y, visible);
    for (std::size_t from : visible) {
        // buildCollapsedConnections: the visible nodes reached through hidden ones
        std::vector<bool> seen(n, false), target(n, false);
        std::vector<std::size_t> queue;
        for (std::size_t j = 0; j < n; ++j)
            if (g.conn[from][j] && !seen[j]) {
                seen[j] = true;
                queue.push_back(j);
            }
        for (std::size_t q = 0; q < queue.size(); ++q) {
            const std::size_t cur = queue[q];
            if (is_visible[cur]) {
                target[cur] = true;
                continue;
            }
            for (std::size_t j = 0; j < n; ++j)
                if (g.conn[cur][j] && !seen[j]) {
                    seen[j] = true;
                    queue.push_back(j);
                }
        }
        const std::string fid = tikz_detail::sanitize_id(g.nodes[from].name);
        for (std::size_t to = 0; to < n; ++to) {
            if (!target[to]) continue;
            if (to == from) {
                sb << tikz_detail::self_loop(fid, g.nodes[from], opt);
                continue;
            }
            const std::vector<TikzPoint> wp = router.compute_waypoints(from, to);
            sb << tikz_render_routed_edge(fid, tikz_detail::sanitize_id(g.nodes[to].name),
                                          tikz_detail::output_anchor(g.nodes[from], opt), ".west", wp,
                                          std::numeric_limits<double>::quiet_NaN(), opt);
        }
    }
    sb << "\n\\end{tikzpicture}\n\\end{document}\n";
    return sb.str();
}
 
/** `Network.toTikZ(options)` over a network struct. */
template <class T>
std::string to_tikz(const qn::NetworkStruct<T>& sn, const TikzOptions& opt = TikzOptions()) {
    return to_tikz(tikz_graph(sn), opt);
}
 
/** `Network.toTikZ(options)`; refreshes the struct, as the JAR's `getStruct()` does. */
template <class T>
std::string to_tikz(qn::Network<T>& model, const TikzOptions& opt = TikzOptions()) {
    return to_tikz(model.get_struct(), opt);
}
 
/** Can `pdflatex --version` run? (`TikZExporter.isPdfLatexAvailable`) */
inline bool tikz_pdflatex_available() {
    return util::capture({"pdflatex", "--version"}, 60, true).exitCode == 0;
}
 
/** `Network.exportTikZToFile`: the document, written to `tex_path` as given. */
template <class M>
void export_tikz_to_file(M& model, const std::string& tex_path, const TikzOptions& opt = TikzOptions()) {
    tikz_detail::write_text(tex_path, to_tikz(model, opt));
}
 
/**
 * `Network.exportTikZ`: write `<stem>.tex` and compile it to `<stem>.pdf`,
 * where the stem is `path` less a `.pdf` or `.tex` suffix. Returns the PDF path.
 *
 * The JAR writes the same `.tex` and returns a PDF left in a temporary
 * directory; this port puts the PDF beside the `.tex` instead, which is where
 * a caller that named a path expects to find it, and leaves no directory behind.
 */
template <class M>
std::string export_tikz(M& model, const std::string& path, const TikzOptions& opt = TikzOptions()) {
    std::string stem = path;
    if (tikz_detail::ends_with(stem, ".pdf") || tikz_detail::ends_with(stem, ".tex"))
        stem.resize(stem.size() - 4);
    const std::string tex = to_tikz(model, opt);
    tikz_detail::write_text(stem + ".tex", tex);
    util::TempDir dir("tikz");
    const std::string pdf = tikz_detail::compile_pdf(tex, dir);
    tikz_detail::copy_file(pdf, stem + ".pdf");
    return stem + ".pdf";
}
 
/**
 * `Network.tikzExportPNG(path, dpi)`: compile the document and rasterise it
 * with `pdftoppm -png -r dpi -singlefile`. `.png` is appended when missing, as
 * the JAR does. Returns the PNG path.
 */
template <class M>
std::string tikz_export_png(M& model, const std::string& path, int dpi = 150,
                            const TikzOptions& opt = TikzOptions()) {
    const std::string png = tikz_detail::ends_with(path, ".png") ? path : path + ".png";
    util::TempDir dir("tikz");
    const std::string pdf = tikz_detail::compile_pdf(to_tikz(model, opt), dir);
    const util::ProcResult r =
        util::capture({"pdftoppm", "-png", "-r", std::to_string(dpi), "-singlefile", pdf,
                       png.substr(0, png.size() - 4)},
                      tikz_detail::kToolTimeout, true);
    if (r.timedOut)
        throw Error("pdftoppm did not finish within " + std::to_string(tikz_detail::kToolTimeout) + " s");
    if (r.exitCode != 0) throw Error("pdftoppm conversion failed:\n" + r.out);
    return png;
}
 
namespace tikz_detail {
 
/** The first executable named `cmd` on PATH, empty when there is none (`TikZViewer.isCommandAvailable`). */
inline std::string find_on_path(const std::string& cmd) {
    const char* p = std::getenv("PATH");
    if (p == nullptr) return std::string();
    std::stringstream ss(p);
    std::string dir;
    while (std::getline(ss, dir, ':')) {
        const std::string f = (dir.empty() ? std::string(".") : dir) + "/" + cmd;
        if (file_exists(f) && ::access(f.c_str(), X_OK) == 0) return f;
    }
    return std::string();
}
 
/** Start `argv` detached (own session, std streams on /dev/null, double fork so no zombie); false if it cannot start. */
inline bool spawn_detached(const std::vector<std::string>& argv) {
    const pid_t pid = ::fork();
    if (pid < 0) return false;
    if (pid == 0) {
        ::setsid();
        if (::fork() != 0) ::_exit(0);
        const int devnull = ::open("/dev/null", O_RDWR);
        if (devnull >= 0) {
            ::dup2(devnull, STDIN_FILENO);
            ::dup2(devnull, STDOUT_FILENO);
            ::dup2(devnull, STDERR_FILENO);
            if (devnull > STDERR_FILENO) ::close(devnull);
        }
        util::detail::exec_never_returns(argv);
    }
    int status = 0;
    ::waitpid(pid, &status, 0);
    return WIFEXITED(status) && WEXITSTATUS(status) == 0;
}
 
/** `TikZViewer.displayPDF`: a standalone viewer first, then the desktop default; false when neither is found. */
inline bool display_pdf(const std::string& pdf) {
    static const char* const viewers[] = {"evince", "okular", "mupdf", "zathura", "qpdfview", "acroread"};
    for (const char* v : viewers)
        if (!find_on_path(v).empty() && spawn_detached({v, pdf})) return true;
#ifdef __APPLE__
    const char* desktop = "open";
#else
    const char* desktop = "xdg-open";
#endif
    return !find_on_path(desktop).empty() && spawn_detached({desktop, pdf});
}
 
}  // namespace tikz_detail
 
namespace tikz_detail {
inline const std::string& model_name(const TikzGraph& g) { return g.name; }
template <class T>
const std::string& model_name(const qn::NetworkStruct<T>& sn) { return sn.name; }
template <class T>
const std::string& model_name(qn::Network<T>& m) { return m.raw_struct().name; }
}  // namespace tikz_detail
 
/** What `tikz_view` produced. */
struct TikzViewResult {
    std::string path;     ///< the compiled PDF, or the `.tex` saved when it could not be compiled
    bool compiled = false;  ///< `path` is a PDF
    bool opened = false;    ///< a viewer was started on it
};
 
/**
 * `MNetwork.tikzView` (`TikZExporter.display`). With pdflatex, compile the
 * document into a fresh `line_tikz_*` directory that is LEFT IN PLACE (the
 * viewer reads it after this returns) and, when `open_viewer`, start a PDF
 * viewer on it. Without pdflatex, or when compilation fails, save the source
 * to `network-diagram.tex` in the working directory, as the JAR does, and say
 * so on stdout. Nothing is thrown for a missing tool; the result says what exists.
 */
template <class M>
TikzViewResult tikz_view(M& model, const TikzOptions& opt = TikzOptions(), bool open_viewer = true) {
    TikzViewResult res;
    const std::string tex = to_tikz(model, opt);
    if (tikz_pdflatex_available()) {
        try {
            util::TempDir dir("tikz");
            res.path = tikz_detail::compile_pdf(tex, dir);
            dir.keep();
            res.compiled = true;
        } catch (const Error& e) {
            std::cerr << "Failed to generate visualization: " << e.what() << "\n";
        }
    }
    if (!res.compiled) {
        res.path = "network-diagram.tex";
        tikz_detail::write_text(res.path, tex);
        std::cout << "TikZ code saved to: " << res.path << "\nCompile manually with: pdflatex " << res.path
                  << "\n";
        return res;
    }
    if (open_viewer) {
        res.opened = tikz_detail::display_pdf(res.path);
        if (res.opened)
            std::cout << "Opened diagram for: " << tikz_detail::model_name(model) << "\n";
        else
            std::cout << "Could not open PDF viewer. File saved at: " << res.path << "\n";
    }
    return res;
}
 
}  // namespace io
}  // namespace line
 
#endif  // LINE_IO_TIKZ_H