DEV Community: Ertugrul

From Lab to Code #4: Exploring Neural Network Efficiency with Python and PyTorch

Ertugrul — Mon, 09 Nov 2026 22:18:11 +0000

A larger neural network can often achieve better accuracy.

But does that always make it the better model?

When working with neural networks, it is easy to focus on a single metric: accuracy. We train a model, evaluate it on a test dataset, and compare the percentage of correct predictions.

However, this leaves out an important engineering question:

How much computation do we need to achieve that accuracy?

A small model might be slightly less accurate but require significantly fewer operations. Depending on the application, that trade-off can matter more than achieving the highest possible score.

For the fourth project in my From Lab to Code series, I wanted to explore this relationship by building an interactive environment for experimenting with convolutional neural networks.

The result is Neural Network Efficiency Lab, a Python and PyTorch application that compares three independently trained CNN models, visualizes their predictions, and shows how architectural decisions affect computational cost.

Rather than building another digit-recognition demo, the goal was to investigate a more interesting question:

How small can a neural network be while still delivering useful classification accuracy?

The Idea: Accuracy Is Only Half the Story

For this experiment, I used the MNIST handwritten-digit dataset.

MNIST contains grayscale images of handwritten digits from 0 to 9. Each image has a resolution of 28 × 28 pixels.

It is a relatively simple classification problem, which makes it useful for comparing small neural networks without requiring a large training infrastructure.

I designed three convolutional neural networks with increasing capacity:

Micro CNN: A very small network designed for a restricted computation budget.
Compact CNN: A moderately sized network with more convolutional channels.
Wide CNN: A larger network intended to investigate the accuracy gained from additional computation.

All three use the same basic architecture, dataset, and training procedure.

The primary difference is the number of convolutional channels.

This makes it easier to observe how increasing model capacity affects both accuracy and computational requirements.

The project also includes an interactive interface where users can select trained models, draw digits, inspect predictions, visualize feature maps, and experiment with hypothetical CNN architectures.

1. Understanding the CNN Architecture

A convolutional neural network processes an image by applying learned filters to local regions.

Unlike a fully connected layer, where every output depends on every input, a convolutional layer reuses small filters across different image positions.

These filters can learn patterns such as edges, strokes, or more complex arrangements of local features.

For this project, I implemented a deliberately small architecture:

Input Image
   1 × 28 × 28
        |
        v
Convolution 1
        |
       ReLU
        |
     MaxPool
        |
        v
Convolution 2
        |
       ReLU
        |
     MaxPool
        |
        v
      Flatten
        |
        v
   Linear Layer
        |
        v
    10 Logits

The two convolutional layers extract features, while max pooling reduces the spatial resolution.

Finally, a fully connected layer maps the extracted representation to ten output values, one for each digit.

The implementation uses PyTorch:

class DigitCNN(nn.Module):
    def __init__(self, config):
        super().__init__()

        k = config.kernel

        self.conv1 = nn.Conv2d(
            1, config.c1, k, padding=k // 2
        )
        self.pool1 = nn.MaxPool2d(2)

        self.conv2 = nn.Conv2d(
            config.c1, config.c2, k, padding=k // 2
        )
        self.pool2 = nn.MaxPool2d(2)

        self.head = nn.Linear(
            config.c2 * 7 * 7, 10
        )

    def forward(self, x):
        x = self.pool1(
            torch.relu(self.conv1(x))
        )
        x = self.pool2(
            torch.relu(self.conv2(x))
        )

        return self.head(torch.flatten(x, 1))

The output consists of ten logits, which are unnormalized classification scores.

During training, these logits are passed to PyTorch's CrossEntropyLoss.

During inference, softmax converts them into a probability distribution over the ten classes:

P(class i) = exp(logit_i) / Σ exp(logit_j)

The predicted digit is the class with the highest probability.

These probabilities are useful for inspecting the model's predictions, although they should not automatically be interpreted as perfectly calibrated confidence estimates.

Why Change the Number of Channels?

The number of convolutional channels determines how many filters a layer learns.

A layer with more channels can represent a larger collection of features.

However, more channels also mean additional learned parameters and arithmetic operations.

This creates an interesting trade-off.

A larger network may learn more useful features and improve classification accuracy, but the improvement might be relatively small compared with the additional computation.

To investigate this, I kept the architecture structure consistent while changing its channel widths.

2. Measuring Computational Cost with MACs

Accuracy is relatively easy to understand.

We count the number of correct predictions and divide by the total number of evaluated examples:

Accuracy = Correct Predictions / Total Predictions

But how should we measure the computational cost of a neural network?

One useful approximation is the number of multiply-accumulate operations, or MACs.

A multiply-accumulate operation combines multiplication and addition:

accumulator += weight × input

Neural networks perform large numbers of these operations in convolutional and fully connected layers.

Counting MACs provides a hardware-independent estimate of some of the arithmetic work required for a forward pass.

Calculating Convolutional MACs

For a standard convolutional layer, the MAC count depends on the output dimensions, input channels, output channels, and kernel size.

A simplified formula is:

MACs = H_out × W_out × C_out × C_in × K²

where:

H_out and W_out are the output feature-map dimensions.
C_in is the number of input channels.
C_out is the number of output channels.
K is the width of a square convolution kernel.

In our architecture, the input has one channel and a resolution of 28 × 28.

The first convolution preserves the spatial resolution through padding.

After the first pooling operation, the image representation becomes 14 × 14.

After the second pooling operation, it becomes 7 × 7.

For convolutional channel counts C1 and C2, and kernel size K, the estimated costs are:

Conv1 = 28 × 28 × C1 × K²

Conv2 = 14 × 14 × C1 × C2 × K²

Dense = 7 × 7 × C2 × 10

Total MACs = Conv1 + Conv2 + Dense

I implemented this directly in Python:

def mac_breakdown(cfg):
    k2 = cfg.kernel ** 2

    conv1 = 28 * 28 * cfg.c1 * k2
    conv2 = 14 * 14 * cfg.c1 * cfg.c2 * k2
    linear = 7 * 7 * cfg.c2 * 10

    return {
        "conv1": conv1,
        "conv2": conv2,
        "linear": linear,
        "total": conv1 + conv2 + linear,
    }

This makes it possible to calculate the theoretical arithmetic cost of a model without executing it.

An Important Limitation

MACs are not the same as inference latency.

The calculation does not include operations such as ReLU, pooling, softmax, memory access, or data movement.

It also does not account for hardware-specific optimizations or parallel execution.

Consequently, a model with fewer MACs is not guaranteed to be faster on every processor or GPU.

For this project, MACs provide a transparent way to compare architectural complexity, not a benchmark of actual deployment performance.

3. Three Models, One Classification Task

With the architecture and cost calculation in place, I created three CNN configurations.

Model	Conv Channels	Parameters	MACs / Image
Micro CNN	3 → 6	3,148	55,860
Compact CNN	8 → 16	9,098	290,080
Wide CNN	16 → 32	20,490	1,031,744

All three use 3 × 3 convolution kernels.

The difference in computational cost is substantial.

The Wide CNN requires approximately 18.5 times as many MACs as the Micro CNN.

But does it achieve 18.5 times better classification performance?

Of course, accuracy cannot scale in that way. Once a model is already performing well, each additional improvement becomes harder to achieve.

The more useful question is how much accuracy we gain in exchange for that increased cost.

To answer it, the models need to be trained and evaluated under comparable conditions.

4. Training and Evaluating the Models

For a fair comparison, I used the same training procedure for all three architectures.

The official MNIST dataset was divided into:

Split	Images	Purpose
Training	54,000	Learn model parameters
Validation	6,000	Select the best training checkpoint
Test	10,000	Final evaluation

The validation set was created from the official MNIST training split.

The official test set was kept separate and used only for the final evaluation.

This distinction matters because selecting a model based on its test accuracy would introduce information leakage into the evaluation process.

Training Configuration

The models were trained using:

Optimizer: Adam
Learning rate: 0.001
Batch size: 256
Loss function: Cross-entropy
Training duration: 4 epochs
Random seed: 2026

For each model, I selected the checkpoint with the highest validation accuracy and then evaluated it on the official 10,000-image test set.

The implementation uses the standard PyTorch training sequence:

optimizer.zero_grad(set_to_none=True)

logits = model(images)

loss = criterion(logits, labels)

loss.backward()

optimizer.step()

Cross-entropy provides a differentiable objective, while backpropagation calculates gradients for the trainable parameters.

Adam uses these gradients to update the network weights.

The key benefit of keeping the training procedure consistent is that we can focus on how changes to the architecture affect the observed results.

However, the experiment uses only one training run per architecture. It is not a statistical comparison across multiple random seeds.

5. Experimental Results: More Computation, Smaller Gains

After training, the three models achieved the following results:

Model	Test Accuracy	MACs / Image
Micro CNN	96.67%	55,860
Compact CNN	97.92%	290,080
Wide CNN	98.63%	1,031,744

All accuracy values come from the held-out official MNIST test set.

These results reveal the central trade-off behind the project.

Micro vs. Compact

Moving from Micro to Compact increases the cost from 55,860 to 290,080 MACs.

That is approximately 5.2 times the computation.

The test accuracy improves from 96.67% to 97.92% — a gain of 1.25 percentage points.

Micro vs. Wide

Moving from Micro to Wide requires approximately 18.5 times the computation.

Yet accuracy improves by only 1.96 percentage points, from 96.67% to 98.63%.

This does not mean the larger model is useless.

For some applications, reducing the error rate can be extremely valuable, even if the improvement in accuracy appears small.

But it does show why accuracy should not be considered in isolation.

The best model depends on the available resources and the requirements of the application.

A Constrained-Compute Experiment

To make the trade-off more concrete, I introduced an illustrative budget of 75,000 MACs per image.

Under this constraint:

Micro CNN fits within the budget.
Compact CNN exceeds the budget.
Wide CNN exceeds the budget by a much larger margin.

The Micro CNN achieves 96.67% test accuracy while requiring only 55,860 MACs.

In this particular experiment, it provides a strong result under the selected arithmetic budget.

The 75,000-MAC threshold is an educational design constraint rather than a limit derived from real hardware.

The experiment demonstrates how a computational budget can influence architecture selection.

It does not establish which network would be fastest on a particular CPU, GPU, or embedded device.

6. Making the Experiments Interactive

After training the models, I wanted to make the results easier to explore.

A table of numbers can show that one network is larger than another.

But an interactive application can help explain what those differences mean.

For the frontend, I created a browser interface connected to a local Python backend using FastAPI.

The backend loads the saved PyTorch model checkpoints and performs inference.

The browser displays the predictions, model metrics, and visualizations.

Comparing the Models

The first part of the application compares Micro, Compact, and Wide CNN.

Users can inspect each model's:

Test accuracy.
Number of parameters.
Estimated MAC count.
Architecture configuration.

An accuracy-versus-computation visualization makes the trade-off easier to see.

Instead of considering accuracy and model size separately, users can observe how much additional computation is associated with each improvement.

Drawing a Digit

The application also includes an interactive drawing canvas.

Users can draw a handwritten digit using their mouse and send it to one of the trained models.

The image is converted into a 28 × 28 grayscale representation and normalized using the same convention as the training data.

The selected model produces ten logits.

Softmax converts them into class probabilities, allowing the interface to display the predicted digit and its probability distribution.

The application also includes twenty attributed MNIST test examples for trying the models on actual dataset samples.

An interesting limitation appears when using the drawing canvas.

Handwritten digits produced with a mouse can look quite different from images in MNIST.

Differences in stroke width, positioning, and drawing style can affect the prediction.

A high accuracy on the MNIST test dataset therefore does not guarantee equally high accuracy on arbitrary user drawings.

This is a small example of distribution shift: a model is evaluated on inputs that differ from those it encountered during training.

Looking Inside the CNN

I also wanted to show something beyond the final classification result.

What does a convolutional layer actually produce?

To investigate this, the application extracts intermediate feature maps from the first two convolutional layers.

For a selected input, users can inspect visualizations of the learned activations.

The model returns both its final classification logits and intermediate features:

f1 = torch.relu(self.conv1(x))
x = self.pool1(f1)

f2 = torch.relu(self.conv2(x))
x = self.pool2(f2)

logits = self.head(torch.flatten(x, 1))

return logits, (f1, f2)

The application displays a selection of feature channels from each layer.

These visualizations provide a way to observe how the input is transformed as it passes through the network.

However, the displayed feature maps are normalized individually for visualization.

This means their brightness should not be interpreted as a directly comparable activation magnitude across channels.

7. Exploring Architectures Without Retraining

One of the more useful features of the project is the Architecture Sandbox.

Here, users can change the number of convolutional channels and the kernel size.

The application immediately recalculates:

Number of trainable parameters.
Estimated MACs for each layer.
Total arithmetic cost.
Whether the hypothetical architecture fits the selected MAC budget.

This makes the relationship between architecture and computation directly observable.

For example, increasing the output channels of the second convolution affects the number of operations required by that layer.

Increasing the kernel size also increases computation because each output value depends on more input positions.

But there is an important separation between the architecture calculator and the trained model comparison.

Changing the architecture does not automatically tell us its accuracy.

An untrained network has no measured classification performance.

To evaluate a new architecture, we would need to train it, select an appropriate checkpoint using validation data, and measure its performance on held-out test data.

Therefore, the Architecture Sandbox only reports properties that can be calculated analytically.

It does not invent an accuracy score for hypothetical models.

This distinction was important to preserve because the project is intended to demonstrate actual engineering trade-offs, not simulated performance claims.

8. What the Experiment Does and Does Not Prove

The results suggest that a small CNN can achieve strong MNIST classification accuracy with a relatively low arithmetic cost.

However, several limitations are worth considering.

First, the models were trained using a single random seed.

A broader comparison would require repeated training runs to estimate performance variation.

Second, the experiment uses only three configurations of the same basic architecture.

It does not establish the optimal CNN for MNIST or the best architecture under a particular computation budget.

Third, MACs estimate only part of the computational work.

Actual inference speed depends on hardware, software libraries, memory behavior, and other implementation details.

Finally, MNIST is a relatively simple classification benchmark.

The relationship between model capacity and accuracy may look very different for larger images, more complex datasets, or real-world deployment conditions.

The purpose of this project is therefore not to introduce a new neural network architecture or claim state-of-the-art performance.

It is to build a transparent, reproducible experiment in which the trade-offs between network size, arithmetic cost, and classification performance can be explored.

What I Learned

This project reinforced a few important ideas about machine learning engineering.

First, accuracy alone is not enough to evaluate a model.

Two models can have similar accuracy while requiring very different amounts of computation.

Depending on the application, the smaller model may be the more practical choice.

Second, the relationship between model capacity and accuracy is not linear.

In this experiment, increasing computational cost substantially produced progressively smaller accuracy gains.

The largest model performed best on the test set, but the smallest model was much more computationally economical.

Third, mathematical cost estimates are useful, but they must be interpreted correctly.

MAC counts make it possible to compare arithmetic complexity without hardware-dependent measurements.

However, they should not be confused with actual runtime performance.

Fourth, intermediate visualizations make neural networks easier to understand.

Inspecting convolutional feature maps helps connect the mathematical architecture to the representations produced during inference.

And finally, a clear separation between measured results and hypothetical configurations is essential.

We can calculate the theoretical cost of a network architecture immediately.

But we cannot know how accurately that architecture will classify images until it has been properly trained and evaluated.

That difference is central to designing reliable machine learning experiments.

Final Thoughts

For this fourth From Lab to Code project, I wanted to investigate a question that extends beyond handwritten-digit recognition:

How do we balance model accuracy against computational requirements?

By training three CNN architectures under comparable conditions, measuring their classification performance, and calculating their arithmetic costs, I built a small environment for exploring this trade-off.

The interactive application adds another perspective by allowing users to compare actual models, classify their own drawings, inspect intermediate feature maps, and experiment with architectural changes.

The most interesting result was that the smallest network achieved 96.67% test accuracy using only 55,860 estimated MACs per image.

A significantly larger network improved accuracy to 98.63%, but required approximately 18.5 times more MACs.

Neither model is universally better.

The appropriate choice depends on the accuracy requirements, the computational constraints, and the environment in which the model will be used.

That is the engineering idea I wanted to make visible.

And it follows the same motivation behind From Lab to Code:

Build something small, understand the underlying principles, make the results observable, and share the implementation.

The full source code, trained model checkpoints, reproducible experiment results, tests, and setup instructions are available on GitHub:

Explore Neural Network Efficiency Lab on GitHub

The implementation and interface were developed independently. The project uses the public MNIST dataset with separate attribution for the included samples; no university course code or instructional materials are redistributed.

Thanks for reading!

From Lab to Code #3: Building an Interactive Robot Cell with Python and Three.js

Ertugrul — Mon, 09 Nov 2026 21:19:52 +0000

In an automated production line, a robotic arm might look like the most interesting part of the system.

But moving the arm is only one part of the problem.

How does the robot know when an object has arrived? How does it decide where to place it? And how do the conveyor, sensors, gripper, and controller coordinate their actions?

More importantly, what happens when a sensor is disconnected or connected to the wrong input?

These questions involve several fundamental concepts in robotics and industrial automation: kinematics, finite state machines, sensor feedback, and digital I/O communication.

For the third project in my From Lab to Code series, I decided to explore these concepts by building a small interactive robot-cell simulation.

The result is Robot Cell Playground, a Python-controlled robotic sorting cell with a 3D interface built using Flask, HTML, CSS, JavaScript, and Three.js.

The interesting part is not just watching a robot sort colored boxes. Users can modify the digital connections between components, introduce faults, and observe how those changes affect the entire system.

The Idea: A Small Automated Sorting Cell

The simulation represents a simple production scenario.

A conveyor transports colored boxes toward a robotic arm. Once a box reaches the pickup position, the controller uses simulated sensors to identify it and determine its destination.

The robot then picks up the box, transfers it to the correct location, and returns to its initial position.

There are three possible destinations: red, green, and blue.

Under normal conditions, each box should reach the destination corresponding to its color.

To make this possible, the application combines several components:

A three-degree-of-freedom robotic arm.
A conveyor and object generator.
Idealized position and color sensors.
A finite-state-machine controller.
Configurable digital input/output connections.
A 3D visualization of the complete cell.

The project uses a simplified geometric model rather than a full industrial physics simulator.

This was a deliberate decision. I wanted to focus on understanding how the individual components interact without introducing the complexity of a complete robotics framework.

1. Robot Kinematics: From Coordinates to Joint Angles

Before controlling a robot, we need a mathematical representation of its movement.

In robotics, kinematics describes positions, orientations, and motion without considering the forces that produce them.

Two important problems are forward kinematics and inverse kinematics.

Forward Kinematics

Forward kinematics answers a straightforward question:

If we know the robot's joint angles, where is its end effector?

For this project, I implemented a simplified robotic arm with three degrees of freedom:

Base rotation (yaw).
Shoulder rotation.
Elbow rotation.

The arm consists of two links moving in a vertical plane, while the base rotates that plane around the vertical axis.

Let the upper-arm length be L1, the forearm length be L2, and the joint angles be q1, q2, and q3.

The horizontal distance from the base is:

r = L1*cos(q2) + L2*cos(q2 + q3)

The vertical position is:

z = shoulder_height
    + L1*sin(q2)
    + L2*sin(q2 + q3)

Using the base rotation, we obtain the horizontal coordinates:

x = base_x + r*cos(q1)
y = base_y + r*sin(q1)

The corresponding Python implementation is relatively compact:

def forward_kinematics(angles):
    yaw, shoulder, elbow = angles

    r = (
        UPPER_ARM * math.cos(shoulder)
        + FOREARM * math.cos(shoulder + elbow)
    )

    z = (
        SHOULDER_HEIGHT
        + UPPER_ARM * math.sin(shoulder)
        + FOREARM * math.sin(shoulder + elbow)
    )

    return (
        BASE_X + r * math.cos(yaw),
        BASE_Y + r * math.sin(yaw),
        z,
    )

This allows the simulation to calculate the wrist position from the current joint configuration.

Inverse Kinematics

The opposite problem is more useful when commanding the robot to move somewhere.

Suppose a box has arrived at a known pickup coordinate.

We know where the robot should move, but we do not yet know the joint angles required to reach that position.

This is the inverse kinematics problem.

For the two-link arm, we can calculate the elbow angle using the law of cosines.

First, we determine the horizontal distance r and height h relative to the shoulder:

r = sqrt((x - base_x)^2 + (y - base_y)^2)

h = z - shoulder_height

Then:

cos(q3) = (r^2 + h^2 - L1^2 - L2^2) / (2*L1*L2)

q3 = -acos(cos(q3))

Once the elbow angle is known, the shoulder angle can be calculated:

q2 = atan2(h, r)
     - atan2(L2*sin(q3), L1 + L2*cos(q3))

Finally:

q1 = atan2(y - base_y, x - base_x)

The implementation selects one elbow configuration and checks whether the requested target lies within the robot's geometric workspace.

A useful test is to apply inverse kinematics to a target and then reconstruct the position using forward kinematics.

target = (0.72, 1.05, 0.92)

angles = inverse_kinematics(target)
reconstructed = forward_kinematics(angles)

The reconstructed coordinates should match the target within floating-point precision.

This gives us a simple mathematical consistency check.

Of course, reaching a coordinate geometrically does not mean the movement is physically safe. Real robots must also consider collisions, mechanical joint limits, actuator dynamics, and other constraints.

For this project, the geometric model is enough to explore the relationship between joint angles and target positions.

2. Finite State Machines: Teaching the Robot What to Do Next

Kinematics tells us how to reach a position.

But it does not tell us when the robot should move there.

A sorting cell must coordinate multiple operations in a specific order.

The robot should not attempt to pick up a box before it arrives. It should not transfer the box before activating the gripper. And it should not generate a new box while the previous sorting operation is still in progress.

For this, I implemented a finite state machine (FSM).

An FSM represents a system using a finite number of states and transitions between them.

In Robot Cell Playground, the normal operating sequence is:

IDLE
  |
  v
CONVEYING
  |
  v
DETECTED
  |
  v
APPROACH
  |
  v
PICKING
  |
  v
LIFTING
  |
  v
TRANSFER
  |
  v
PLACING
  |
  v
RETRACTING
  |
  v
RETURNING
  |
  +------> IDLE

Each state has a specific responsibility.

For example, CONVEYING advances the box toward the pickup point, while DETECTED confirms that the necessary sensor information has been received.

The movement states handle approaching, picking, lifting, transferring, and placing the box.

A separate FAULT state handles certain failed operations.

Implementing the State Machine

The simulation is controlled by the RobotCell class in Python.

The controller maintains the current phase, box position, robot angles, sensor information, wiring configuration, and sorting statistics.

A particularly interesting part is the conveyor logic:

if self.phase == "CONVEYING":

    if self._inputs()["Belt.OnOff"] and self.box is not None:
        self.box["x"] = min(
            PICKUP_X,
            self.box["x"] + 1.20 * dt
        )

    inputs = self._inputs()

    if (
        inputs["Robot.ItemAvailable"]
        and item_present(self.box)
    ):
        matched = [
            c for c in COLORS
            if inputs[f"Robot.Color{c.capitalize()}"]
        ]

        if len(matched) == 1:
            self.detected_color = matched[0]
            self.phase = "DETECTED"

Notice that the conveyor does not move unconditionally.

It moves only when the corresponding digital input is active.

Similarly, the controller proceeds to the detection state only when an object is available and exactly one color input is active.

These conditions become particularly important when we start modifying the wiring.

Making the Motion Smooth

For the robot's joint movements, I used a cubic smoothstep interpolation:

s(t) = 3t² - 2t³

where t varies from 0 to 1 during a movement phase.

Each joint angle is interpolated as:

q(t) = q_start + s(t)*(q_target - q_start)

This produces smoother visual transitions than immediately jumping between configurations.

It is not a physically constrained trajectory planner, but it provides a simple way to animate the robot while keeping the motion calculations inside the Python controller.

The important distinction is that kinematics determines where the robot should move, while the state machine determines what the robot should do next.

3. Digital I/O: Connecting the Components

This became one of the most interesting parts of the project.

An automated robot cell consists of multiple components that need to communicate.

The conveyor needs to receive a start command. The robot needs to know when a box arrives. The gripper must receive an activation signal, and the controller needs information from the color sensor.

In this simulation, these interactions are represented using digital input/output signals.

A digital signal has two possible logical values:

LOW  = 0
HIGH = 1

A signal travels from an output to an input.

For example:

Robot.StartStop  ------>  Belt.OnOff

Here, the robot controller produces a command, and the conveyor receives it.

The same principle applies to the simulated gripper:

Robot.Grasp  ------>  Gripper.Vacuum

Sensor communication flows in the other direction:

PositionSensor.Detect
          |
          v
Robot.ItemAvailable

In this case, the sensor provides the output, while the robot controller receives it.

Making the Connections Editable

Instead of hardcoding every connection directly into the controller, I implemented an independent digital I/O routing system.

The application stores a mapping between device inputs and their connected outputs.

For example:

DEFAULT_CONNECTIONS = {
    "Source.Trigger": "Robot.Generate",
    "Belt.OnOff": "Robot.StartStop",
    "Gripper.Vacuum": "Robot.Grasp",

    "Robot.ItemAvailable": "PositionSensor.Detect",

    "Robot.ColorRed": "ColorSensor.Red",
    "Robot.ColorGreen": "ColorSensor.Green",
    "Robot.ColorBlue": "ColorSensor.Blue",
}

This is a shortened version of the default configuration. The complete system also includes signals for the three sorting destinations.

The key is that the controller does not directly read the physical source signals.

Instead, it receives values through the current connection mapping.

The IOBoard class resolves these connections using:

def resolve(self, outputs: dict[str, bool]) -> dict[str, bool]:
    return {
        p.id: bool(
            outputs.get(self.routes.get(p.id, ""), False)
        )
        for p in INPUTS
    }

For each input, the function finds the connected output and retrieves its logical value.

If the input has no valid connection, its value becomes False.

This introduces an important distinction:

A controller output can be HIGH while the corresponding device input remains LOW.

For example, the robot might send a command to start the conveyor, but the conveyor will not respond if the connection is missing.

The Interactive Wiring Lab

To make this behavior visible, I added an interactive wiring panel to the application.

The panel contains ten output ports and ten input ports.

Users can connect outputs to inputs, disconnect existing connections, restore the default configuration, and inspect the live digital signal levels.

The connections are visualized as lines between ports.

HIGH and LOW signals are displayed separately from the connection status, so an inactive signal is not confused with a disconnected wire.

The Python controller also provides diagnostic messages explaining which signals are missing during particular operations.

This is a simplified logical routing model, not a complete PLC programming environment.

However, it gives users a way to explore a central principle of automation:

The behavior of a system depends not only on the commands being generated, but also on how those commands and sensor signals are connected.

4. Fault Injection: What Happens When the Wiring Is Wrong?

Once the connections became editable, I wanted to explore another question:

What happens if we deliberately connect something incorrectly?

This turns the simulation into a small fault-injection environment.

Instead of only observing the correct sorting sequence, we can investigate why the system stops working or produces incorrect results.

Experiment 1: Disconnecting the Conveyor

Under normal conditions:

Robot.StartStop  ------>  Belt.OnOff

When the controller enters the CONVEYING state, it activates its StartStop output.

Now imagine disconnecting that connection.

The output still becomes HIGH, but the conveyor input remains LOW.

The result is straightforward: the box stays at the beginning of the conveyor.

The controller remains in the conveying phase because the box never reaches the pickup position.

The interesting part is that the controller still issues the correct command.

The problem is the missing connection between the controller and the device.

Experiment 2: Disconnecting the Position Sensor

Normally, the position sensor sends a detection signal to the robot:

PositionSensor.Detect
          |
          v
Robot.ItemAvailable

Now disconnect this signal.

The conveyor still transports the box toward the pickup point.

But when the box arrives, the robot controller does not receive the corresponding detection signal.

As a result, the controller cannot proceed to the pickup operation.

The robot waits even though the box has physically reached the correct location in the simulated scene.

This demonstrates how missing feedback can prevent an otherwise functioning system from progressing.

Experiment 3: Disconnecting the Gripper

The gripper is activated through:

Robot.Grasp  ------>  Gripper.Vacuum

If this connection is removed, the robot can still approach the box.

However, when it attempts to pick up the object, the gripper does not receive the activation signal.

In this implementation, the controller recognizes the missing signal and enters the FAULT state.

The simulation must be reset before another sorting cycle can begin.

This is a simplified fault-handling mechanism, but it clearly illustrates the dependency between control commands and actuator inputs.

Experiment 4: Swapping the Color Sensor Connections

This was my favorite experiment.

Imagine that the simulated color sensor correctly identifies a red box.

The sensor's red output becomes HIGH.

Now suppose the red and blue sensor connections are swapped:

ColorSensor.Red
          |
          v
Robot.ColorBlue

ColorSensor.Blue
          |
          v
Robot.ColorRed

The actual box is still red.

The color sensor still detects red.

But the controller receives that signal through its blue input.

Consequently, it identifies the object as blue and selects the blue destination.

The robot then picks up the red box and transfers it into the blue bin.

The application records this as a mis-sort.

This is particularly interesting because the robot's movement can be geometrically correct while its overall decision is wrong.

The kinematics are still functioning. The state machine is still progressing. The robot reaches the destination selected by the controller.

The error originates from the information entering the controller through an incorrect connection.

Comparing the Fault Scenarios

Experiment	Result
Default wiring	Boxes reach their matching bins
Conveyor disconnected	Box does not advance
Position sensor disconnected	Controller waits for detection
Gripper disconnected	Gripper fault is triggered
Red/blue inputs swapped	Boxes can reach the wrong destination

These scenarios are also covered by automated tests.

For example, one integration test verifies that a red box incorrectly routed to the blue destination increments the mis-sort counter:

self.assertEqual(cell.missorted, 1)
self.assertEqual(cell.pick_count, 0)
self.assertEqual(cell.counts["red"], 0)
self.assertEqual(cell.bin_contents["blue"]["red"], 1)

Instead of merely checking whether the application displays an error, the test verifies that the simulated sorting behavior actually changed.

For me, this is one of the most valuable parts of the project.

A small wiring error can affect the outcome of an entire automation process, even when the underlying movement algorithms are functioning correctly.

5. Visualizing the System with Three.js

After implementing the Python controller, I wanted to make its behavior visible and interactive.

For the frontend, I used HTML, CSS, JavaScript, and Three.js.

The backend uses Flask to expose the simulation state to the browser.

One design decision was particularly important: Python remains responsible for the robot's behavior.

The frontend does not independently decide when the robot should move, when a box has been detected, or which destination should be selected.

Instead, it renders the state calculated by Python.

The architecture looks like this:

Browser Interface
        |
        | HTTP / JSON
        v
     Flask API
        |
        v
 Python Controller
        |
        +-- Kinematics
        +-- State Machine
        +-- Sensors
        +-- Digital I/O Routing
        |
        v
 Simulation State
        |
        v
 Three.js Visualization

You can also inspect the system architecture diagram included in the repository.

The browser periodically sends simulation-step requests to Flask.

Python advances the controller and returns the updated state, including joint positions, box coordinates, sensor values, connection states, and sorting statistics.

Three.js uses this information to update the scene.

The user can observe the robotic arm, conveyor, colored boxes, and sorting destinations in 3D.

The interface also allows camera rotation, zooming, simulation-speed adjustments, and selection of the next generated box color.

Below the 3D scene, the Wiring Lab displays the digital connections and their live signal levels.

An event stream provides additional information about state transitions, detection events, successful sorting operations, and faults.

This separation between simulation and visualization has another advantage: the Python control logic can be tested independently of the browser.

It also makes the system easier to understand. The 3D scene shows what happens, while the controller determines why it happens.

6. Reproducible Results and Testing

An interactive simulation is useful for exploring individual scenarios.

However, I also wanted to verify that the underlying controller behaves consistently without manually operating the interface.

For this reason, I implemented a deterministic demonstration using a fixed random seed.

The simulation generates and sorts twelve colored boxes using the default connections.

The recorded result is:

Measurement	Result
Successfully sorted boxes	12
Red	4
Green	2
Blue	6
Simulated elapsed time	112.32 seconds

The random seed for this run was 13.

These values represent simulated outcomes, not measurements from a physical production line.

The elapsed time is measured in simulation time, so it should not be interpreted as an industrial throughput benchmark.

Beyond this demonstration, the project includes unit and integration tests covering kinematics, sensor behavior, sorting cycles, input validation, digital wiring, and fault scenarios.

An important test checks that forward and inverse kinematics produce consistent coordinates.

Other tests verify that missing connections prevent operations from progressing, invalid connections are rejected, and swapped color inputs produce an actual mis-sort.

These tests do not make the application hardware-ready, but they help ensure that the simplified model follows its intended rules.

7. What This Simulation Does Not Model

Robot Cell Playground is an educational simulation, not a physics-accurate industrial robot controller.

The robotic arm has three geometric degrees of freedom and uses analytical kinematics.

The system does not model actuator forces, motor torque, realistic gripper contact, collisions, detailed joint constraints, or obstacle avoidance.

The sensors are idealized. The color sensor returns a discrete color signal instead of processing real camera data.

Similarly, the digital I/O connections model logical Boolean values, without electrical characteristics, signal propagation delays, or PLC scan cycles.

The robot's motion uses smooth joint-angle interpolation rather than a complete industrial trajectory planner.

These limitations are intentional.

The objective is to make specific engineering concepts easier to observe and experiment with, not to reproduce the full complexity of a real manufacturing environment.

What I Learned

This project helped me connect several engineering concepts that are often studied independently.

Robotic movement is only one part of automation.

Forward and inverse kinematics provide a mathematical way to position the robot, but they do not determine when a conveyor should stop, whether a box is available, or which destination the robot should select.

That requires a control strategy.

Finite state machines make the behavior easier to understand.

Breaking the sorting process into distinct states creates clear responsibilities and transition conditions.

It also makes debugging more manageable because the controller's current state provides information about what it is trying to accomplish.

Digital connections are part of the system's behavior.

One of the biggest takeaways came from the Wiring Lab.

A controller may execute its programmed logic correctly and still produce the wrong result if its inputs contain incorrect information.

The swapped-color experiment demonstrates this directly: the robot follows its controller's decision, but the decision itself is based on an incorrectly routed signal.

Fault injection makes hidden dependencies visible.

When everything works, the importance of individual sensor and actuator connections is easy to overlook.

Disconnecting them reveals which operations depend on which signals.

Finally, separating the Python simulation from the Three.js visualization made the project easier to test and reason about.

The controller is responsible for the logic, while the frontend provides an interactive way to observe the results.

Final Thoughts

With Robot Cell Playground, I wanted to explore how relatively simple mathematical and programming concepts can work together to form an automated system.

The project began with a robotic arm and a conveyor, but the more interesting questions appeared when I started considering communication between components.

What happens when the controller receives no signal? What if it receives the wrong one? Can the robot complete a movement correctly but still make an incorrect sorting decision?

By combining kinematics, finite state machines, editable digital I/O connections, and fault injection, the simulation provides a small environment for investigating these questions.

The project is intentionally limited in scope. It is not designed to replace industrial robotics software or operate physical machinery.

Instead, it follows the idea behind From Lab to Code:

Build something small, understand the engineering behind it, make the behavior observable, and share the implementation.

The complete source code, technical documentation, setup instructions, and reproducible experiments are available in the GitHub repository:

Explore Robot Cell Playground on GitHub

The implementation and visualizations are original and independently developed. No university handouts, CIROS assets, proprietary robot models, or restricted instructional materials are redistributed.

Thanks for reading!

From Lab to Code #2: Exploring Spatial Audio with Python and SciPy

Ertugrul — Tue, 27 Oct 2026 12:00:32 +0000

Most of us can recognize where a sound is coming from without consciously thinking about it.

If someone speaks to our left, we naturally turn in that direction. If a car passes behind us, we can often estimate its movement without seeing it.

But how does our auditory system determine where a sound is located?

Interestingly, much of this ability depends on small differences between the signals arriving at our left and right ears.

A sound may reach one ear slightly earlier, or with a different intensity, than the other.

These differences can be analyzed using signal processing techniques such as cross-correlation, convolution, and impulse response analysis.

For the second project in my From Lab to Code series, I wanted to explore these concepts through an interactive Python application.

The result is Spatial Audio Playground: a small experimental application that lets users position virtual sound sources, compare mono and binaural audio, and visualize some of the signals responsible for directional hearing.

GitHub repository: https://github.com/Ertugrulmutlu/from-lab-to-code

Project 02 — Spatial Audio Playground: https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/02-spatial-audio

What Are We Building?

The application explores four main ideas:

Cross-correlation to measure the relative delay between signals.
Interaural Time Difference (ITD) and Interaural Level Difference (ILD) to understand directional hearing.
Binaural synthesis to generate separate audio signals for the left and right ears.
Interactive spatial audio using Python, SciPy, Streamlit, and a small JavaScript-based soundstage.

Users can move two virtual sound sources around a listener, adjust their positions and gains, and compare the resulting audio through headphones.

The project uses procedurally generated audio and educational impulse-response models by default.

No pretrained models, external audio datasets, or API calls are required.

1. Cross-Correlation: Detecting Delays Between Signals

Before exploring spatial audio, we need a way to measure the relative timing of two signals.

Consider a simple example.

We have two discrete signals containing impulses:

The first signal has an impulse at sample index 5.
The second signal has impulses at indices 9 and 14, with amplitudes of 1.0 and 0.5.

The corresponding differences in sample positions are +4 and +9.

How can we detect these shifts automatically?

Understanding Cross-Correlation

Cross-correlation measures similarity between two signals as one is shifted relative to the other.

For discrete signals, one convention is:

R_yx[k] = Σ y[n] · conjugate(x[n-k])

The resulting function tells us how strongly the signals align at different sample lags.

For simple impulse signals, alignment produces distinct correlation peaks.

Implementing Cross-Correlation with SciPy

First, generate the signals:

import numpy as np
from scipy import signal

num_samples = 20

reference = signal.unit_impulse(
    num_samples, idx=5
)

shifted = (
    signal.unit_impulse(num_samples, idx=9)
    + 0.5 * signal.unit_impulse(
        num_samples, idx=14
    )
)

Next, calculate the correlation and its corresponding lags:

correlation = signal.correlate(
    shifted,
    reference,
    mode="full"
)

lags = signal.correlation_lags(
    len(shifted),
    len(reference),
    mode="full"
)

The correlation contains two nonzero peaks:

Lag	Correlation amplitude
+4	1.0
+9	0.5

The first peak is larger because the corresponding impulse has a higher amplitude.

An important detail is the order of the arguments.

In this example, correlate(shifted, reference) produces positive lags for impulses occurring later in the shifted signal.

Reversing the arguments changes the lag sign convention.

From Sample Lag to Time Delay

A sample shift can also be expressed as a time difference.

If the sampling frequency is fs, then:

delay = lag / fs

For example, at a sampling frequency of 44,100 Hz, a delay of four samples corresponds to approximately 0.091 milliseconds.

This becomes important when comparing the arrival times of audio signals at our two ears.

Key takeaway: Cross-correlation gives us a practical way to estimate relative timing differences, provided the signals contain sufficiently identifiable patterns.

2. How Do We Hear Direction? ITD and ILD

Our ears receive two slightly different versions of the same sound.

The differences between them provide important information about the location of a sound source.

Two particularly useful cues are:

Interaural Time Difference (ITD)

Imagine a sound source located to your left.

The sound generally reaches your left ear before your right ear because the path to the right ear is longer.

This arrival-time difference is called the Interaural Time Difference.

In the application, I define:

ITD = t_right - t_left

Therefore:

Positive ITD: the sound arrives at the left ear first.
Negative ITD: the sound arrives at the right ear first.
ITD near zero: both ears have approximately equal arrival times.

To estimate ITD, the project applies a low-pass filter to the left and right impulse responses before calculating their cross-correlation.

sos = signal.butter(
    4,
    1500,
    btype="lowpass",
    fs=44100,
    output="sos"
)

low_left = signal.sosfilt(
    sos, hrir[0]
)

low_right = signal.sosfilt(
    sos, hrir[1]
)

lags = signal.correlation_lags(
    len(low_right),
    len(low_left),
    mode="full"
)

correlation = signal.correlate(
    low_right,
    low_left,
    mode="full"
)

The implementation restricts the lag search to a physically relevant window of ±1 millisecond.

The lag corresponding to the highest correlation value within this window provides an estimate of the timing difference.

Interaural Level Difference (ILD)

Time is not the only difference between our ears.

The head also affects how much sound energy reaches each ear.

For some directions, the head partially blocks the sound travelling toward the opposite ear.

This effect is especially important at higher frequencies.

The resulting difference in sound level is called the Interaural Level Difference.

In the project, a broadband ILD estimate is calculated using the energy of the two impulse responses:

ILD = 10 · log10(E_right / E_left)

where:

E = Σ h[n]²

In Python:

energy_left = np.sum(hrir[0] ** 2)
energy_right = np.sum(hrir[1] ** 2)

ild_db = 10 * np.log10(
    energy_right / energy_left
)

A negative ILD means the right channel contains less impulse-response energy than the left channel.

This is a broadband estimate. In real acoustic systems, ILD depends strongly on frequency, so frequency-band analysis can provide more detailed information.

Why Both Cues Matter

ITD and ILD complement each other.

ITD is particularly useful for understanding low-frequency directional cues, while ILD becomes especially relevant at higher frequencies.

However, these two values alone cannot completely explain spatial hearing.

They do not reliably resolve all front/back or elevation ambiguities.

For that, we need to consider how the head, torso, and outer ears modify the sound spectrum.

Key takeaway: Spatial hearing depends on both when sound reaches each ear and how its level and spectrum change along the way.

3. Head-Related Impulse Responses: Modeling the Path to Our Ears

To simulate the sound arriving at each ear, we need to model how the human body modifies incoming audio.

This is where Head-Related Transfer Functions (HRTFs) and Head-Related Impulse Responses (HRIRs) become useful.

An HRTF describes the directional filtering of sound in the frequency domain.

An HRIR represents the corresponding impulse response in the time domain.

For each sound source direction, we need two impulse responses:

h_left[n] for the left ear.
h_right[n] for the right ear.

These responses describe how an incoming signal is transformed on its way to the two ears.

Generating Educational HRIRs

For this project, I implemented a small synthetic HRIR generator.

Instead of relying on a measured dataset, the default model approximates three effects:

Arrival-time differences between the ears.
Head-shadow attenuation.
Mild spectral coloration related to elevation.

The lateral direction is calculated using the source angles:

lateral = (
    np.sin(np.deg2rad(azimuth))
    * np.cos(np.deg2rad(elevation))
)

The application uses the following coordinate convention:

0°: front
+90°: left
-90°: right
±180°: behind

The synthetic model then converts this lateral position into an approximate sample delay.

It also reduces the far-ear amplitude to illustrate head-shadow effects.

This provides a controllable environment for investigating spatial cues without requiring external recordings.

An Important Limitation

The synthetic HRIR model is intentionally simplified.

Real HRIRs contain much more detailed information about reflections, diffraction, and resonances caused by an individual's anatomy.

Therefore, the built-in model is most useful for understanding basic left/right directional cues.

It should not be treated as a physically accurate or personalized 3D audio renderer.

For more realistic experiments, the application can optionally load compatible measured HRIR data stored in the SOFA (Spatially Oriented Format for Acoustics) format.

The current implementation uses the nearest available measurement direction rather than interpolating between measurements.

4. Binaural Synthesis: Turning Mono into Directional Stereo

Now we have the essential components:

A mono audio signal.
A left-ear impulse response.
A right-ear impulse response.

The next step is to combine them.

This is done using convolution.

For a mono input signal x[n], we calculate:

y_left[n] = x[n] * h_left[n]

y_right[n] = x[n] * h_right[n]

Here, * represents the convolution operation.

Each output contains a filtered version of the original sound, corresponding to a different ear.

Implementing Convolution with SciPy

The actual project uses scipy.signal.oaconvolve, which implements overlap-add convolution.

from scipy import signal
import numpy as np

def render_one(mono, hrir, gain_db=0.0):
    channels = [
        signal.oaconvolve(
            mono,
            hrir[ear],
            mode="full"
        )
        for ear in range(2)
    ]

    stereo = np.column_stack(channels)

    return stereo * (
        10.0 ** (gain_db / 20.0)
    )

The result is a stereo array containing separate left and right waveforms.

When these signals are played through headphones, the listener receives different directional information at each ear.

Combining Multiple Sound Sources

The application supports up to two independent sound sources.

Each source can have its own:

Audio recording.
Azimuth and elevation.
Gain.
HRIR pair.

Every mono source is processed separately.

The resulting stereo signals are then summed to create a binaural mix.

To make the mono/binaural comparison more consistent, the application applies one shared clipping-prevention gain to both outputs when necessary.

This avoids independently peak-normalizing the two versions, which could introduce an unnecessary gain difference.

It is important to note that a common gain does not guarantee equal perceived loudness.

Key takeaway: Convolution lets us transform ordinary mono audio into two direction-dependent ear signals using impulse responses.

5. Building the Interactive Spatial Audio Playground

Understanding the equations is useful, but I also wanted a way to experiment with them directly.

That became the main motivation behind the application's interface.

The interface is built using Streamlit, with an additional HTML, CSS, SVG, and JavaScript component for the interactive soundstage.

Moving Virtual Sound Sources

Instead of manually entering every angle, users can drag two sound-source markers around a listener.

Each marker represents an independent virtual audio source.

When a source is moved, its new azimuth is sent to the Python application.

The application selects or generates the corresponding impulse responses and renders new audio clips.

The soundstage also supports keyboard interaction and directional presets.

Importantly, this is offline rendering, not continuous real-time spatial audio.

Moving the markers changes the next generated clip rather than streaming a moving sound source.

Comparing Mono and Binaural Playback

One of the central features is a direct listening comparison.

The application produces two outputs from the same input sources:

Centered mono: A reference mix without separate left/right spatial filtering.

Binaural stereo: A direction-dependent mix created using individual impulse responses for each ear.

Users can listen to both versions and download the binaural WAV output.

Headphones are recommended because they deliver the two channels separately to the listener's ears.

Inspecting the Signals

The interface also displays:

Estimated ITD in milliseconds.
Estimated ILD in decibels.
Left and right HRIR waveforms.
The beginning of the rendered stereo waveform.

This allows users to connect the perceptual experience with the underlying signal-processing operations.

The application also includes a separate cross-correlation experiment and a short theory section.

Running the Project Locally

The complete implementation is available on GitHub:

https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/02-spatial-audio

You will need Python 3.11–3.13.

Clone the repository:

git clone https://github.com/Ertugrulmutlu/from-lab-to-code.git
cd from-lab-to-code/02-spatial-audio

Create a virtual environment:

python -m venv .venv

Install the dependencies:

python -m pip install -r requirements.txt

Launch the application:

python -m streamlit run app.py

The application opens in your browser, typically at http://localhost:8501.

You can immediately experiment with the built-in audio examples.

The project also supports uploading your own short WAV recordings and compatible SOFA datasets.

To execute the automated tests:

python -m unittest discover -s tests -v

The project includes 18 automated unit and integration tests covering signal processing, audio rendering, and related functionality.

The main implementation is organized into separate files:

correlation.py — cross-correlation and interaural cue estimation.
binaural.py — convolution, HRIR loading, and WAV handling.
audio_pipeline.py — rendering and mixing multiple sound sources.
synthetic.py — original demonstration sounds and educational HRIRs.
app.py — the interactive Streamlit application.
frontend/index.html — the draggable soundstage component.

This separation keeps the audio algorithms independent of the user interface.

What I Learned

Working on this project helped me connect several ideas that initially seemed independent.

First, small timing differences can carry meaningful spatial information.

Cross-correlation is not only a mathematical technique for comparing signals. It also provides a practical way to investigate the delays that contribute to directional hearing.

Second, impulse responses provide an elegant connection between physical systems and software.

Once we represent the acoustic path to each ear as an impulse response, generating the corresponding output becomes a convolution problem.

Third, a signal can be mathematically correct without producing a perfectly realistic perceptual result.

Our synthetic HRIR model demonstrates timing and level differences, but human spatial hearing also depends on detailed anatomy-dependent spectral cues.

Finally, I learned that making an engineering concept interactive can change how it is understood.

Adjusting an azimuth angle, listening to the result, and examining the corresponding waveforms makes the relationship between theory and perception much more tangible.

Continuing From Lab to Code

In the first project of this series, I explored classical computer vision using filtering, Fourier analysis, thresholding, and clustering.

This second project moves from image processing to audio signal processing.

Both follow the same philosophy:

Take an engineering concept, build an independent implementation, make the results observable, and explain what is happening underneath.

Not every engineering experiment needs to become a large software product.

Sometimes, a small interactive application is enough to reveal how an interesting concept works.

The goal of From Lab to Code is to keep exploring these ideas through practical implementations.

All bundled demonstration sounds in this project are generated programmatically, and no university course materials or proprietary recordings are redistributed.

If you're interested in signal processing, spatial audio, or simply curious about how computers can simulate directional hearing, I hope this project gives you something interesting to experiment with.

Explore the full series: https://github.com/Ertugrulmutlu/from-lab-to-code

Explore Spatial Audio Playground: https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/02-spatial-audio

Thanks for reading!

From Lab to Code #1: Exploring Classical Computer Vision with Python and OpenCV

Ertugrul — Thu, 22 Oct 2026 10:01:08 +0000

Most conversations about computer vision today revolve around deep learning, neural networks, and increasingly sophisticated AI models.

But not every image processing problem requires a trained model.

Sometimes, a Gaussian filter is enough to reduce noise. A threshold can separate objects from their background. A Fourier transform can reveal interference that is difficult to understand in the spatial domain.

These techniques are relatively simple, mathematically interpretable, and still useful in practical applications.

Recently, while exploring image and signal processing concepts in my computer engineering studies, I decided to start a small programming series called From Lab to Code.

The idea is simple: take engineering concepts I encounter, build independent implementations, visualize the results, and share what I learn.

For the first project, I built a small interactive image processing toolkit using Python, OpenCV, NumPy, and Streamlit.

GitHub repository: https://github.com/Ertugrulmutlu/from-lab-to-code

Project 01 — Image Processing: https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/01-image-processing

What Are We Building?

The application explores four classical computer vision techniques:

Image denoising using Gaussian and median filters.
Object counting using illumination correction, thresholding, and connected components.
Periodic noise removal using the Fast Fourier Transform (FFT).
Color clustering using K-means.

The application provides interactive controls, generated example images, and visual comparisons.

No pretrained models, API calls, or external datasets are required.

All bundled demonstration images are generated programmatically.

1. Image Denoising: Gaussian vs. Median Filtering

Digital images are often affected by noise.

Noise can originate from camera sensors, poor lighting conditions, signal transmission, or image acquisition hardware.

Two common types are:

Gaussian noise: Random variations in pixel intensity, often modeled using a normal distribution.
Salt-and-pepper noise: Individual pixels unexpectedly taking very dark or very bright values.

Different noise distributions require different filtering strategies.

Gaussian Filtering

A Gaussian filter performs a weighted average of neighboring pixels.

Pixels closer to the center receive higher weights, following a Gaussian distribution.

Mathematically, the two-dimensional Gaussian kernel can be written as:

G(x, y) = (1 / 2πσ²) × exp(-(x² + y²) / 2σ²)

The parameter σ controls the amount of smoothing.

A larger σ produces stronger smoothing but can also remove fine image details.

In OpenCV, Gaussian filtering is straightforward:

import cv2

gaussian = cv2.GaussianBlur(
    image, (5, 5), 0
)

Median Filtering

Unlike Gaussian filtering, a median filter replaces the center pixel with the median value of its neighborhood.

Consider these pixel values:

[10, 11, 12, 13, 255]

Their average is 60.2, but their median is 12.

If the value 255 represents an isolated noise spike, the median is much closer to the surrounding pixel values.

This makes median filtering particularly useful for salt-and-pepper noise.

median = cv2.medianBlur(image, 5)

Comparing the Results

The application applies both filters to the same noisy image.

It also calculates the Mean Squared Error (MSE) against the original image when a reference is available.

MSE = (1/N) × Σ(original - processed)²

A lower MSE indicates a smaller average squared difference from the reference image.

However, MSE alone does not fully describe perceptual image quality.

Key takeaway: Gaussian filtering is useful for smoothing distributed noise, while median filtering is often more effective against isolated intensity spikes.

Neither method is universally superior.

2. Object Counting: From Pixels to Objects

Suppose we want to count small objects placed on a table.

At first, this sounds like a simple thresholding problem.

If the objects are darker than the background, we could classify pixels based on their intensity.

But what happens when the background illumination is uneven?

One side of the image might be noticeably darker than the other, making a single global threshold unreliable.

Step 1: Estimate the Background

We can approximate slowly changing illumination using a large Gaussian blur.

background = cv2.GaussianBlur(
    gray, (0, 0), sigmaX=30
)

Subtracting the original image from the estimated background helps emphasize darker foreground objects.

corrected = cv2.subtract(
    background, gray
)

This reduces the influence of gradual illumination changes.

Step 2: Apply Otsu Thresholding

Otsu's method automatically selects a threshold based on the image's intensity distribution.

Instead of manually choosing a number such as 100 or 150, it searches for a threshold that separates the intensity classes according to their statistical variance.

_, mask = cv2.threshold(
    corrected,
    0,
    255,
    cv2.THRESH_BINARY + cv2.THRESH_OTSU
)

The output is a binary image containing foreground and background pixels.

Step 3: Identify Connected Components

After thresholding, neighboring foreground pixels can be grouped into connected regions.

OpenCV provides a useful function for this:

count, labels, stats, centroids = (
    cv2.connectedComponentsWithStats(
        mask, connectivity=8
    )
)

The function returns component labels and information such as bounding boxes and pixel areas.

By excluding the background and removing regions below a minimum area, we can estimate the number of objects.

The project also applies a small morphological opening operation before counting to remove isolated foreground noise.

Where Can This Be Useful?

This approach can be applied to controlled visual inspection tasks involving separate objects, such as small manufactured components.

However, it comes with important assumptions.

Objects should be sufficiently separated, and the contrast between objects and background should be reasonably clear.

Touching objects may merge into a single connected component.

Key takeaway: Reliable object counting often requires preprocessing, not just thresholding.

3. Fourier Transform: Removing Periodic Noise

This was one of the most interesting parts of the project.

Images are normally represented in the spatial domain, where each pixel corresponds to a position.

But some image artifacts are easier to identify in the frequency domain.

For example, imagine an image affected by regularly repeating stripes.

Those stripes represent periodic variations in pixel intensity.

Moving to the Frequency Domain

The two-dimensional Discrete Fourier Transform decomposes an image into spatial frequency components.

Each component represents a particular frequency and orientation.

Using NumPy:

import numpy as np

spectrum = np.fft.fft2(gray)

shifted = np.fft.fftshift(spectrum)

magnitude = np.log1p(
    np.abs(shifted)
)

Here:

fft2() computes the two-dimensional Fourier transform.
fftshift() moves the zero-frequency component to the center.
abs() obtains the magnitude.
log1p() makes the magnitude spectrum easier to visualize.

Periodic interference may appear as distinct peaks in the Fourier spectrum.

Removing Specific Frequencies

If we know which frequencies correspond to interference, we can suppress them using a notch filter.

A notch filter removes selected frequency regions while preserving much of the remaining spectrum.

For real-valued images, the Fourier spectrum has conjugate symmetry.

This means a sinusoidal interference component generally produces a symmetric pair of frequency peaks.

Both should be handled to preserve the symmetry of the filtered spectrum.

The basic operation is:

filtered_spectrum = shifted * mask

Here, mask contains zeros at the frequencies we want to suppress and ones elsewhere.

We then reconstruct the image using the inverse Fourier transform.

restored = np.fft.ifft2(
    np.fft.ifftshift(filtered_spectrum)
).real

An Important Limitation

In this project, the periodic noise is generated with known frequencies.

Therefore, the notch filter already knows where the unwanted frequency components are located.

This is intentional: it lets us isolate and study the effect of frequency-domain filtering.

Automatically identifying unknown interference frequencies in arbitrary photographs is a separate problem and is not implemented here.

A notch filter can also remove useful image information if the rejected frequencies overlap with actual image content.

Key takeaway: The Fourier transform provides another perspective on image processing, allowing us to manipulate structures according to their spatial frequencies rather than their pixel positions.

4. K-Means: Unsupervised Color Clustering

The final technique explores unsupervised learning.

Unlike classification models, K-means does not require predefined class labels.

Instead, it groups observations based on similarity.

For an RGB image, each pixel can be represented as a three-dimensional vector:

Pixel = [Red, Green, Blue]

K-means attempts to divide these vectors into K clusters by minimizing the squared distances between pixels and their assigned cluster centers.

The objective function is:

J = Σ ||xᵢ - μ(clusterᵢ)||²

where xᵢ is a pixel vector and μ is the corresponding cluster center.

Implementing K-Means with OpenCV

First, reshape the image into a collection of RGB vectors:

pixels = image.reshape(
    -1, 3
).astype(np.float32)

Then run K-means:

criteria = (
    cv2.TERM_CRITERIA_EPS +
    cv2.TERM_CRITERIA_MAX_ITER,
    25,
    0.2
)

_, labels, centers = cv2.kmeans(
    pixels,
    4,
    None,
    criteria,
    5,
    cv2.KMEANS_PP_CENTERS
)

We can reconstruct an image by replacing each pixel with the color of its assigned cluster center.

This produces a simplified image containing a small number of representative colors.

Color Clustering Is Not Semantic Segmentation

This distinction is important.

K-means only sees RGB values in this implementation.

It does not understand objects, scenes, or semantic categories.

Two unrelated objects with similar colors may belong to the same cluster.

Likewise, one object with multiple colors may be split across several clusters.

Still, color clustering is useful for exploring image structure, reducing color complexity, and understanding unsupervised learning.

Running the Project Locally

The project is available on GitHub:

https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/01-image-processing

You will need Python 3.10 or newer.

Clone the repository:

git clone https://github.com/Ertugrulmutlu/from-lab-to-code.git
cd from-lab-to-code/01-image-processing

Create a virtual environment:

python -m venv .venv

Activate it on Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Install the dependencies:

python -m pip install -r requirements.txt

Start the application:

python -m streamlit run app.py

Streamlit will open an interactive application in your browser.

You can switch between the four techniques, adjust processing parameters, and compare the results.

Each mode includes a programmatically generated example image. You can also upload an image of your own.

To regenerate the demonstration gallery:

python demo.py

To run the included tests:

python -m unittest discover -s tests -v

The processing algorithms are implemented in processing.py, while synthetic.py generates the example images and app.py contains the Streamlit interface.

What I Learned

Building this project reinforced several important ideas.

First, understanding the characteristics of a problem matters as much as selecting an algorithm.

Gaussian filtering and median filtering may look similar at first, but they behave differently depending on the noise distribution.

Second, preprocessing can determine whether a simple computer vision algorithm succeeds or fails.

In the object counting example, background illumination correction can be just as important as the thresholding operation itself.

Third, the frequency domain provides a different way to reason about images.

Some patterns that are difficult to isolate spatially become much easier to analyze after a Fourier transform.

Finally, unsupervised clustering demonstrates that useful structure can be extracted from images without labeled training data, even though grouping colors is not the same as understanding a scene.

Why I Started From Lab to Code

I wanted a lightweight way to turn engineering concepts into practical software projects.

Not every project needs to become a startup, a large framework, or a long-term product.

Sometimes, a small, well-explained implementation is enough to explore an idea and demonstrate what you have learned.

That is the philosophy behind From Lab to Code.

Each entry will focus on an engineering topic, build a small independent implementation, and document the underlying concepts and results.

The projects are independently implemented, with original demonstration materials rather than redistributed university coursework.

This first project focuses on classical image processing. Future entries may explore other engineering topics as I encounter them.

If you are learning computer vision or signal processing, I hope the code and explanations help you experiment with these concepts yourself.

Explore the series: https://github.com/Ertugrulmutlu/from-lab-to-code

Explore the image processing project: https://github.com/Ertugrulmutlu/from-lab-to-code/tree/main/01-image-processing

Thanks for reading!

Behavioral Convergence Without Representational Convergence: Reproducing Training-History Dependence in Neural Networks

Ertugrul — Wed, 30 Sep 2026 14:34:04 +0000

I recently released a new preprint exploring a simple question:

If two neural networks eventually behave almost the same, does that mean they also become internally the same?

The experiments suggest that — at least under the protocol I tested — the answer can be no.

Two neural networks can reach very similar predictive performance while still retaining measurable differences in their internal representations caused by their earlier training histories.

The paper is now available on arXiv:

Paper: https://arxiv.org/abs/2609.37836

Code and reproducibility repository:

https://github.com/Ertugrulmutlu/hysteresis-neural-networks

The basic idea

The experiments use MNIST and a small convolutional neural network.

Instead of training a model once on the full dataset, I split the learning history into stages.

Define:

A: digits 0–4
B: digits 5–9
C: a balanced distribution containing digits 0–9

Two models start from identical initial weights.

The first model experiences:

A -> B -> C

The second experiences:

B -> A -> C

I call these:

SABC
SBAC

The important part is the final stage.

During C, both models receive the same training distribution, the same deterministic batch sequence, and the same checkpoint schedule.

So after their different histories, both networks are exposed to the same environment.

The question becomes:

Does common training erase the effects of training history?

Why accuracy alone is not enough

Suppose both networks eventually reach around the same accuracy.

It would be tempting to conclude that they have converged to essentially the same solution.

But prediction accuracy only tells us about behavior.

It does not tell us whether the internal features learned by the two networks are identical.

To study this, I compare internal representations using CKA-based similarity measurements.

The main representation-history score is:

H_repr = 1 - mean(CKA_conv2, CKA_fc1)

Higher values mean the two networks retain more representational difference.

The interesting case is therefore:

Behavioral difference -> small

while

Representational difference -> remains measurable

What happened?

In the main experiment, I ran 20 paired seeds.

The networks often became closely matched in predictive performance after common relaxation, while measurable representation differences remained.

This motivated a harder test:

What happens if both models continue training on the same distribution for much longer?

Stress test: 50,000 shared updates

I reran five paired seeds from initialization and extended the common-relaxation phase to:

10,000 updates
25,000 updates
50,000 updates

At 50,000 common updates, the mean representation-history score was:

H_repr = 0.1902

with a 95% bootstrap confidence interval of approximately:

[0.1611, 0.2193]

Meanwhile, predictive performance remained very close.

At 50,000 updates:

Mean SABC accuracy: 98.480%
Mean SBAC accuracy: 98.316%

Mean absolute accuracy gap: ~0.18 percentage points

So over the measured horizon, behavioral convergence did not imply representational convergence.

Importantly, this does not prove that the difference persists forever.

The correct interpretation is narrower:

The internal representation difference did not disappear within the tested 50,000-update horizon.

A second question: does the difference actually matter?

Representation geometry can differ without having any practical consequence.

So I added a fresh linear-probe experiment.

The CNN backbone is frozen.

A brand-new linear classifier is then trained on top of FC1 features.

Only the new linear head is trained.

The SABC and SBAC probes receive:

identical initialization,
identical examples,
identical labels,
identical minibatch ordering,
identical optimization settings.

This lets us ask:

Is class information equally easy to extract from both representations?

An interesting low-data effect

I tested several amounts of labeled training data:

25 examples / class
50 examples / class
100 examples / class
500 examples / class

The mean SABC-minus-SBAC accuracy differences were:

25/class  -> +1.005 percentage points
50/class  -> +0.580 percentage points
100/class -> +0.288 percentage points
500/class -> +0.090 percentage points

The difference shrinks as more labeled data becomes available.

The 50-examples-per-class condition was especially interesting, so I repeated the probe using five different fresh-head seeds.

After averaging repeated probes within each of the 20 model seeds:

Mean paired difference: +0.496 pp
95% t CI:              [+0.127, +0.866] pp
95% bootstrap CI:      [+0.160, +0.833] pp
paired t-test:         p = 0.0111
Wilcoxon:              p = 0.0083

This suggests a useful distinction.

The two representations can provide similar high-data performance while differing in low-data readout efficiency.

In other words, training history may change how easy it is for a downstream classifier to extract useful information when supervision is limited.

What happens with more probe data?

At 500 examples per class, the mean difference was only:

+0.090 percentage points

I also ran an exploratory equivalence analysis using a ±0.5 percentage-point margin.

The 90% confidence interval was:

[-0.037, +0.217] pp

which falls completely inside the chosen equivalence interval.

So under that declared margin, the high-data linear-probe endpoints are practically equivalent.

That produces a two-regime picture:

Low labeled data:
training history affects linear readout efficiency.

High labeled data:
the difference becomes practically small.

Is this just caused by ReLU?

One possible mechanism is reduced plasticity caused by sparse ReLU activation patterns.

To explore this, I ran a matched-learning-rate comparison between:

ReLU
vs.
LeakyReLU

Both conditions were evaluated through 50,000 common-relaxation updates across five paired seeds.

At the final endpoint, the LeakyReLU-minus-ReLU difference in the representation-history score was approximately:

-0.0398

All five paired differences pointed in the same direction.

The bootstrap interval was approximately:

[-0.0772, -0.0176]

But with only five model seeds, classical paired significance tests were still inconclusive.

So I treat this as directional mechanism evidence, not a causal proof.

The result suggests that activation-mediated plasticity may contribute to the persistence of training-history effects.

Is the result only caused by different labels?

The original A/B split separates digits:

A = 0–4
B = 5–9

That raises an obvious concern.

Maybe the effect is simply caused by learning disjoint output classes in different orders.

To test this, I added a same-label rotated-MNIST control.

Both histories use the same class labels, but the input domains differ through symmetric rotations.

Across all five paired seeds, the models reached the predeclared behavioral-matching criterion while still retaining non-zero representation-history scores.

So the phenomenon is not limited to the original disjoint-label setup.

Reproducing the experiments

The full repository is available here:

https://github.com/Ertugrulmutlu/hysteresis-neural-networks

Clone it:

git clone https://github.com/Ertugrulmutlu/hysteresis-neural-networks.git
cd hysteresis-neural-networks

Create an environment:

python -m venv .venv

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install dependencies:

pip install -r requirements.txt

Run the basic AB / BA experiment

python -m src.train configs/mnist_v0_sab.yaml
python -m src.train configs/mnist_v0_sba.yaml

Then validate that the pair uses the intended matched initialization:

python -m src.validate_pair \
  --run-a results/mnist_v0_SAB_seed1337_normnone \
  --run-b results/mnist_v0_SBA_seed1337_normnone \
  --json-out results/pair_validation.json

Run representation analysis

For example, CKA:

python -m src.analysis.cka \
  --run-sab results/mnist_v0_SAB_seed1337_normnone \
  --run-sba results/mnist_v0_SBA_seed1337_normnone \
  --samples-per-class 200 \
  --outdir plots/part2_seed1337/cka

The repository also includes analyses for:

training curves
weight trajectories
CKA
weight interpolation
activation health
common relaxation
paired multi-seed aggregation
linear probes
long-horizon relaxation
activation-function controls
rotated-MNIST controls

A note on reproducibility

I tried to make the pairwise experimental design explicit.

The paired runs control factors such as:

initialization
random seeds
evaluation data
common-relaxation batch order
checkpoint schedule
probe initialization
probe minibatch order

Run metadata is stored alongside the generated experiment artifacts.

The final paper-facing outputs are packaged under:

paper_artifacts/

while the underlying experiment outputs remain the source of truth.

What I think is the interesting part

The most interesting result to me is not simply that two networks end up with different weights.

That is expected.

The more interesting observation is the combination:

same initialization

+ different training histories

+ long exposure to the same later distribution

+ almost identical predictive performance

+ persistently different internal representations

And the linear-probe experiments suggest that those differences can sometimes affect how efficiently information is extracted downstream.

This creates an interesting distinction between:

behavioral convergence

and

representational convergence

They are not necessarily the same thing.

What this does NOT show

There are several important limitations.

This work does not establish that:

all neural networks exhibit hysteresis,
training-history effects persist permanently,
the measured representation difference has a single causal mechanism,
similar accuracy implies functionally identical networks,
the result automatically generalizes beyond the tested architectures and datasets.

The experiments currently focus mainly on a small CNN and MNIST-derived protocols.

So I view the results as evidence of persistent training-history dependence under controlled experimental conditions, rather than a universal theorem about neural networks.

Where to go next

There are several natural extensions:

wider or deeper architectures,
larger datasets,
transformers,
continual-learning benchmarks,
longer common-relaxation horizons,
interventions targeting plasticity,
representation alignment methods,
studying whether history dependence affects adaptation to entirely new downstream tasks.

One question I find particularly interesting is whether similar effects appear in large models that are repeatedly fine-tuned or continually updated.

If two systems behave similarly today, how much of their different histories is still encoded internally?

That seems increasingly relevant as models become continuously trained, adapted, and deployed.

Paper and code

📄 Paper

https://arxiv.org/abs/2609.37836

💻 Code + reproducibility artifacts

https://github.com/Ertugrulmutlu/hysteresis-neural-networks

If you reproduce the experiments, find an issue, or want to test the idea on another architecture, feel free to open an issue or discussion on GitHub.

Citation

@article{mutlu2026behavioral,
  title={Behavioral Convergence Without Representational Convergence: Persistent Training-History Dependence in Neural Networks},
  author={Mutlu, Ertuğrul},
  journal={arXiv preprint arXiv:2609.37836},
  year={2026}
}

What an Over-Engineered Parity Classifier Taught Me About Representation

Ertugrul — Sat, 26 Sep 2026 16:23:53 +0000

I Revisited My Parity Paper — and Found the Representation Was the Real Story

A while ago, I built a deliberately over-engineered classifier for one of the easiest problems in computer science:

Is an integer odd or even?

In binary, the answer is already sitting in the least significant bit.

0 means even.

1 means odd.

No machine learning is needed.

And yet I passed those binary representations through a wavelet transform, summarized the coefficients, clustered them with k-means, and tried to recover parity from the resulting feature space.

The first version of the experiment looked interesting. It reported about 69.67% accuracy.

But when I came back to the project and started preparing a proper revision, I found something more important than the original result:

the experiment itself needed to be rethought.

That ended up making the project much more interesting.

The two problems I found in the original version

The first issue was label leakage.

I used parity labels to estimate whether each cluster was mostly odd or mostly even. But the evaluation was not cleanly separated from that calibration step.

That meant information from the data being evaluated could influence the mapping from clusters to parity labels.

The second issue was more conceptual.

I had described the method as unsupervised because k-means itself never receives parity labels.

That is only partly true.

The clustering step is unsupervised, but the final cluster-to-parity mapping uses labels. So the complete classifier is not fully unsupervised.

Those two details changed how the result should be interpreted.

Instead of trying to defend the original framing, I decided to rebuild the experiment around a stricter evaluation protocol.

Rebuilding the experiment

The revised study uses all integers from 0 to 10,000.

Each integer is converted into a fixed-width 32-bit binary signal.

The primary pipeline is:

Integer
   ↓
32-bit binary representation
   ↓
level-3 db2 wavelet transform
   ↓
mean absolute coefficient magnitude
   ↓
k-means per wavelet subband
   ↓
training-only cluster calibration
   ↓
odd / even prediction

The data is split into:

6,000 training samples
2,000 validation samples
2,001 held-out test samples

Representation and model choices are made using only training and validation data.

Once the configuration is frozen, the model is re-fit on the combined train and validation sets and evaluated once on the held-out test set.

The result:

84.26% held-out test accuracy

with a 95% Wilson confidence interval of:

82.60%–85.79%

Across 20 different stratified train/test splits, the same representation achieved:

84.20% ± 0.57%

So the revised result is numerically stronger than the original one.

But that is not the part I find most interesting.

The important result is what happens when the representation changes

Parity is determined by one bit.

So the cleanest test is simple:

remove that bit.

When I mask the natural least significant bit and keep the rest of the wavelet pipeline unchanged, validation accuracy drops to:

48.15%

That is essentially chance.

This is important because it rules out the strongest interpretation of the model.

The pipeline is not discovering the abstract arithmetic rule of parity.

It is using information that is already present in the binary representation.

The interesting question becomes:

Why is that information so easy to recover in some representations and almost impossible to recover in others?

A tiny layout change can have a huge effect

The standard representation uses left-zero padding.

If I keep the same 32-bit signal but switch to right padding, validation accuracy drops to:

65.20%

The parity rule did not change.

The bits did not contain less information.

Only their position inside the signal changed.

That was the first strong hint that the wavelet transform was creating a geometry that depends heavily on spatial layout.

The coarse wavelet band carries almost all of the signal

A level-3 wavelet decomposition produces one approximation band and three detail bands:

Subband	Validation accuracy
A3	83.20%
D3	52.35%
D2	50.30%
D1	50.40%

This surprised me.

Parity depends on a single bit, so I initially expected the fine-scale detail coefficients to matter most.

Instead, the approximation band A3 contains almost the entire predictive signal.

I then compared it with simpler coarse representations:

Representation	Validation accuracy
db2 A3	83.20%
Haar A3	61.30%
Raw MAV	61.30%
3-level average pooling	61.30%
Triangular low-pass	51.40%

So this is not just an averaging effect.

Something specific about the interaction between the db2 filters, downsampling, signal layout, and boundary handling makes the parity bit unusually accessible.

Then I moved the parity bit

This was probably the most revealing experiment.

I kept exactly the same 32 bits.

I did not add information.

I did not remove information.

I only moved the parity-carrying bit to different positions in the signal.

The result changed dramatically.

At the natural position, validation accuracy is:

83.20%

At some positions, it falls much closer to chance.

At the best tested position, it reaches:

98.60%

Nothing about the underlying parity information changed.

Only its position changed.

That makes the interpretation much clearer:

the model is not learning a representation-independent rule.

It is exploiting a representation-dependent structure created by the transform.

Even boundary handling changes the result

Wavelet transforms need a rule for what happens at the edges of a finite signal.

I tested several boundary-extension modes while keeping the rest of the model fixed.

The resulting validation accuracy ranged from:

54.45% to 83.20%

That is a huge swing from what might look like a low-level implementation choice.

In this experiment, boundary handling is not a minor detail.

It is part of the mechanism.

Generalization exposes the weakness

I also froze the model trained on 0–10,000 and evaluated it on increasingly distant numerical ranges without recalibration.

Test range	Accuracy
10,001–20,000	79.98%
20,001–50,000	71.51%
50,001–100,000	66.32%
100,001–1,000,000	59.69%

Performance steadily degrades as the magnitude distribution moves away from the training range.

At first, that might suggest that larger integers are inherently harder.

But when separate models are trained and tested inside fixed bit-length bands, accuracy remains roughly between 78% and 88%.

So the main problem is not magnitude itself.

It is representation shift.

The geometry that works in one numerical regime does not stay stable in another.

More data does not solve it either

On a wider 0–100,000 distribution, I increased the training set from 500 examples all the way to 80,000.

The performance ceiling barely moved.

That suggests the bottleneck is not the amount of data.

The bottleneck is the representation and the very simple clustering model operating on top of it.

What I changed my mind about

The first version of this project was mostly about a surprising classifier result.

The revised version is not.

The more interesting story is that the same symbolic information can become easy, difficult, or almost impossible to recover depending on how it is represented.

That changed how I think about the experiment.

The question is no longer:

“Can wavelets classify parity?”

Of course parity can be solved exactly with one bit.

The better question is:

“What does the representation make accessible to a simple model?”

That is a much more general machine-learning question.

A model can perform well without learning the abstract rule we think it learned.

Sometimes preprocessing creates a useful proxy.

Sometimes position matters more than expected.

Sometimes a boundary condition changes the geometry enough to alter the result completely.

And sometimes the right experiment is not another accuracy benchmark, but an ablation that tells you where the accuracy came from.

Why I am glad I revisited the paper

Finding problems in an earlier experiment is uncomfortable.

But I think revisiting it made the work much stronger.

The revised version now:

separates training, validation, and test data cleanly
describes the supervised and unsupervised parts accurately
includes repeated-split robustness checks
tests out-of-distribution generalization
isolates the role of the LSB
studies subbands, padding, bit position, and boundary conditions
includes frozen splits, predictions, metrics, and reproducibility artifacts

The final claim is narrower than the original one.

I am much more comfortable with it because of that.

The wavelet pipeline does not discover parity as an abstract arithmetic rule.

Instead, it shows how a classical signal-processing transform can make symbolic information that is already present in the input more or less statistically accessible.

For me, that ended up being the real result.

Reproducibility

The code, frozen experiment artifacts, prediction outputs, and analysis results are available here:

GitHub:

https://github.com/Ertugrulmutlu/Using-Wavelets-and-Clustering-to-Predict-Odd-or-Even-Numbers

For the exact manuscript snapshot, use the Git tag:

paper-v2

The revised arXiv version is scheduled to become public on September 29, 2026.

Paper:

https://arxiv.org/abs/2511.00071

Final thought

This project started as an unnecessarily complicated way to answer a one-bit question.

The revision taught me something more useful than the original accuracy number:

Before asking what a model learned, ask what the representation made easy to learn.

That is the part of this experiment I will probably remember.

PromptLedger v0.7 — Turning prompt evaluation into local regression gates

Ertugrul — Mon, 13 Jul 2026 14:14:40 +0000

Devlog — Part 6

PromptLedger v0.7 is out.

The previous release made prompt history easier to inspect.

This release makes prompt changes easier to evaluate.

Until now, PromptLedger could answer questions such as:

What changed?
Which version is in production?
Which version was marked stable?
Why was a new version created?

But one important question was still missing:

Did the new prompt actually perform better?

A text diff can show that a prompt changed.

It cannot tell you whether accuracy improved, latency increased, cost became unacceptable, or an important behavior regressed.

PromptLedger v0.7 introduces evaluation runs, metric comparisons, and policy-based regression gates.

The workflow is now:

version → diff → review → evaluate → gate → promote

Evaluation runs

PromptLedger can now store benchmark results produced by external tools.

Each evaluation run is attached to a concrete prompt version and can include:

benchmark suite
model
dataset hash
numeric metrics
run metadata
creation time

For example:

{
  "suite": "support-v1",
  "model": "test-model",
  "metrics": {
    "accuracy": 0.91,
    "latency_ms": 420,
    "cost_usd": 0.018
  },
  "metadata": {
    "seed": 42,
    "sample_count": 500
  }
}

A prompt version can have multiple evaluation runs.

This is important because the same prompt may be tested:

on multiple models
against different datasets
with different seeds
across several benchmark suites
multiple times as the surrounding system changes

Evaluation history is stored separately from prompt history, so repeated runs are preserved instead of overwriting each other.

Recording results

PromptLedger does not run the benchmark itself.

External tools produce the evaluation result, and PromptLedger records it.

promptledger eval record \
  --id onboarding \
  --ref staging \
  --file evaluation-result.json

The reference may be a concrete version or a label such as prod or staging.

Even when a moving label is used, the evaluation is stored against the concrete version the label currently points to.

This keeps the historical record stable.

Comparing prompt versions

Evaluation runs can be compared between two prompt versions or labels:

promptledger eval compare \
  --id onboarding \
  --from prod \
  --to staging \
  --suite support-v1 \
  --model test-model

Example output:

Evaluation comparison: onboarding
Suite: support-v1
Model: test-model

Metric          prod/v1     staging/v2    Delta
accuracy        0.84        0.91          +0.07
latency_ms      380         410           +30
cost_usd        0.016       0.018         +0.002

PromptLedger selects compatible runs deterministically.

It does not silently compare results from unrelated benchmark suites or different models.

A comparison is only useful when both sides describe the same experiment.

Regression gates

Comparisons show what changed.

Regression gates decide whether the change is acceptable.

A gate policy defines:

whether a metric should be higher or lower
how much absolute regression is allowed
how much percentage regression is allowed

Example policy:

{
  "suite": "support-v1",
  "model": "test-model",
  "metrics": {
    "accuracy": {
      "direction": "higher",
      "max_regression": 0.02
    },
    "latency_ms": {
      "direction": "lower",
      "max_regression_percent": 15
    },
    "cost_usd": {
      "direction": "lower",
      "max_regression_percent": 20
    }
  }
}

Run the gate with:

promptledger eval gate \
  --id onboarding \
  --from prod \
  --to staging \
  --policy promptledger-gate.json

Example output:

PASS accuracy: candidate improved by 0.07
PASS latency_ms: regression within allowed threshold
PASS cost_usd: regression within allowed threshold

Gate passed.

When a regression exceeds the policy limit, the command returns a non-zero exit code.

That makes evaluation gates suitable for CI workflows.

A prompt change can now fail a build in the same way as a failed test or performance regression.

Dashboard evaluation history

The local dashboard has also been updated.

Prompt details can now show:

evaluation run history
benchmark suite
model
dataset information
metrics
metadata
metric differences between versions

This connects prompt history and evaluation history in the same interface.

A developer can inspect what changed in the prompt and how the measured behavior changed alongside it.

The dashboard remains local-first, and prompt content remains read-only.

Sequence-aware prompt diffs

The dashboard comparison system was also improved.

The previous implementation compared lines mainly by their array position.

That works for simple replacements, but inserting one new line could make every following line appear changed.

The new comparison uses a sequence-aware diff based on Python’s difflib.SequenceMatcher.

It now handles:

inserted lines
removed lines
replaced lines
unchanged sections
aligned line numbers

This produces a much more accurate view of how a prompt changed.

What changed in v0.7

Dedicated evaluation history

Benchmark results now live in their own evaluation-run records instead of being treated as static prompt metadata.

Version and label comparisons

Evaluation results can be compared through concrete versions or release labels such as prod and staging.

Policy-based regression gates

Teams can define acceptable quality, latency, and cost regressions through JSON policies.

CI-friendly exit codes

Passing gates, detected regressions, invalid input, and operational failures return distinct exit codes.

Dashboard evaluation visibility

Evaluation runs and metric differences are now visible alongside prompt history.

Improved visual diffs

Prompt comparisons now use a sequence-aware algorithm instead of simple line-position matching.

Non-destructive migration

Existing PromptLedger databases are migrated to the new schema without removing prompt versions, labels, markers, or metadata.

Design boundary

PromptLedger still does not execute prompts.

It does not call:

OpenAI
Anthropic
Gemini
Ollama
any other model provider

It also does not include an automatic LLM judge.

That separation is intentional.

PromptLedger should remain:

local-first
provider-independent
deterministic
lightweight
compatible with external benchmark systems

Your evaluation framework runs the experiment.

PromptLedger keeps the history, compares the results, and applies the release policy.

Testing

The v0.7 release includes 119 passing tests covering:

database migrations
repeated evaluation runs
label resolution
malformed metrics
non-finite values
comparison compatibility
deterministic ordering
missing metrics
zero baselines
regression policies
CLI exit codes
dashboard endpoints
sequence-aware diffs

The PowerShell file-based evaluation workflow was also tested end to end.

Installation

pip install --upgrade promptledger

Initialize a local database:

promptledger init

Launch the dashboard:

promptledger dashboard

Closing

Prompt version control is useful, but version history alone cannot tell you whether a release is safe.

A new prompt may look cleaner while producing worse answers.

It may improve accuracy while increasing latency or cost.

It may pass one benchmark while silently regressing another.

PromptLedger v0.7 connects prompt changes to measurable results.

The goal is not to build another evaluation framework.

The goal is to provide the missing release layer between prompt experimentation and production:

What changed?
How did performance change?
Is the regression acceptable?
Should this version be promoted?

PromptLedger is moving from a tool that stores prompt history to a tool that helps control prompt releases.

Links

PyPI: PyPI

GitHub: GitHub

LinkedIn: LinkedIn

Website: Website

One Gradient Spike, Six Batches to NaN: Debugging a Deterministic Neural-Network Training Failure

Ertugrul — Mon, 13 Jul 2026 06:00:00 +0000

The first visible NaN appeared in the final linear layer at batch 46.

By then, the model was already effectively destroyed.

Six batches earlier, every tensor was still finite. The loss was finite. The gradients were finite. The momentum buffers were finite. Nothing had crossed the clean boundary between a valid floating-point value and NaN.

But the training state was already in a runaway regime.

This is how an aggregate-analysis failure led me backward—from a corrupted checkpoint, to one reproducible batch, to the finite gradient spike that began the collapse.

The experiment

I was running a sequential-training experiment on MNIST using a small CNN.

The experiment compared two training histories:

SABC: digits 0–4, then digits 5–9, followed by a shared balanced 0–9 relaxation phase.
SBAC: digits 5–9, then digits 0–4, followed by the same relaxation phase.

As a mechanism-control experiment, I replaced the existing ReLU activation with LeakyReLU while keeping the rest of the protocol fixed.

The setup was:

SimpleCNN
no normalization
LeakyReLU slope 0.01
SGD
learning rate 0.05
momentum 0.9
no weight decay
deterministic seeds: 101, 202, 303, 404, 505
two histories per seed
ten total runs

Four of the ten runs became numerically invalid:

SABC seed303
SBAC seed101
SBAC seed202
SBAC seed303

In all four cases, the first known bad checkpoint was epoch 11.

Epoch 10 was the end of the first training domain. Epoch 11 was the first epoch after switching to the second domain.

That timing was suspicious, but not enough to establish a cause. The instability could depend on the interaction between the activation function, learning rate, momentum, domain switch, model state, task order, and random seed.

The validator found it first

I did not discover the problem because the training loop printed NaN.

A later aggregate-analysis validator rejected two checkpoints that should have represented the same model state: the final sequential-training checkpoint and the step-zero checkpoint of the relaxation phase.

At first, this looked like a serialization or bookkeeping issue.

A direct checkpoint audit showed that the affected files contained NaN and Inf values.

For three failed runs, all 421,642 parameters were NaN in the first bad checkpoint. In SABC seed303, the checkpoint contained 421,610 NaNs and 32 positive infinities.

The validator had not caused the problem. It had prevented corrupted runs from entering the scientific analysis.

What I initially got wrong

The original runs had been launched in parallel on one GPU.

My first suspicion was therefore environmental:

GPU contention
multiprocessing interference
nondeterministic CUDA behavior
a transient scheduling or hardware issue

To test that, I reran one known failing configuration—seed101-SBAC—alone with a detailed numerical tracer.

It failed again at exactly:

epoch 11
phase 2
phase data A
batch 46
after the forward pass
first failing tensor: fc2_logits

The isolated repeat also used the same input hash, label hash, label histogram, and non-finite counts.

The failing logits contained:

128 NaNs
128 positive infinities
384 negative infinities

Reproducing the same failure in isolation, on the same batch and at the same network stage, makes a one-off GPU collision very unlikely.

What actually happened

The first non-finite tensor appeared at batch 46.

But the failure began earlier.

At batch 39, the system still looked ordinary:

loss: about 3.03
global gradient norm: about 9.11
parameter magnitudes still small

At batch 40, the trajectory changed sharply:

loss jumped to about 44.59
global gradient norm jumped to about 483.74
maximum gradient reached about 266.7

Everything was still finite.

After the optimizer step, the largest momentum-buffer value rose from about 9.13 to about 269.93.

The following batches did not recover.

Batch	Loss	Global gradient norm	Max FC1 activation	Interpretation
39	`3.03`	`9.11`	`2.18`	Ordinary-looking state
40	`44.59`	`483.74`	`17.10`	First large finite gradient event
41	`1.48 × 10^3`	`988`	`913`	Runaway growth becomes visible
43	`1.04 × 10^5`	`7.82 × 10^4`	`5.92 × 10^4`	Strong amplification
44	`4.71 × 10^8`	`6.25 × 10^7`	`1.02 × 10^6`	Extreme but finite
45	`3.23 × 10^18`	`1.19 × 10^15`	`6.87 × 10^15`	Model effectively destroyed
46	—	—	`1.97 × 10^36`	Final logits overflow float32

Immediately before the failing forward pass:

fc1.weight magnitude was around 10^12
fc2.weight magnitude was around 10^13
momentum buffers were around 10^14–10^15
the maximum FC1 activation was about 1.97 × 10^36

The final linear layer then overflowed float32 and produced NaN and signed Inf values.

The trace supports the following sequence:

large but finite gradient event
→ rapid growth in momentum and parameter scale
→ rapidly growing activations
→ float32 overflow in the final linear layer

Momentum appears to have amplified the instability, but the trace does not establish what caused the initial gradient spike.

Likewise, fc2_logits was the first non-finite tensor, but it was the terminal symptom, not necessarily the origin of the failure.

Finite is not healthy

A standard safeguard is:

if not torch.isfinite(tensor).all():
    stop_training()

That check is necessary, but late.

At batch 45, the model had:

loss around 10^18
gradient norm around 10^15
momentum buffers around 10^14
activations around 10^15

Every value was still finite.

A binary finite/non-finite check would classify the state as valid. In practice, the model was already beyond recovery.

This suggests a more useful distinction:

numerically finite
numerically extreme
numerically non-finite

The transition from the first state to the second is where the most useful debugging information exists.

By the time NaN appears, the original trigger may be several optimizer steps in the past.

Why the debugging workflow mattered

The investigation followed a simple sequence:

Aggregate analysis failed.
A pair validator caught a checkpoint inconsistency.
A checkpoint audit found NaN and Inf values.
A fail-fast numerical tracer was added.
A known failure was reproduced in isolation.
The first non-finite tensor was localized to one batch and one network stage.
Earlier batches revealed the actual runaway dynamics.
A finite control run showed that the tracer did not automatically cause failure.

That workflow is reusable.

For numerical debugging, I would now monitor:

global gradient norm
maximum absolute gradient
parameter norms
momentum-buffer norms
activation magnitudes
model state before and after the optimizer step
deterministic hashes of the input and labels

The hashes were especially useful.

“It failed at batch 46 again” is weaker evidence than:

“It failed at batch 46 again on the exact same input and label tensors.”

What the evidence supports

The careful conclusion is:

Under this sequential-training protocol, LeakyReLU with SGD at learning rate 0.05 and momentum 0.9 showed deterministic, seed-dependent numerical instability in 4 of 10 runs.

The evidence does not show that LeakyReLU universally causes gradient explosions.

It also does not show that momentum, the domain switch, the task order, or the final linear layer independently caused the failure.

The instability may depend on an interaction between:

activation function
learning rate
momentum
domain switch
model state
random seed
task order

A control run, seed404-SBAC, completed the same requested epoch range without non-finite values.

So the protocol was not universally unstable.

But a 4/10 failure rate made this LeakyReLU branch unreliable for paired scientific analysis under the tested configuration.

The existing ReLU results were not affected by this failure.

Conclusion

The most useful artifact from this experiment was not the NaN checkpoint.

It was the finite trace leading into it.

At batch 39, the system looked ordinary.

At batch 40, the gradient norm jumped from roughly 9 to roughly 484.

At batch 45, the model was still technically finite but already had gradients around 10^15.

At batch 46, a hidden activation reached approximately 10^36, and the final linear layer overflowed float32.

The main lesson is simple:

A finite tensor is not necessarily evidence of a healthy training state.

NaN checks are essential, but they are late alarms.

The final NaN showed where the computation stopped being representable.

The six finite batches before it showed how the model got there.

OpenAnima v1 — Open-Source Desktop Overlay Engine for Windows

Ertugrul — Fri, 15 May 2026 06:15:20 +0000

OpenAnima v1 — Open-Source Desktop Overlay Engine for Windows

After months of building, experimenting, rewriting systems, debugging strange desktop issues, and testing different asset formats, OpenAnima v1 is finally out.

OpenAnima is an open-source desktop overlay engine for Windows that lets you place animated assets directly onto your desktop.

You can use:

GIFs
Static images
Sprite strips
Spritesheets
Frame-folder animations
RPG-style HUD elements
Transparent animated assets
Pixel-art characters
Desktop companions

The goal of the project was simple:

Create a lightweight desktop overlay system that feels flexible, customizable, and fun to experiment with.

What OpenAnima Can Do

OpenAnima allows you to spawn movable overlay windows directly on top of your desktop.

Each overlay can be:

dragged freely
resized
locked in place
made click-through
set always-on-top
adjusted for opacity
animated with custom FPS settings

The application also restores overlay states between sessions, so your desktop setup persists after restarting the app.

Supported Asset Types

One of the biggest goals of the project was supporting multiple animation workflows instead of only GIFs.

Currently supported:

GIF animations
Static images (.png, .jpg, .webp)
Frame-folder animations
Horizontal sprite strips
Vertical sprite strips
Spritesheets with metadata
Basic HUD/UI overlay assets

The engine also includes an asset analyzer system that tries to detect asset types automatically.

Built With

OpenAnima is primarily built using:

Python
PyQt6
QMovie / QPixmap rendering systems
Custom animation parsing logic

A lot of time went into handling edge cases like:

hidden overlays
broken configs
off-screen windows
click-through recovery
corrupted animation states

v1 focuses heavily on stability and recovery tools.

Features Added During Development

Some systems added throughout development:

Persistent overlay state saving
Safer config recovery
Recovery tools for invisible overlays
Logging system
Diagnostics panel
Asset metadata support
Import wizard
Sprite animation handling
Basic layered UI rendering
System tray controls

Why I Built It

I always liked desktop customization tools, animated desktop companions, game HUD overlays, and lightweight desktop effects.

Most existing solutions were either:

too limited
too complicated
too specific
abandoned
or focused on only one asset type

So I started experimenting with building my own system.

The project slowly evolved from “just display GIFs on desktop” into a more general desktop overlay engine.

Future Plans

Some ideas planned for future versions:

Better transparent video support
More advanced animation systems
Improved UI tools
Better performance optimizations
Asset marketplace/import improvements
More overlay interaction systems
Possible 3D asset support in the future

Download

Website / Download:

OpenAnima Website: https://ertugrulmutlu.github.io/OpenAnima/

GitHub Repository:

OpenAnima GitHub Repository: https://github.com/Ertugrulmutlu/OpenAnima

itch.io Page:

OpenAnima itch.io Page: https://ertugrulmutlu.itch.io/openanima

Instagram:

OpenAnima Instagram: https://www.instagram.com/openanimaengine

Final Thoughts

OpenAnima started as a small side project and slowly became a much larger system than I originally expected.

There is still a lot to improve, but releasing v1 feels like a huge milestone for the project.

Feedback, ideas, bug reports, and experiments are always welcome.

I’m excited to see what people create with it.

PromptLedger v0.6 — Turning prompt history into a local workspace dashboard

Ertugrul — Mon, 04 May 2026 16:23:46 +0000

Devlog — Part 5

PromptLedger v0.6 is out.

This release changes how PromptLedger feels to use.

Until now, PromptLedger was primarily a terminal-first tool with a small read-only viewer. The core workflow already existed: store prompt versions, compare changes, label releases, mark important versions, and keep everything local in SQLite.

That worked.

But once a prompt library grows, a simple viewer stops being enough.

Prompt iteration is not just about storing text. It is about navigating decisions:

Which version worked best?
Which version became stable?
What changed between versions?
Which prompt belongs to which workflow?
Which prompt should be reused?

Those questions are easier to answer when the history is not only stored, but also visible and interactive.

So v0.6 turns the old viewer into a local prompt workspace dashboard.

Workspace dashboard

The dashboard now starts with a card-based workspace instead of a single prompt view.

Each prompt appears as a card showing:

latest version
collection and role
markers such as stable or milestone
short preview of the prompt
last updated time

This makes it easier to scan a prompt library and understand what exists without opening each item.

Prompt detail view

Clicking a card opens a detailed view of the prompt.

This view includes:

full prompt text
version metadata
markers and labels
version timeline
side-by-side comparison

The goal is to make it easy to understand how a prompt evolved over time.

What changed in v0.6

Workspace instead of viewer

The dashboard is no longer just a viewer. It is a workspace where prompts can be explored and organized visually.

Card-based interaction

Prompts are now treated as objects instead of rows in a list. Cards provide quick context and actions.

Marker actions in the UI

Stable and milestone markers can now be applied directly from the dashboard. These actions use the same underlying marker system as the CLI.

Compare workflow

The compare view has been improved to clearly show differences between versions.

Usability improvements

keyboard shortcuts for faster navigation
copy actions with feedback
better empty states
improved hover and selection behavior

Design direction

PromptLedger remains intentionally limited in scope.

It is:

local-first
SQLite-backed
CLI-driven for write operations
dashboard-driven for inspection and workflow

It does not include:

cloud services
telemetry
external APIs
AI features

This boundary is important.

The goal is not to build another platform, but to provide a reliable tool for working with prompt history.

Installation

pip install --upgrade promptledger

Run the dashboard

promptledger dashboard

Closing

v0.6 is a shift from storing prompt history to working with it.

The dashboard is not meant to replace the CLI, but to complement it by making prompt iteration easier to inspect, compare, and organize.

There is still a lot to improve, but this version establishes a clearer direction:

PromptLedger is becoming a tool for thinking about prompts, not just storing them.

Links

PyPI: PyPI
GitHub: GitHub
LinkedIn: LinkedIn
Website: Website

OpenAnima v0.2 Preview: Turning the Windows Desktop into a Living Canvas

Ertugrul — Fri, 01 May 2026 10:31:23 +0000

OpenAnima v0.2 Preview: Turning the Windows Desktop into a Living Canvas

I recently published OpenAnima v0.2 Preview, and this release is a big step for the project.

OpenAnima started as a small experiment: what if I could place animated GIFs directly on my Windows desktop as movable overlay objects?

That simple idea quickly became more interesting.

Instead of only supporting GIFs, OpenAnima is now moving toward a more general goal:

An open-source desktop asset overlay engine for Windows.

The idea is to make the desktop feel less static. OpenAnima lets you place animated assets, sprites, frame animations, HUD elements, and game-style visual assets directly on your desktop, then control how they behave.

Website: https://ertugrulmutlu.github.io/OpenAnima/
Itch.io: https://ertugrulmutlu.itch.io/openanima
GitHub: https://github.com/Ertugrulmutlu/OpenAnima
Release: https://github.com/Ertugrulmutlu/OpenAnima/releases/tag/v0.2.0-preview

What OpenAnima does

OpenAnima is a Windows desktop application that lets users add visual assets on top of their desktop.

These assets can be moved around, configured, and used as lightweight desktop overlays.

Some example use cases:

Desktop companions or animated mascots
Game-style HUD elements
Stream or recording overlays
Sprite and animation preview experiments
Ambient desktop widgets
Weird little visual experiments

The project is still early, but the direction is becoming clearer: OpenAnima is not just a GIF player. It is becoming a small visual layer above the desktop.

Why I built it

I like projects that feel small at first, but slowly reveal a larger design space.

At the beginning, OpenAnima was simply about putting GIFs on the desktop. That was already fun, but it also felt limited.

Once I started thinking about game assets, HUD elements, sprites, and layered UI assets, the project became more like a desktop rendering playground.

I wanted to explore questions like:

Can desktop overlays be treated like reusable visual assets?
Can a normal desktop become a small interactive canvas?
Can game-style assets live outside a game engine?
Can asset packs become something users can import, configure, and reuse?

That is where the v0.2 release comes in.

What changed in v0.2

The v0.2 preview expands OpenAnima from a GIF overlay tool into a more metadata-driven desktop asset engine.

The biggest changes are:

Generic asset analyzer and import wizard
asset.json metadata support
Support for multiple asset formats
Sprite strip setup workflow
Spritesheet rendering with named animations
Composite UI/HUD assets
Runtime sliders for layered UI assets
Improved Editor tab and Asset Setup dialog layouts
Safer metadata validation and error handling
Backward compatibility for existing GIF/static/frame-folder workflows

This release is still a preview, but the foundation is much stronger than the first version.

Supported asset types

OpenAnima v0.2 supports several asset types:

GIF
Static image
Frame-folder animation
Sprite strip
Spritesheet
Composite UI / HUD

The first version was mostly focused on simple animated overlays. v0.2 starts building the system needed for more structured assets.

Metadata-driven assets

One of the most important changes in v0.2 is asset.json support.

Instead of hardcoding every asset type, OpenAnima can now use metadata to understand how an asset should be loaded and rendered.

A simplified example could look like this:

{
  "name": "demo_hud",
  "type": "composite_ui",
  "layers": [
    {
      "name": "background",
      "file": "background.png",
      "x": 0,
      "y": 0
    },
    {
      "name": "bar",
      "file": "bar.png",
      "x": 12,
      "y": 20
    }
  ]
}

This makes the project more flexible. Instead of treating every asset as just an image or GIF, OpenAnima can start understanding assets as structured objects.

That opens the door for asset packs, richer UI overlays, and more advanced configuration later.

Sprite strips and spritesheets

Another focus of v0.2 was better support for game-style assets.

Sprite strips and spritesheets are common in game development, but they usually need some setup before they can be used correctly.

OpenAnima now includes workflows for:

Frame count
Frame size
Crop fields
Preview grid
Frame export
Named animations for spritesheets

This is still not perfect, especially for unusual sprite layouts, but it is a good step toward making OpenAnima useful for more than simple GIF overlays.

Composite UI and HUD assets

I also added support for composite UI/HUD assets.

The idea is simple: an overlay does not have to be one image. It can be made from multiple layers.

For example:

A health bar background
A fill layer
A frame layer
A text or icon layer
Runtime sliders controlling values

This makes it possible to experiment with game-like desktop HUDs.

The current Composite UI editor is functional, but it is not meant to be a professional layout tool yet. It is more of a foundation for future versions.

The control panel

OpenAnima has a small control panel with three main areas:

Library
Active
Editor

The Library tab is used to import and manage assets.

The Active tab is used to manage overlays currently placed on the desktop.

The Editor tab is used to adjust selected assets with controls like:

Scale
Opacity
Speed
Always on top
Click-through
Locked

The goal is to keep the interface practical and lightweight. I do not want OpenAnima to become a huge desktop suite. I want it to stay small, hackable, and focused.

Website and distribution

For this release, I also created a small website for the project:

https://ertugrulmutlu.github.io/OpenAnima/

The website explains the idea, shows the demo, links to the GitHub repository, and provides access to the Windows executable through GitHub Releases.

I also published the project on itch.io as a free tool:

https://ertugrulmutlu.itch.io/openanima

This was mainly to make the project feel more like a small product rather than only a repository.

Known limitations

This is still a preview release, so some limitations are expected.

Known issues include:

Sprite strips may require manual frame count or frame size correction.
Some sprite strips with unusual padding may need manual crop values.
Spritesheets require metadata or setup through the import wizard.
Composite UI assets may require manual layer alignment.
The Composite UI editor is functional but not a full professional layout tool.
3D model support is not included yet.
Some unusual asset packs may still need manual asset.json editing.

I prefer being clear about this because v0.2 is not a polished final product. It is a foundation release.

What I want to explore next

There are several directions I want to explore after v0.2:

Asset packs
Better first-run experience
More polished installer/distribution flow
Better preview and import tools
More reliable spritesheet workflows
Simple 3D overlay experiments
Linux experiments later
Better documentation for custom assets

The 3D direction is especially interesting, but I do not want to rush it before the 2D asset foundation is stable.

What I learned

This project reminded me that even small desktop tools can become surprisingly deep.

At first, the problem looked simple:

Put an animated object on the desktop.

But once I started supporting different asset types, the project became about importing, validating, describing, previewing, rendering, and controlling assets.

That means the real challenge is not only drawing something on the desktop. The real challenge is creating a flexible system around desktop assets.

OpenAnima v0.2 is my first serious step in that direction.

Links

Website: https://ertugrulmutlu.github.io/OpenAnima/
GitHub: https://github.com/Ertugrulmutlu/OpenAnima
Release: https://github.com/Ertugrulmutlu/OpenAnima/releases/tag/v0.2.0-preview
itch.io: https://ertugrulmutlu.itch.io/openanima

Feedback, bug reports, weird desktop overlay ideas, and asset workflow suggestions are very welcome.

Thanks for reading.

PromptLedger v0.4 — Faster prompt logging, lightweight markers, and better prompt organization

Ertugrul — Mon, 27 Apr 2026 15:19:18 +0000

Devlog — Part 4

PromptLedger v0.4 is mostly about making prompt versioning easier to use repeatedly: faster logging, clearer organization, and small release signals for versions worth remembering.

In the earlier parts of this series, PromptLedger started as a deliberately small local-first prompt version control tool. Then it gained labels, status semantics, better diffs, review workflows, semantic summaries, warnings, and Markdown export.

Those additions made the history more useful after prompts had already been logged.

Some of the direction for v0.4 also came from feedback and from watching where the workflow still felt a bit too manual. So before going into the details: thank you to everyone who tried the earlier versions, shared thoughts, pointed out rough edges, or simply asked practical questions about how the tool should behave during real prompt iteration.

v0.4 focuses more on the moment before review: the actual day-to-day act of adding, organizing, and revisiting prompt versions.

Because in practice, a prompt version control tool only works if logging a prompt is cheap enough that you actually keep doing it.

Why this part was needed

PromptLedger has always been intentionally limited in scope.

It is SQLite-backed. It is terminal-first. It does not need a hosted backend. It does not try to execute prompts for you. It does not try to become an evaluation platform.

The core job is still simple:

store prompt versions
compare them
review changes
organize prompt history
make the history inspectable later

But once I started using it more like a real prompt library, a small problem became obvious.

Adding a prompt version was technically easy, but repetitive.

During actual prompt iteration, the prompt text changes often, while the surrounding metadata usually stays the same. The same author. The same environment. The same tags. The same library grouping. The same role.

Having to retype that metadata every time creates friction.

And friction matters. If logging is annoying, the history becomes incomplete. If the history is incomplete, review becomes less useful. And if review becomes less useful, the tool stops doing its main job.

So v0.4 is not a big architectural release.

It is a workflow release.

It makes repeated prompt logging faster, adds better organization primitives, and introduces lightweight markers for important versions.

Quick add: less typing during real iteration

The main usability change in v0.4 is the new add --quick workflow.

A normal add can still be explicit:

promptledger add --id onboarding --text "..." --collection support --role system

That is useful when creating a new prompt or when metadata should be stated clearly.

But once a prompt already exists, most iterations do not need all metadata to be typed again. With --quick, PromptLedger can reuse safe metadata defaults from the latest version of the same prompt id.

promptledger add --id onboarding --text "..." --quick

If the latest onboarding version already had metadata like author, tags, env, collection, and role, those values can be reused unless explicitly overridden.

That means the common workflow becomes much smaller:

edit the prompt
add the new version
keep moving

This is not a flashy feature, but it changes the feel of the tool.

Prompt logging becomes closer to a habit than a chore.

That matters because PromptLedger is not useful because one perfect prompt was saved once. It is useful because a sequence of changes becomes reviewable later.

Quick add is there to protect that sequence.

Collection and role are now first-class metadata

v0.4 also adds two first-class metadata fields on prompt versions:

collection
role

The reason is simple: once a prompt library grows, ids and tags are not always enough.

A collection gives prompts a lightweight grouping. It can represent a product area, a project, a use case, a customer support flow, an internal tool, or just a personal folder-like grouping.

For example:

promptledger add --id onboarding --text "..." --collection support --role system

This makes it easier to ask questions like:

Which prompts belong to the support collection?
Which prompts are part of an onboarding workflow?
Which versions were written for a specific environment or use case?

The second field, role, is about what kind of prompt artifact this version represents.

Built-in roles are:

system
user
template
modelfile
eval

This matters because prompt libraries usually contain different kinds of artifacts.

A system instruction is not the same thing as a reusable template. An evaluation prompt is not the same thing as a user-facing message. A model file prompt is not the same thing as an onboarding assistant instruction.

Before v0.4, these differences could be represented with tags, but tags are free-form and tend to become messy over time.

Making role first-class gives PromptLedger a small amount of structure without turning it into a large framework.

That is the balance I wanted here: enough organization to be useful, but not so much that the tool starts dictating how every prompt library must be designed.

Markers: small signals for important versions

v0.4 introduces a new marker system for prompt versions.

The core commands are:

promptledger marker set --id onboarding --version 8 --name stable

promptledger marker remove --id onboarding --version 8 --name stable

promptledger marker list --id onboarding

promptledger marker show --id onboarding --version 8

There are also convenience commands for the built-in markers:

promptledger stable --id onboarding

promptledger milestone --id onboarding

The built-in markers are:

stable
milestone

Markers are intentionally lighter than labels.

That distinction is important.

Labels in PromptLedger are useful when you want release-like semantics or named pointers. They can represent states such as a current production prompt, a reviewed version, or a version used in a specific workflow.

Markers are smaller than that.

A marker says: this version is worth noticing.

Maybe it was the first version that worked well. Maybe it was a milestone during a rewrite. Maybe it was stable enough to revisit later. Maybe it is just a checkpoint that should not get lost in the version list.

Not every important prompt version needs full label semantics.

Sometimes you only need a small flag attached directly to a version.

That is what markers are for.

They are deliberately simple. They do not try to encode deployment state, environment ownership, evaluation results, or production routing. They are just lightweight release signals inside the local history.

Search, list, and show became more useful

Organization only helps if the tools expose it.

So v0.4 updates list, show, and search to surface and use collection, role, and marker information.

For example, searching by metadata becomes more natural:

promptledger search --collection support --role system

Search can also work with an empty --contains, which means metadata-only filtering is now possible.

That sounds small, but it changes how PromptLedger can be used.

Before, search was mostly about finding prompt text. Now it can also be used to navigate the prompt library itself.

For example:

show all system prompts in a collection
find evaluation prompts across a project
inspect versions marked as stable
separate templates from user prompts
review one slice of the library without relying on text search

This moves PromptLedger a little further from “prompt version storage” toward “prompt library workflow”.

Still local. Still small. Still inspectable.

But more practical once the number of prompt artifacts grows.

The Streamlit UI is still read-only

PromptLedger also has a small Streamlit UI for inspecting prompt history.

In v0.4, the UI now surfaces collection, role, and markers in timeline, detail, and comparison views.

That makes the UI more useful when browsing a prompt library. You can see not only how a prompt changed, but also what kind of prompt it is, which collection it belongs to, and whether a version was marked as stable or as a milestone.

The important part: the UI is still read-only.

That is intentional.

For now, PromptLedger keeps editing and logging in the CLI, while the UI remains focused on inspection. This keeps the implementation smaller and avoids turning the viewer into a second source of write behavior.

The terminal is where versions are created.

The UI is where history can be reviewed more comfortably.

That split still feels right for the project.

Database changes stayed local and simple

v0.4 moves the schema version from 3 to 5.

The main database changes are straightforward:

a new markers table
new collection and role columns on prompt_versions
migrations for the local SQLite database

There is no remote migration service. No hosted registry. No account state. No backend coordination.

The migration story stayed aligned with the rest of the project: local, inspectable, and boring in a good way.

That matters because PromptLedger should remain easy to understand. A small SQLite-backed tool should not require infrastructure thinking just to store prompt history.

Tests expanded around the new workflows

v0.4 also expands the test coverage substantially around the areas that changed most:

add workflows
quick add behavior
marker commands
search and metadata filtering
related list/show behavior

This is not the kind of testing expansion that makes for a dramatic release note, but it is important for this project.

PromptLedger deals with history. If history is stored incorrectly, the tool loses trust quickly.

So the goal is practical correctness:

metadata should be reused only when expected
explicit overrides should still win
markers should attach to the right versions
search should return the intended slice of the prompt library
existing workflows should not become harder to use

For a local-first developer tool, confidence matters more than feature count.

Design tradeoffs

The main tradeoff in v0.4 was deciding how much structure to add.

PromptLedger could have gone further.

It could have introduced nested collections, custom role registries, marker categories, richer release channels, or project configuration files.

I avoided that for now.

The project works best when the concepts stay small:

ids identify prompt histories
versions preserve changes over time
labels provide stronger named semantics
markers provide lightweight version signals
collection groups prompt versions
role explains what kind of prompt artifact a version is

That is enough structure to make a growing prompt library easier to navigate, without making the tool feel like a platform.

This is also why markers are not labels with another name.

Labels are useful when you want something closer to a maintained pointer or status. Markers are useful when you want to annotate a version as notable.

Both can exist because they answer different workflow questions.

A label asks:

What does this version represent in a larger workflow?

A marker asks:

Is this version worth noticing later?

That difference is small, but it keeps the model clean.

What did not change

v0.4 does not change the basic philosophy of PromptLedger.

It is still a small, local-first prompt version control tool.

It still does not add:

hosted registry
prompt execution APIs
agent tooling
telemetry pipelines
cloud sync
automatic scoring
evaluation harnesses

Those are not bad ideas in general. They are just outside the current scope of this project.

PromptLedger is not trying to run prompts, score prompts, deploy prompts, or orchestrate agents.

It is trying to make prompt changes easier to store, compare, review, and organize.

That boundary is useful.

Small scope is not a missing feature here. It is part of the design.

Closing thoughts

PromptLedger v0.4 is a usability and organization release.

It does not radically change what the tool is. Instead, it makes the existing workflow smoother.

Quick add reduces friction during iteration. Collection and role make prompt libraries easier to navigate. Markers create a lightweight way to remember important versions. Search, list, show, and the read-only UI now expose more of that structure.

The result is still intentionally modest.

A local SQLite database. A CLI. A read-only inspection UI. Deterministic exports and reviewable history where possible.

But the day-to-day workflow feels better now.

And for a tool like this, that matters.

Because prompt version control only becomes useful when it is easy enough to use consistently.

Links

PyPI: PyPI
GitHub: GitHub
LinkedIn: LinkedIn
Website: Website