f20x

Demystifying the Random Avatar Generator: A JavaScript Code Analysis

Manuel Herrera — Thu, 23 Jan 2025 00:00:00 GMT

Have you ever wondered how websites generate those unique, pixelated default profile pictures for new users? They might look like simple geometric shapes, but under the hood, there is a fascinating mix of mathematics, software design, and web technologies at play.

This article analyzes a specific open-source library, the Random Avatar Generator, created by Fractal Software. Designed as part of an academic publication and a side project, this library serves an educational purpose: to illustrate different aspects of JavaScript's capabilities and general software development concepts.

::github{repo="fractalsoftware/random-avatar-generator"}

The tool generates random pixel-pattern avatars with a focus on low collision (ensuring you rarely get the same avatar twice) and zero external dependencies (meaning it doesn't rely on massive third-party libraries). Let's dive into the patterns, programming aspects, and computer science concepts this elegant script employs.

1. Separation of Concerns (Architecture)

A fundamental principle in computer science is Separation of Concerns (SoC)—dividing a computer program into distinct sections so each section addresses a separate concern. In this library, the creator explicitly divided the avatar creation process into two distinct phases:

Data Generation (generateRandomAvatarData): This method computes the math and logic to randomly determine which "pixels" are turned on or off and what colors they should be. It outputs a lightweight string of data (e.g., 0-6-6te25-9d9p0-xd5g).
Rendering (getAvatarFromData): This method takes the data string and translates it into an actual visual graphic (an SVG image).

Why is this a good pattern? Because the application state (the data string) is separate from the user interface (the SVG). If you want to save a user's generated avatar in a database, you don't need to save a massive image file; you just save the tiny string 0-6-6te25-9d9p0-xd5g and re-render it whenever needed! To make things easier for developers who just want a quick image, the author also includes a helper function called getRandomAvatar() that combines both steps.

2. The Strategy Pattern for Rendering

The Strategy Pattern is a behavioral design pattern that lets you define a family of algorithms, put each of them into a separate function, and make their objects interchangeable.

The library includes an API parameter called renderMethod. By default, the avatar uses a square rendering strategy, but developers can change it to a circle strategy. Even better, the library accepts a custom callback function to draw entirely new shapes.

For example, a developer can pass a custom function to draw triangles instead of squares:

const drawTriangle = (resolution, indexX, indexY) => {
   return `M${indexX * resolution + resolution / 2},${indexY * resolution} l${ resolution / 2 } ${resolution} l-${resolution} 0z`;
}

For a beginner, this is a prime example of Polymorphism and High Extensibility. The core engine of the library doesn't need to know how to draw a triangle; it just delegates the drawing logic to whatever function you provide it.

3. Dealing with "Collision" (Probability and Math)

In computer science, a "collision" happens when two different inputs produce the exact same output. In the context of an avatar generator, a collision means two different users randomly getting the exact same profile picture.

To solve this, the script relies heavily on matrix generation and probability manipulation. According to the documentation:

"In order to have bigger numeric space to prevent collision, each row within the matrix has a random color number."

By associating randomization not just with the coordinates (X and Y axes), but also injecting color variation at the row level, the total permutations (the number of possible unique avatars) skyrocket. The strings generated (like 6te25) represent integers converted into alphanumeric base formats (like base-36 or hexadecimal). Base conversion is a highly effective way to compress large numerical values into short, readable strings.

4. Scalable Vector Graphics (SVG) and Template Literals

Instead of using an HTML Canvas element or generating an image file (like a PNG or JPG), the script generates SVG (Scalable Vector Graphics) code.

SVG is an XML-based markup language used for describing two-dimensional vector graphics. Since SVGs are built using mathematical formulas (lines, paths, and curves) instead of fixed pixels, they can scale to any size without losing quality.

The library uses modern JavaScript Template Literals (strings wrapped in backticks `) to dynamically inject variables directly into the SVG path strings:

`<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 ${size} ${size}">...`

For entry-level developers, manipulating DOM elements or drawing directly via JavaScript can be cumbersome. Building a raw markup string and returning it is often a faster, more flexible approach that works identically on a Web Browser, inside a Node.js server, or inside a React component.

5. Functional Default Parameters

Another modern JavaScript concept used across the library's API is the use of Default Parameters. Functions like generateRandomAvatarData and getAvatarFromData have fallback values if the user decides not to configure them.

For example:

complexity: Defaults to 16
renderMethod: Defaults to "square"
size: Defaults to 256

This represents a design philosophy called Convention over Configuration. It means the library works flawlessly out of the box with sensible defaults, while still allowing power-users to open the hood and tinker with the parameters.

Playground

You can see this application in action, an generate your own patterns here: Random Avatar Generator.

Conclusion

What appears to be a simple script for rendering colorful boxes is actually a rich educational playground. By reading through scripts like the Random Avatar Generator, computer science students and junior developers can see practical implementations of architectural decoupling, base-conversions, strategy patterns, and clever utilization of native web capabilities like SVG. Next time you encounter a randomly generated default avatar, you'll know exactly what kind of software magic is happening behind the scenes!

How (and why) I vibe-coded an app to test Markov chains for image generation

Manuel Herrera — Tue, 05 Aug 2025 00:00:00 GMT

Some days ago, binge-watching on YouTube, I "found" the latest video from the famous channel Veritasium about the mathematical concept called Markov chains. Of course, its catchy (clickbait) title, The Strange Math That Predicts (Almost) Anything, engaged me immediately. After half an hour engaged by its storytelling and well produced content, I wanted to test the concepts exposed there.

I must admit that I believed that, before watching that video, I understood what is a Markov chain. Wrong. The simplicity of the math behind left me surprised and fully motivated to experiment in a field that I always find exciting: image manipulation.

A proof of concept

Initially, I wanted to iterate on a simple command-line method that produces a sequence of characters that can be used as "pixels". ASCII characters came to help: [' ', '░', '▒', '▓', '█', '▄', '▀']. Now, with probabilities matrix, the work here is only iterate over a given number of steps and, with a random seed, check the probability of an ocurrency:

function markov(steps = 1000) {
    const states = [' ', '░', '▒', '▓', '█', '▄', '▀'];
    const transitionProbabilities = {
        [states[0]]: { [states[0]]: 0.9, [states[1]]: 0.0, [states[2]]: 0.0, [states[3]]: 0.0, [states[4]]: 0.1, [states[5]]: 0.0, [states[6]]: 0.0 },
        [states[1]]: { [states[0]]: 0.1, [states[1]]: 0.9, [states[2]]: 0.0, [states[3]]: 0.0, [states[4]]: 0.9 , [states[5]]: 0.0, [states[6]]: 0.9 },
        [states[2]]: { [states[0]]: 0.0, [states[1]]: 0.1, [states[2]]: 0.9, [states[3]]: 0.0, [states[4]]: 0.0 , [states[5]]: 0.1, [states[6]]: 0.0 },
        [states[3]]: { [states[0]]: 0.0, [states[1]]: 0.0, [states[2]]: 0.1, [states[3]]: 0.9, [states[4]]: 0.1 , [states[5]]: 0.1, [states[6]]: 0.0 },
        [states[4]]: { [states[0]]: 0.0, [states[1]]: 0.0, [states[2]]: 0.0, [states[3]]: 0.0, [states[4]]: 0.0 , [states[5]]: 0.1, [states[6]]: 0.1},
        [states[5]]: { [states[0]]: 0.1, [states[1]]: 0.0, [states[2]]: 0.0, [states[3]]: 0.9, [states[4]]: 0.0 , [states[5]]: 0.1, [states[6]]: 0.0},
        [states[6]]: { [states[0]]: 0.0, [states[1]]: 0.1, [states[2]]: 0.0, [states[3]]: 0.0, [states[4]]: 0.1 , [states[5]]: 0.0, [states[6]]: 0.1},
    }

    let currentState = states[4];
    let accumulator = currentState;

    while (steps > 0) {
        const nextState = states[Math.floor(Math.random() * states.length)];
        const probability = transitionProbabilities[currentState][nextState];
        if (Math.random() < probability) {
            if (steps % 90 === 0) {
                accumulator += '\n';
            }
            currentState = nextState;
            accumulator += currentState;
            steps--;
        }
    }

    return accumulator;
}

The result? A promising nice pattern like this one:

Learning (machines)

But, the interesting part of Markov chains is their ability to learn from previous sources. In the previous example, the transitionsProbabilities matrix was deliberated, tunned manually to obtain similar patterns. What does it means? We need to provide a way to build or calculate that matrix from an initial source. A new method must be introduced to perform that calculations. Additionally, it required to evaluate the probabilities from an external image or a set of images.

As the previous example showed, we have a limited set of "colors", 7 in total. Reducing the number of colors of the source image will improve the speed of processing and creation of the output image.

The final matrix will be a simplified representation of the current image, keeping the general structure and probabilities of the original image.

I wanted an interactive application that can be deployed in any static server: basic HTML, JavaScript and CSS.

This list of restictions will be a good starting point to develop a more robust solution, but requires going deeper in the following aspects:

Image manipulation using the Canvas API.
Color reduction algorithm.
Markov chains learning algorithm.

Vibe prompting

As something that I wanted to explore quick, I decided to use some generative AI to create this app faster. But as many knows, a good prompt is the key of a good result. Why not use the same tool to create a well documented set of instructions to generate the expected application? Using Gemini 2.5 flash, I asked for:

write a detailed document that instructs an AI to develop an application in javascript that, using the Markov chains concept, learns from a set of base images, subscaling and reducing their colors to a user defined total. Then, with the obtained probabilities, generates a new image

The result: an impressive and highly detailed, a thousand words long document that details the requirements of this application: ai-instructions.md. It went way beyond my expectations, describing the HTML document, a general requirement for the styles, and the structure of the JavaScript file. But it makes a strong emphasis describing the inner process of the application split in three sections:

Image Preprocessing (Subscaling and Color Reduction)
Markov Chain Learning
Image Generation

Each step has a brief description and a set of instructions for the AI, e.g.,

Objective: Implement the logic to load images, resize them, and reduce their color palette to a user-defined number of colors. Instructions for AI: 1. Image Loading and Subscaling (processImages function): - When the "Process Images & Learn" button is clicked, iterate through the selected files from the file input...

Some instructions offers different alternatives, but makes a final decision at the end,

Pixel Traversal: For each image, traverse its pixels. Consider different neighborhood relationships for the Markov chain: - Option 1 (Simple - 1D): Learn probabilities based on a pixel and its right neighbor ((x,y) to (x+1,y)). This is simpler but might produce less cohesive images. - Option 2 (Slightly More Complex - 2D): Learn probabilities based on a pixel and its right neighbor AND its bottom neighbor ((x,y) to (x+1,y) and (x,y) to (x,y+1)). This generally produces better results. - AI Choice: Implement Option 2 for a more robust model.

or simply mention other possible solutions,

Recommended Algorithm: Use a K-means clustering algorithm or a similar perceptual color reduction method (e.g., Octree Quantization if simpler to implement in JS).

In other sections, it even presents code suggestions:

The structure of markovChainModel should be,

{
    "color1": {
        "next_color_1": probability,
        "next_color_2": probability,
        // ...
    },
    "color2": {
        // ...
    }
}

or describes an algorith to solve a particular problem,

Counting Transitions: - For each pixel P1 at (x,y): - Get its color C1. - Get the color C2 of its right neighbor P2 at (x+1,y) (if within bounds). - Get the color C3 of its bottom neighbor P3 at (x,y+1) (if within bounds). - Increment counts in markovChainModel: - markovChainModel[C1][C2] (for horizontal transitions) - markovChainModel[C1][C3] (for vertical transitions) - Handle edge cases (last row/column pixels).

On a following step, called Refinements and Error Handling, it makes some suggestions related with the user interface, like Input Validation or User Feedback. Others related with the Performance Considerations and Visual Quality Enhancements. It even dedicate a section to the Code Structure.

Finally, a list of deliverables where, alongside the item, it presents a really brief description of each file. Another deliverable suggested is a documentation (it doesn´t specify an output format), highlighting the use instructions, the technical details behind the Markov chain implementation, and possible limitations of the app.

Vibe coding

Using the Canvas option enabled in the Gemini web interface, I asked to build the solution:

Using the previous response, generate the described application

Well, after a short wait, I got this,

I have created the Markov Chain Image Generation application you described. Below are the complete, self-contained files for the application. You can save these three files (index.html, style.css, and script.js) in the same folder and open index.html in your web browser to run the application.

followed by three files ready to be downloaded. The Canvas option in the Gemini UI, allows the live previsualization of web applications.

Mixed results

The first iteration returned an almost unusable application, with missing links to the correct Tailwind styles and broken JavaScript methods. after aking to fix it, it came with a decent result that,at the end required manual tweaking in most of its parts.

Here you can experiment with the manually edited result: Markov Image Generator .

Conclusions

This is a promising technology that will transform in less than a year the way software is developed. Engineers will need a new set of skills required to orchestrate autonomous workers, understanding problems in a macro perspective, know how to write tailored instructions, and be aware of the limitations of the current tools.

Great times will come, scary but thrilling times!

Shrink Your Stash: Breaking Down the Ultimate WebP Converter Script

Manuel Herrera — Tue, 17 Mar 2026 05:00:00 GMT

Hey there. So, you’ve been hoarding high-res PNGs and JPEGs. Maybe it’s a folder of 4K cat photos, maybe it’s an overblown website assets directory. We’ve all been there. Well, as an Web Developer, I have a physical hard drive that gets bogged down with giant files, and absolutely feel your pain when things run slower than they need to.

Today, we’re going to take a nice, slow walk through a pretty slick Bash script called bulkwebp (source code). It doesn’t just convert your images to WebP (Google's highly efficient image format); it throws all your CPU cores at the problem so you aren't waiting around until the next ice age, and then it gives you a neat little receipt of the megabytes you saved.

Let’s kick back, grab a beverage, and dissect how this bad boy works, piece by piece.

1. Setting the Stage (and Finding Your Cores)

Right out of the gate, the script establishes some ground rules.

REPLACE=false
RECURSIVE_MODE=false 
CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 1) 
FILE_TYPE=""

The Safety Nets: REPLACE and RECURSIVE_MODE default to false. The script isn't going to go rogue and delete your original files or dive deep into your forbidden subdirectories unless you explicitly tell it to.
The Core Sniffer: That CORES line is a thing of beauty. It tries to use nproc (common on Linux) to see how many CPU cores you have. If that fails, it tries sysctl (the macOS way). If that fails, it just throws its hands up and assumes you have 1 core. It's doing the heavy lifting so you don't have to guess your machine's specs.

2. The Bouncer: Argument Parsing

Next up, the script has to figure out what you actually want it to do based on the flags you passed in the terminal.

while [ $# -gt 0 ]; do
  case "$1" in
    -r|--recursive)
...

This while loop is basically a bouncer at the club, checking IDs. It looks at the first argument ($1), figures out what flag it is (like -r or --cores), sets the internal variable, and then uses shift to kick that argument out of line so it can check the next one.

:::note Look at the `-t|--type` block. It actually strips out a leading dot if you accidentally type `-t .png` instead of `-t png`. That is some excellent, forgiving UX design right there in a terminal script! :::

3. The Bloodhound: Building the `find` Command

Instead of hardcoding how to search for files, the script dynamically builds a find command based on the flags you set.

Staying shallow: If RECURSIVE_MODE is false, it slaps -maxdepth 1 onto the command so it only looks in the current folder.
Picking targets: If you specified a file type, it targets that. Otherwise, it casts a wide net for the usual suspects: .png, .jpg, .jpeg, and .tiff.

By the end of this section, FIND_CMD is a fully loaded string ready to sniff out your hefty images.

4. The Heavy Lifting: `xargs` and Parallel Processing

This is where the script goes from "neat" to "absolute beast."

Instead of converting files one by one in a slow, agonizing queue, it uses xargs -P "$CORES".

Exporting Variables: It uses export REPLACE so the mini-scripts running in parallel know if they have permission to delete the original files.
The Payload (SCRIPT): It defines a chunk of code that uses cwebp to do the actual conversion. It also uses wc -c to count the exact byte size of the original file and the new WebP file.
The Secret Messages: Notice how it echos out things like ✅ Converted but also outputs a weird line like SIZE_STATS 150000 45000? That is a hidden data string meant for the next part of our script. It’s like the workers passing notes to the accountant.

5. The Accountant: `awk`

Finally, all this parallel terminal output gets piped (|) into awk, which is basically the spreadsheet nerd of the Linux world.

awk '/^SIZE_STATS/ {
    orig_total += $2
    new_total += $3
    next
}
...

awk sits at the end of the pipeline, reading every line of text that the conversion workers spit out.

If it sees a line starting with SIZE_STATS, it says, "Ah, data!" It intercepts those numbers, adds them to a running total, and hides the line from your screen (next).
If it sees any other line (like the green checkmarks or the trash can emojis), it just prints it normally so you can watch the progress.

Once all the files are done (the END block), awk does some quick math to convert those bytes into Megabytes, calculates the percentage of space you saved, and prints out a beautiful little receipt.

The Verdict

This script is a fantastic example of gluing together standard Unix tools (find, xargs, awk) to create something highly efficient. It respects your time by using parallel processing, and it respects your terminal by giving you a clean, readable summary at the end instead of just vomiting data onto the screen.

The Full Script

In case you where wondering what I'm talking about, and you missed the link in the introduction, here you have the full script for your delight:

#!/bin/bash

# Default values for flags
REPLACE=false
RECURSIVE_MODE=false # Use a simple boolean for logic
CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 1) # Get core count
FILE_TYPE="" # Variable to store the optional file extension

##
# Displays help message
##
show_help() {
cat << EOF
Usage: bulkwebp [OPTIONS]
Converts images in the directory to WebP format and calculates space saved.

This high-performance version processes files in parallel for maximum speed.

Options:
  -r, --recursive   Recursively search for images in all subdirectories.
  -p, --replace     Delete the original source image after a successful conversion.
  -c, --cores NUM   Specify the number of parallel jobs (default: all available cores).
  -t, --type EXT    Specify a single input file extension to convert (e.g., png, jpg). Defaults to all common formats.
  -h, --help        Display this help message and exit.
EOF
}

# --- Argument Parsing ---
while [ $# -gt 0 ]; do
  case "$1" in
    -r|--recursive)
      RECURSIVE_MODE=true
      shift
      ;;
    -p|--replace)
      REPLACE=true
      shift
      ;;
    -c|--cores)
      CORES="$2"
      shift 2
      ;;
    -t|--type)
      # Remove any leading dot if the user accidentally typed "-t .png" instead of "-t png"
      FILE_TYPE="${2#.}" 
      shift 2
      ;;
    -h|--help)
      show_help
      exit 0
      ;;
    *)
      echo "Error: Unknown option '$1'" >&2
      show_help
      exit 1
      ;;
  esac
done

# --- Build find command ---
# Start with the base command
FIND_CMD="find ."

# Add maxdepth option ONLY if not in recursive mode
if [ "$RECURSIVE_MODE" = "false" ]; then
    FIND_CMD+=" -maxdepth 1"
fi

# Add the file type and name patterns dynamically
if [ -n "$FILE_TYPE" ]; then
    # If a specific type is provided, only look for that extension
    FIND_CMD+=" -type f -iname '*.$FILE_TYPE' -print0"
else
    # Default behavior: look for standard image formats
    FIND_CMD+=" -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.tiff' \) -print0"
fi

# --- Main Execution ---
# Export the REPLACE variable so it's available to the subshells created by xargs
export REPLACE

# The `sh -c '...'` script that will be executed by xargs for each file
SCRIPT='
    filepath="$1"
    outfile="${filepath%.*}.webp"
    
    # Extract original size in bytes (cross-platform friendly)
    orig_size=$(wc -c < "$filepath")
    
    if cwebp -quiet "$filepath" -o "$outfile"; then
        # Extract new size in bytes
        new_size=$(wc -c < "$outfile")
        
        echo "✅ Converted: $outfile"
        # Output a hidden data string for awk to intercept and calculate
        echo "SIZE_STATS $orig_size $new_size"
        
        if [ "$REPLACE" = "true" ]; then
            rm "$filepath"
            echo "🗑️  Removed:   $filepath"
        fi
    else
        echo "❌ Failed:    $filepath" >&2
    fi
'

# Execute the command using a pipe and xargs for parallel processing.
eval "$FIND_CMD" | xargs -0 -P "$CORES" -I {} sh -c "$SCRIPT" _ {} | awk '
/^SIZE_STATS/ {
    orig_total += $2
    new_total += $3
    next # Skip printing this specific line
}
{ print } # Print all other lines (like ✅ Converted or 🗑️ Removed)
END {
    if (orig_total > 0) {
        saved = orig_total - new_total
        percent = (saved / orig_total) * 100
        
        printf "\n--------------------------------------\n"
        printf "📊 Total Original Size: %.2f MB\n", orig_total / 1048576
        printf "📊 Total WebP Size:     %.2f MB\n", new_total / 1048576
        if (saved > 0) {
            printf "🎉 Total Space Saved:   %.2f MB (%.1f%% reduction)\n", saved / 1048576, percent
        } else {
            printf "⚠️ Space Increased by:   %.2f MB\n", (new_total - orig_total) / 1048576
        }
        printf "--------------------------------------\n"
    } else {
        print "\nNo images were found or converted."
    }
}'