DEV Community: Nabeel Ahmed

Writing a Multithreaded Image Dithering Program with Rust 🦀🖼️

Nabeel Ahmed — Sat, 18 Mar 2023 19:23:37 +0000

Check out the project here: https://github.com/NabeelAhmed1721/ordered-dithering/

I have been interested in the Rust programming language for the past couple of months. Coming from JavaScript, a weakly typed language, I find that Rust is much more strict and requires more thought when developing a control flow.

Just for the record, dithering isn't usually done on the CPU. It's a task best suited for a GPU, where it can take advantage of parallelism. I used this project as a way to learn about Rust and multithreading. If you want a guide for dithering done on a GPU, take a look at this.

Overview

Simply put, dithering is the process of adding noise to quantized data. To understand quantized data, think about omitting information needed to represent some data, for example, using less color to express an image.

It's important to note that dithering is a general term in information processing. With its use stretching far into audio, radar, weather, and many other applications, it isn't limited to images.

There are several image dithering techniques, my project uses Ordered or Bayer Dithering. Is it the most practical? Probably not. But if you ask me, I think it visually looks the most interesting.

Anyway, before we dive into the project itself, here are some results to entice you to continue reading:

Dithered Image of Apple (8-bit color)

Dithered Image of Sunlight through Leaves (8-bit color)

Dithered Image of Lava (8-bit color)

Ordered Dithering

To dither an image using ordered dithering, we must compare every pixel in the source image with an input palette and a threshold matrix (commonly referred as Bayer Matrix or Filter).

For the sake of consistency, our project will use an 8-bit color palette, which includes the following colors:

const PALETTE: [Color; 8] = [
    Color(0, 0, 0),          // black
    Color(255, 0, 0),        // red
    Color(0, 255, 0),        // green 
    Color(0, 0, 255),        // blue
    Color(255, 255, 0),      // yellow
    Color(255, 0, 255),      // magenta
    Color(0, 255, 255),      // cyan
    Color(255, 255, 255),    // white
];

You are free to use any assortment of colors, however, I find that the 8-bit color range has a reliable balance of colors that works for most images.

To generate a threshold matrix, we can use the following recursion formula to create a Bayer Matrix to the $n$ 'th level:

\begin{bmatrix} 4 \cdot Bayer(n - 1) + 0 & 4 \cdot Bayer(n - 1) + 2 \\ 4 \cdot Bayer(n - 1) + 3 & 4 \cdot Bayer(n - 1) + 1 \end{bmatrix}

where for every $n$ 'th level, the matrix is $2n+1×2n+12^{n+1} \times 2^{n+1}$ and contains numbers from $0$ to $2^{2n+2}$ .

Full credit of this equation and a special thanks goes to this wonderful article by Surma.

In practice, however, this type of computation quickly becomes expensive to generate during runtime, so it's more reasonable to reference from a pre-generated matrix. Hence, why my program uses a pre-generated $\times 8$ threshold matrix, which looks like the following:

\begin{bmatrix} 0 & 32 & 8 & 40 & 2 & 34 & 10 & 42 \\ 48 & 16 & 56 & 24 & 50 & 18 & 58 & 26 \\ 12 & 44 & 4 & 36 & 14 & 46 & 6 & 38 \\ 60 & 28 & 52 & 20 & 62 & 30 & 54 & 22 \\ 3 & 35 & 11 & 43 & 1 & 33 & 9 & 41 \\ 51 & 19 & 59 & 27 & 49 & 17 & 57 & 25 \\ 15 & 47 & 7 & 39 & 13 & 45 & 5 & 37 \\ 63 & 31 & 55 & 23 & 61 & 29 & 53 & 21 \\ \end{bmatrix}

The differences in matrix sizes reflect the complexity of the dithering pattern on the output image. A small $\times 2$ matrix produces an output with striking contrast and a rugged dithering pattern. While a larger $32 \times 32$ matrix results in smoother contrast with a granular dithering pattern. However, there are diminishing returns with larger matrix sizes— I find that an $\times 8$ matrix works best to smooth colors but also maintain that pixelated-dithered look.

To reduce complexity, I express the matrix as a 2D array, and through the calculations below, I can convert the x-y coordinates of the image to a value I can use to index the array:

// 8x8 Bayer Matrix
const MATRIX_WIDTH: u32 = 8;
const MATRIX: [u16; 64] = [
    0, 32, 8, 40, 2, 34, 10, 42, 48, 16, 56, 24, 50, 18, 58, 26, 12, 44, 4, 36,
    14, 46, 6, 38, 60, 28, 52, 20, 62, 30, 54, 22, 3, 35, 11, 43, 1, 33, 9, 41,
    51, 19, 59, 27, 49, 17, 57, 25, 15, 47, 7, 39, 13, 45, 5, 37, 63, 31, 55,
    23, 61, 29, 53, 21,
];

fn get_bayer(x: u32, y: u32) -> u16 {
    let pos = x % MATRIX_WIDTH
            + ((y * MATRIX_WIDTH) % (MATRIX_WIDTH * MATRIX_WIDTH));

    MATRIX[pos as usize]
}

We need to, however, map the threshold value from $0, 2^{2n+2}]$ to $[0, 255]$ because the RGB color values of the input image will be between 0 and 255. To solve this, I used a simple range mapping formula:

pub fn map_range_value(
    value: u32,
    range_in: (u32, u32),
    range_out: (u32, u32),
) -> u32 {
    return (value - range_in.0) * (range_out.1 - range_out.0)
        / (range_in.1 - range_in.0)
        + range_out.0;
}

Combining what we know, we can calculate our threshold value for a given pixel at an x-y coordinate with the following expression:

let bay = utility::map_range_value(
    Dither::get_bayer(x, y),
    (0, 64),
    (0, 255),
);

To calculate the quantized value of a given pixel color, we multiply the bay value with a spread value. The product is then summed with the input color, which is adjusted by a gamma value:

let quantize_value = |c: u8| -> u8 {
    f32::min(
        255.0 * f32::powf(f32::from(c) / 255.0, self.gamma)
            + self.spread * f32::from(bay),
        255.0,
    ) as u8
};

let query_color =
    Color(quantize_value(r), quantize_value(g), quantize_value(b));

Finally, we use query_color to search for the closest match in the defined palette. The closest color match is then set as the pixel value at the given x-y coordinate on the output image. Repeating this process for every pixel in an input image will result in an dithered output image.

Multithreading

Since the dithering process itself can run on each pixel independently, in other words, an individual pixel doesn't need to know the state of another pixel, this creates an ideal opportunity for multithreading. Fortunately, because of Rust's borrow checker, multithreading is simple and intuitive. Common bugs such as data races, locks, and memory leaks, are harder to encounter.

Depending on the application, multithreading can get hard to manage. I find it helpful to visualize the control flow to prevent confusion when programming. The following is how I expect my program to run:

Dividing the image into separate even chunks allows for a convenient collection process. Since each thread is assigned an ID, we can use the following formulas to calculate the starting and ending locations of each chuck:

let thread_location_start =
    (area / self.thread_count) * thread_id;

let mut thread_location_end =
    (area / self.thread_count) * (thread_id + 1) - 1;

// looping through specific chunk
for i in thread_location_start..thread_location_end {
    // dithering logic...
}

To identify and manage threads, I created separate helper module called worker. Within the module, a struct called Manager stores all threads (individually called Worker) in a vec and executes a collect method when threads complete. Overall, this allowed me to abstract multithreading logic and keep my code more manageable.

let mut manager = worker::Manager::<DitherJob>::new(THREAD_COUNT);
let worker_count = manager.worker_count;

let dither = Arc::new(Dither::new(
    worker_count,
    reference_image,
    &PALETTE,
    GAMMA,
    SPREAD,
));

manager.set_workers(&|id| {
    let dither = Arc::clone(&dither);
    thread::spawn(move || dither.dither_section(id))
});

manager.collect(&mut output);

Notice how Dither is wrapped Arc::new. To safely share ownership of data across threads, an Atomic Reference Counter (Arc) needs to be used. It keeps count of the owners and drops the value when no threads are using it.

Conclusion

Overall, I’m pleased with how the program turned out. With me still learning Rust, this project has helped me to become more confident in using the language and allowed me to explore new ideas in image processing.

I hope you enjoyed reading my article, and again, feel free to check out the project below:

https://github.com/NabeelAhmed1721/ordered-dithering/

Thank you,
Nabeel Ahmed

Using React to Design a Minimalistic Link with an Icon

Nabeel Ahmed — Mon, 03 May 2021 16:36:41 +0000

I wanted to create my own link component to showcase my social media because a lot of the ones I found online just didn't fit my aesthetic. 👽🧞

Recently I wanted to update my portfolio website. It had been almost two years since I had updated it. I had come a long way from simple HTML+CSS+JS Apache Server websites. I had learned several stacks and technologies over this period, and I wanted to put a lot of this knowledge to use by putting it into a site that reflects me.

Designing

There isn't much to talk about here. I just let my creative juices flow and spent a solid hour on Figma. I was able to design the following:

If you are wondering about specifics, I used the Inter font and the Feather Icon library.

Implementation

For the demo, I used TypeScript, React, and CSS for my stack. Here is the final result:

I made minor changes along the way such as adjusting the color of the description under the title.

Technicalities

This component is super responsive. No really, go on the embedded CodeSandbox project, view it in another window, and watch it beautifully align the links as you resize the window. 🏗

I also purposely designed the link to be chunky so it feels comfortable to tap on a smaller screen.

These are the possible props for the link component:

type LinkBadgeProps = {
  icon: ReactNode;
  title: string;
  desc: string;
  link: string;
  color?: string;
};

Everything is quite self-explanatory, however, something to note is that color, which can be hex or RGB, is not needed. It'll just default to #111.

Conclusion

Overall, I am happy with how it turned out. Feel free to use this component in any way, just give me credit :).

Well, that's it. Thanks for reading my post and consider following me on Instagram @nabeelahmed_.

~ Nabeel Ahmed

Setting up Typescript with ESLint+Prettier on VSCode

Nabeel Ahmed — Fri, 23 Apr 2021 13:07:28 +0000

I spent way too long trying to find a decent or updated tutorial- so I made up myself.

Believe me when I say I've been there. Picture this, you wanted to start a new Typescript project you were going to abandon anyway in a week, and you wanted a clean workflow, so you spent way too long setting up your perfect environment. Soon, you realized that the configuration files weren't working, and so you abandoned the whole project.

Assumptions

Visual Studio Code installed
A Package Manager installed (Personally, I like Yarn 🧶)
You have a new empty project folder created and opened in VSCode

Installation

Open a terminal, cd to your project folder, and execute the following:

yarn add -D eslint prettier eslint-config-prettier eslint-config-standard eslint-plugin-prettier eslint-plugin-import eslint-plugin-node eslint-plugin-promise @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript ts-node-dev

Depending on how bad your internet speed is, you might want to get a coffee before you fall asleep waiting. 😴

Setup

In your workspace open package.json (create it if it doesn't already exist) and insert the following object:

"scripts": {
    "dev": "ts-node-dev --respawn -- src/",
    "build": "tsc"
},

Create a .eslintrc.js file in the root directory of the project and paste the following:

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  extends: [
    'standard',
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:import/errors',
    'plugin:import/warnings',
    'plugin:promise/recommended',
    'prettier',
  ],
  parserOptions: {
    ecmaVersion: 2015,
    sourceType: 'module',
  },
  plugins: ['prettier', '@typescript-eslint'],
  rules: {
    'comma-dangle': ['error', 'always-multiline'],
    'no-empty-pattern': ['off'],
    'no-undef': ['error'],
    'no-var': ['error'],
    'object-curly-spacing': ['error', 'always'],
    indent: ['off'],
    'prettier/prettier': [
      'error',
      {
        singleQuote: true,
        semi: true,
      },
    ],
  },
  env: {
    // change as necessary
    node: true,
  },
};

Feel free to add or remove rules, but personally I think they're perfect. Also, Here's a list of the environments (env) you can provide ESLint.

Next, create a .eslintignore file so you don't blow up your computer trying to lint all those files in node_modules and add the following to it:

node_modules
dist

Now update your VSCode settings to allow the ESLint to format code. You could complete this step using the GUI, but I am going to just directly edit the settings.json file for efficiency.

To open settings.json press f1, type "open settings JSON", and press enter. If the file didn't open, use this to locate it.

Once open, add the following:

{
    "editor.defaultFormatter": "dbaeumer.vscode-eslint",
    "eslint.format.enable": true,
    "eslint.packageManager": "yarn",
    "eslint.run": "onSave",
    "editor.formatOnSave": true,
}

You don't technically need "editor.formatOnSave": true", but it helps you from wasting time and typing commands to format your code. 🙄

Finally, create an src folder and put an index.ts file into it. Type some code in it like an idiot and then save it to see your code be beautifully formatted. 🧹✨

During development use the dev script to watch Typescript files and have them auto-executed every time you save. To start this, in a terminal execute:

yarn dev

For a production build, use the build script to transpile the code into a dist folder. To do this, run:

yarn build

That's about it. I like to keep things simple.

Finishing Up

At this point, everything should just work. If it's not working properly it's probably your fault (I tested this tutorial 3 times lol). To fix this, restart the tutorial or just Google it.

From here, you can go ahead and install DefinitelyTyped definitions for whatever packages you use. I'd suggest at least installing @types/node:

yarn -D @types/node

This will give you typed definitions for Node.js.

Conclusion

Well, that's it. Thanks for reading my post and consider following me on Instagram @nabeelahmed_.

~ Nabeel Ahmed

Setting up a Minimal Ubuntu VM on Windows and Mac

Nabeel Ahmed — Tue, 03 Nov 2020 18:08:04 +0000

How to install Ubuntu on a Virtual Machine

Author: Nabeel Ahmed

Please scroll down to the operating system you use. (Windows or Mac).

Windows 👾

It is much easier to set up a CLI (Command-Line Interface) environment for Windows as Microsoft has already implemented a Ubuntu subsystem virtual machine that is built onto Windows. Follow the steps below to install the subsystem:

Open the following link: https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6.
Click on the Get button and it should redirect you to the Microsoft Store app on your machine.
Install and wait for it to finish.
Once finished, type Ubuntu into the Start search box, and the app should pop up- click on it.
Once a Terminal is opened it should automatically begin the installation processes.
If you are prompted with the following message: The Windows Subsystem for Linux optional component is not enabled. Please enable it and try again. Complete the following steps to fix this else move to step 7:
1. Open Powershell as Administrator (right-click Powershell in Start and select Run as administrator).
2. Paste the following command into it: dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart.
3. After the previous command is done running, paste the following: dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart.
4. Finally, paste the following: wsl --set-default-version 2.
  1. If you run into the error of wsl is not recognized, paste the following command instead: Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
5. Once complete close Powershell and the Ubuntu Subsystem App and reopen the Ubuntu Subsystem App.
You will now be asked to fill in some details such as a UNIX username (pick anything you will remember your first name all lowercase should be enough) and a UNIX password (pick something you will remember because you will be using it a lot).
You are done! 👏

macOS 🍎

It is a little bit harder to install a Linux virtual machine on macOS as you have to create the Virtual Environment yourself. Follow the steps below to install the Virtual Machine:

Head over to the following URL and download VirtualBox, a free hypervisor that allows you to create virtualized environments on your machine. Make sure to click OS X hosts to start the download: https://www.virtualbox.org/wiki/Downloads.
As VirtualBox is downloading, install the Ubuntu Minimal disk alongside it, which will give us the CLI (Command-Line Interface) version of Ubuntu. Link for the download. Scroll down until you see your computer's architecture (64bit or 32bit) and click the latest version of Ubuntu within the list. The latest version should be number 1: https://help.ubuntu.com/community/Installation/MinimalCD.
Once VirtualBox has finished downloading, open the VirtualBox .dmg file. Double click on the .pkg icon in the VirtualBox drive folder to open the installation wizard. Once you complete the installation steps, close the drive window, and eject the drive.
Open System Preferences on Mac. Can be located by the following steps: Apple Logo (Absolute top-left of the screen) > System Preferences.
Open Security & Privacy and switch the tab to General.
Unlock the Lock that is located on the bottom left of the window. You will be prompted to enter your password.
Click Allow beside the blocked software warning (This is a security warning because VirtualBox enables virtualization onto your computer).
Finally, open the VirtualBox app. This can be located by simply typing VirtualBox into the Spotlight Search (which can be open by pressing cmd + space).
After opening VirtualBox, you should be prompted to a window that has an image of a Penguin with building tools.
Click the New button and complete the following steps:
1. On the window presented to you, type CS Ubuntu Machine into the name field- or whatever you'd like as long as you can remember the particular virtual machine.
2. For the Machine Folder, it should default to /Users/[your_username]/VirtualBox VMs, which is fine. If it doesn't default to that, make a folder called VirtualBox VMs in the Home directory and select that in VirtualBox.
3. For the Type field select: Linux.
4. For the Version field select: Ubuntu (64-bit) or Ubuntu (32-bit) depending on your computer's architecture (64bit or 32bit). Once done, click Continue.
5. For Memory Size drag the slider until it says 2048 MB or type 2048 into the input box on the right. (2GB is a healthy amount of RAM for Ubuntu Minimal). Once done, click Continue.
6. For Hard Drive click Create a virtual disk now. Once done, click Create.
7. For Hard disk file type click VDI (VirtualBox Disk Image). Once done, click Continue.
8. Select Dynamically allocated. Once done, click Continue.
9. Do not edit the text input that has the location to the .vdi file. The allocated drive space should be set to at least 20.00 GB (You can always change this later if you require more space). Once done, click Create.
At this point, you should have an empty machine on the left with the name: CS Ubuntu Machine or whatever you named it.
From here we need to add the .iso file of Ubuntu Minimal we downloaded earlier. This can be done by right-clicking the machine on the left and selecting Settings... from the drop-down menu.
Navigate to the Storage tab on the top menu and click the Empty CD/DVD icon under the Controller: IDE on the left.
Beside Optical Drive make sure it says IDE Secondary Master. Also, click on the checkbox that says Live CD/DVD if it isn't checked already.
Click on the CD/DVD icon beside Optical Drive and select Choose a disk file... in the drop-down menu. Navigate to your Downloads folder, select the mini.iso file (this is the Ubuntu Minimal Disk), and press Open.
Press OK in the settings menu and you should be brought back to the home page of the VirtualBox program.
Then, go ahead and select the machine on the left and press Start on the top menu above. This should pop up a window that has Ubuntu Minimal booting within it. If you are presented with a screen that asks to choose your virtual optical drive just press start as mini.iso should already be selected. If mini.iso is not appearing in the input box, you might have to restart steps starting from 12.
At this point in your virtual machine window should be presenting you with the Installer boot menu. If you accidentally click the screen and a message pops up asking You have clicked the mouse and to capture it, select cancel. If you pressed Capture by accident press the left cmd button to uncapture your mouse.
If the screen is too small, solve this by clicking the display option on the bottom row (The row should be filled with icons. The display icon is between the gray folder icon and the film camera icon). In the drop-down menu select: Virtual Screen 1 > Scale to 200% (autoscaled output).
From here select Install on the Ubuntu boot menu by pressing return on your keyboard.
Below are the steps to setup Ubuntu:
1. For language, choose English. Press the up arrow key or down arrow key to highlight an option and press return to select it.
2. For the country, select United States.
3. Select No to Detect keyboard layout?.
4. Select English (US) for Country of origin for keyboard.
5. Select English (US) again for Keyboard layout.
6. Wait for installation.
7. Leave hostname as ubuntu by pressing the down arrow key and selecting Continue.
8. Select United States for Ubuntu archive mirror country.
9. Select us.archive.ubuntu.com for Ubuntu archive mirror.
10. Do not enter HTTP proxy information leave it blank. Just press return.
11. Wait for further installation (this might take a minute or two).
12. After installation is complete, type your full name into the text field. Enter your first name with the last name; separated by a space. (e.g Nabeel Ahmed). Select Continue once you are done.
13. The next menu should automatically type your first name in lowercase as a username, which is fine. If you don't see anything in the input field, type your first name only in lower-case only (e.g nabeel) (You can technically write any lowercase username but it is better if you can remember it so you can log in with ease). Select Continue once you are done.
14. For the next menu type a password for your system. Make sure it is rememberable as you will be using it often. Select Continue once you are done.
15. Re-enter your password for the next menu for verification. Select Continue once you are done.
16. Select Yes if Ubuntu is properly displaying your timezone. Select No if it isn't and complete the steps it prompts you with fixing that.
17. Wait for more installation.
18. For the Partitioning method make sure to select Guided - use entire disk.
19. For Select disk to partition, you should only have one option as we only created one drive. Select the only option. If you see multiple drives you might need to delete your virtual machine and start back at step 10 (close the Ubuntu virtual machine window by pressing the close button and selecting Power off the machine. Once you are back to the VirtualBox's main page, right-click the virtual machine and select delete and then select remove then Delete all files).
20. Finally, select Yes to Write the changes to disks?
21. Wait for further installation (this might several minutes).
22. Once the installation has completed, select No automatic updates.
23. Wait for further installation.
24. For choose software to install do not select anything. Just press return.
25. Wait for further installation.
26. Select Yes for Install the GRUB boot loader to the master boot record?
27. Wait for further installation.
28. Select Yes for Is the system clock set to UTC?
29. Wait for further installation.
30. Finally, select Continue for Installation complete.
31. Once the virtual machine brings you back to the Installer boot menu, close the virtual machine window and select Power off the machine. The window should be gone now.
Once you return to the VirtualBox homepage, right-click your virtual machine on the left and select Settings...
Switch to the Storage tab and select the mini.iso below Controller: IDE.
On the right, click the CD/DVD icon beside the Optical Drive and select Remove Disk from Virtual Drive from the drop-down menu.
Press OK on the settings menu located at the bottom right of the menu.
Finally, click Start on the virtual machine.
Once a prompt for ubuntu login comes up type in your username (this should be just your first name lowercase).
For the Password prompt type in the password you chose.
If you did everything correctly, you should be logged in now and presented with a Linux shell.
You are done! 👏