###########################################################################
#
#  Collection of routines related to Windows BMP images
#
#
###########################################################################

import struct


# helper function: converts an integer n to binary string occupying
# specified number of bytes b (doesn't check for errors!)
def istr(n, b):
    return struct.pack('<q', n)[:b]

# create a colormap
def init_cmap(maxcol):
    cmap = {maxcol: 3*'\0'}
    for i in range(maxcol):
        r, g, b = (630-i*2)%256, (i*27)%256, (10000-i*7)%256
    # alternative colormap: contiguous hue sweep in HSV space
    #hue_range = 270
    #for i in range(maxcol):
    #    s = i*hue_range/(60.0*maxcol)
    #    s, f = int(s), s-int(s)
    #    r = int(255*(1, 1-f, 0, 0, f, 1)[s])
    #    g = int(255*(f, 1, 1, 1-f, 0, 0)[s])
    #    b = int(255*(0, 0, f, 1, 1, 1-f)[s])
        cmap[i] = chr(b)+chr(g)+chr(r)
    return cmap

# helper function: returns additive pad to make a number divisible by 4
def pad4(n):
    r = n%4
    return (0, 4-r)[r > 0]

# create a colormap, open image file and write out BMP header
def init_image(fname, x, y):
    f = file(fname, 'w')
    # BMP header
    hdr = 'BM'+istr(26+y*(3*x+pad4(3*x)), 4)+4*'\0'+istr(26, 4)
    # pixmap info (OS/2 V1 header)
    hdr += istr(12, 4)+istr(x, 2)+istr(y, 2)+istr(1, 2)+istr(24, 2)
    f.write(hdr)
    return f, len(hdr)

# obtain properly padded buffer containing image row data
def padded_row(f, cmap, rdata):
    row = ''.join(map(lambda x: cmap[x], rdata))
    return row+pad4(len(row))*'\0'

# store any single row of image in file
def write_row(f, hsize, cmap, rnum, rdata):
    f.seek(hsize+len(rdata)+pad4(3*len(rdata))*rnum)
    f.write(padded__row(f, cmap, rdata))

# save image in BMP format, converting every pixel into RGB color value
def write_image(fname, xs, ys, data, ncolors):
    cmap = init_cmap(ncolors)
    f, hsz = init_image(fname, xs, ys)
    for row in data:
        f.write(padded_row(f, cmap, row))