Function plot_image_chars

tests/BS_thread_pool_test.cpp:3505–3590

* @brief Create a plot of an image as characters, using either 24-bit ANSI colors or monochrome blocks of different brightness. * * @param image The image to plot. * @param out_width The plot width in terminal characters. Should be even, since in the monochrome case each pixel spans two characters horizontally. * @param use_color `true` to generate a colored plot, `false` to generate a monochr

 * @return The plot as a string.
 */
std::string plot_image_chars(const image_matrix<color>& image, const std::size_t out_width, const bool use_color)
{
    // Get the source image dimensions.
    const std::size_t src_width = image.get_width();
    const std::size_t src_height = image.get_height();
    // Compute the plot height in terminal characters, keeping in mind that characters have an aspect ratio of about 1:2 (width:height).
    const std::size_t out_height = static_cast<std::size_t>(std::llround(0.5 * static_cast<double>(src_height) * static_cast<double>(out_width) / static_cast<double>(src_width)));
    // Create a buffer for the plot.
    std::string plot;

    // For the colored plot we use Unicode lower half blocks to pack two pixels per character. The background color sets the color of the top (empty) half, and the foreground color sets the color of the bottom (filled) half.
    if (use_color)
    {
        // Each character row contains two pixel rows (top and bottom).
        const std::size_t out_height_pixels = out_height * 2;
        // Create a mapping of output x coordinates to source pixels, such that x_map[0] = 0 and x_map[out_width - 1] = src_width - 1.
        std::vector<std::size_t> x_map(out_width);
        for (std::size_t x = 0; x < out_width; ++x)
            x_map[x] = (x * (src_width - 1)) / (out_width - 1);
        // Create a mapping of output pixel y coordinates to source pixels, such that y_map[0] = 0 and y_map[out_height_pixels - 1] = src_height - 1.
        std::vector<std::size_t> y_map(out_height_pixels);
        for (std::size_t y = 0; y < out_height_pixels; ++y)
            y_map[y] = (y * (src_height - 1)) / (out_height_pixels - 1);
        // Reserve enough capacity for the entire plot to avoid reallocations. Each row contains ANSI codes of the form `\033[48;2;RRR;GGG;BBBm\033[38;2;RRR;GGG;BBBm` = up to 38 bytes, plus the Unicode lower half block U+2584 in UTF-8 = 3 bytes, for a total of 41 bytes per character of the plot, plus the `\033[0m` reset code at the end and the newline = 5 bytes.
        plot.reserve(out_height * ((out_width * 41) + 5));
        // Iterate over the rows and columns.
        for (std::size_t y = 0; y < out_height; ++y)
        {
            for (std::size_t x = 0; x < out_width; ++x)
            {
                // Fetch the sampled source pixel for the top and bottom halves.
                const color col_top = image(x_map[x], y_map[2 * y]);
                const color col_bottom = image(x_map[x], y_map[(2 * y) + 1]);
                // Create the background color ANSI sequence for the top half.
                plot.append("\033[48;2;");
                plot.append(std::to_string(col_top.r));
                plot.push_back(';');
                plot.append(std::to_string(col_top.g));
                plot.push_back(';');
                plot.append(std::to_string(col_top.b));
                // Finish the sequence with `m` and create the foreground color ANSI sequence for the bottom half.
                plot.append("m\033[38;2;");
                plot.append(std::to_string(col_bottom.r));
                plot.push_back(';');
                plot.append(std::to_string(col_bottom.g));
                plot.push_back(';');
                plot.append(std::to_string(col_bottom.b));
                // Finish the sequence with `m` and append a lower half block (U+2584) in UTF-8, which is the actual character that will be displayed.
                plot.append("m\xE2\x96\x84");
            }
            // Reset the ANSI style at the end of the row and add a newline character.
            plot.append("\033[0m\n");
        }
    }
    // For the monochrome plot we use Unicode block characters of different brightness levels. Each pixel is rendered as two identical blocks side-by-side to make the pixels square (so essentially, the opposite of the colored plot).
    else
    {
        // Each pixel spans two terminal characters horizontally.