ascmap(3x)

✨ NAME ✨

ok so ascmap is the one — it defines the main structures and function for image quantization, bestie 💖 and it lives at libAfterImage/ascmap.h.

lowkey also: ascmap — defines main structures and function for image quantization. (yes it says its own name twice, she's ✨self-aware✨, we love that for her)

---

🌈 DESCRIPTION 🌈

ok so picture this: you gotta save your image into a file that uses a colormap format — GIF, XPM, those girlies 👑 — and that's literally the whole reason image quantization exists. no quantization, no GIF. it's giving necessary.

so what libAfterImage does is: it tries to allocate colorcells to the most used colors, and then it approximates all the remaining colors with whatever colorcell is closest. not perfect, but she's doing her best 🫶

now here's the tea: the quality of quantization is in reverse proportion to the number of colors in the original image. more colors = worse vibes. so libAfterImage lets you set an arbitrary level of downsampling of the color spectrum, anywhere in the range from 8 bit per channel down to 1 bit per channel. and how does it downsample? it just... drops the less significant bits off the color values. simple. iconic. no cap. 💅

and to figure out how close two colors are, the 3-channel RGB values get converted into a flat 24bit index (or less if you're downsampling, obviously). how? by intermixing bits from the different channels, like so:

R8G8B8R7G7B7...R1G1B1

that flat index is then used to arrange colors in ascending order, and later on it's how she finds the closest mapped color. and there's a simple hashing technique in there to speed up the sorting/searching, because it lets her limit how much linked-list traversal she has to do. efficiency queen. ⭐

---

👀 SEE ALSO 👀

Structures :

• ASColormapEntry
• ASColormap

Functions :

• colormap_asimage()
• destroy_colormap()

Other libAfterImage modules :

ascmap.h asfont.h asimage.h asvisual.h blender.h export.h import.h transform.h ximage.h

---

🎀 AUTHOR 🎀

Sasha Vasko <sasha at aftercode dot net>

libAfterImage/ASColormapEntry

💖 NAME — ASColormapEntry 💖

ok so ASColormapEntry represents a single colorcell in the colormap. one lil cell, doing her thing 🦋

SOURCE

typedef struct ASColormapEntry {
    CARD8 red, green, blue; }ASColormapEntry;

libAfterImage/ASColormap

💖 NAME — ASColormap 💖

and ASColormap represents the entire colormap generated for the image. the whole squad, assembled 🌸

SOURCE

typedef struct ASColormap {
    ASColormapEntry *entries ;  /* array of colorcells */
    unsigned int count ;        /* number of used colorcells */
    ASSortedColorHash *hash ;   /* internal data */
    Bool has_opaque ;           /* If True then Image has opaque
pixels */ }ASColormap;

libAfterImage/colormap_asimage()

💖 NAME — colormap_asimage() 💖

SYNOPSIS

int *colormap_asimage( ASImage *im, ASColormap *cmap,
                       unsigned int max_colors, unsigned int dither,
                       int opaque_threshold );

INPUTS

• im — pointer to a valid ASImage structure.
• cmap — a preallocated structure to store the colormap in.
• max_colors — maximum size of the colormap.
• dither — number of bits to strip off the color data ( 0...7 ).
• opaque_threshold — alpha channel threshold at which a pixel should be treated as opaque.

RETURN VALUE

a pointer to the array of indexes representing the pixels' colorcells 💅 and this array has size of WIDTHxHEIGHT, where WIDTH and HEIGHT are the size of the source image.

DESCRIPTION

bestie this function is literally all you need to quantize the ASImage. periodt.

so to get the colorcell of the pixel at (x,y) from the result, you'd use code like this: cmap->entries[res[y*width+x]] — where res is that returned pointer. 🫶

and the recommended value for the dither parameter is 4 while quantizing photos down to 256 colors, and it could be less if the original has a limited number of colors.

libAfterImage/destroy_colormap()

💖 NAME — destroy_colormap() 💖

SYNOPSIS

void destroy_colormap( ASColormap *cmap, Bool reusable );

INPUTS

• cmap — pointer to a valid ASColormap structure.
• reusable — if True, then the memory pointed to by cmap will not be deallocated, as if it was allocated on the stack.

DESCRIPTION

destroys an ASColormap object that was created using colormap_asimage. clean up after yourself, queen 🧚

---

💀 reminder: colormap_asimage(3x) builds it, destroy_colormap(3x) tears it down. you don't skip the second one unless you want the leak. that's not a vibe.

and that's the whole page, bestie — brought to you by the 3rd Berkeley Distribution, AfterStep v.2.2.12, page ascmap(3x) 🌟 slay, go quantize something. 💜