# Copyright 2021 Nick Brassel (@tzarc) # Copyright 2023 Pablo Martinez (@elpekenin) # SPDX-License-Identifier: GPL-2.0-or-later # Quantum Graphics File "QGF" Image File Format. # See https://docs.qmk.fm/#/quantum_painter_qgf for more information. import functools from colorsys import rgb_to_hsv from types import FunctionType from PIL import Image, ImageFile, ImageChops from PIL._binary import o8, o16le as o16, o32le as o32 import qmk.painter def o24(i): return o16(i & 0xFFFF) + o8((i & 0xFF0000) >> 16) # Helper to convert from RGB888 to the QMK "dialect" of HSV888 def rgb888_to_qmk_hsv888(e): hsv = rgb_to_hsv(e[0] / 255.0, e[1] / 255.0, e[2] / 255.0) return (int(hsv[0] * 255.0), int(hsv[1] * 255.0), int(hsv[2] * 255.0)) ######################################################################################################################## class QGFBlockHeader: block_size = 5 def write(self, fp): fp.write(b'' # start off with empty bytes... + o8(self.type_id) # block type id + o8((~self.type_id) & 0xFF) # negated block type id + o24(self.length) # blob length ) ######################################################################################################################## class QGFGraphicsDescriptor: type_id = 0x00 length = 18 magic = 0x464751 def __init__(self): self.header = QGFBlockHeader() self.header.type_id = QGFGraphicsDescriptor.type_id self.header.length = QGFGraphicsDescriptor.length self.version = 1 self.total_file_size = 0 self.image_width = 0 self.image_height = 0 self.frame_count = 0 def write(self, fp): self.header.write(fp) fp.write( b'' # start off with empty bytes... + o24(QGFGraphicsDescriptor.magic) # magic + o8(self.version) # version + o32(self.total_file_size) # file size + o32((~self.total_file_size) & 0xFFFFFFFF) # negated file size + o16(self.image_width) # width + o16(self.image_height) # height + o16(self.frame_count) # frame count ) @property def image_size(self): return self.image_width, self.image_height @image_size.setter def image_size(self, size): self.image_width, self.image_height = size ######################################################################################################################## class QGFFrameOffsetDescriptorV1: type_id = 0x01 def __init__(self, frame_count): self.header = QGFBlockHeader() self.header.type_id = QGFFrameOffsetDescriptorV1.type_id self.frame_offsets = [0xFFFFFFFF] * frame_count self.frame_count = frame_count def write(self, fp): self.header.length = len(self.frame_offsets) * 4 self.header.write(fp) for offset in self.frame_offsets: fp.write(b'' # start off with empty bytes... + o32(offset) # offset ) ######################################################################################################################## class QGFFrameDescriptorV1: type_id = 0x02 length = 6 def __init__(self): self.header = QGFBlockHeader() self.header.type_id = QGFFrameDescriptorV1.type_id self.header.length = QGFFrameDescriptorV1.length self.format = 0xFF self.flags = 0 self.compression = 0xFF self.transparency_index = 0xFF # TODO: Work out how to retrieve the transparent palette entry from the PIL gif loader self.delay = 1000 # Placeholder until it gets read from the animation def write(self, fp): self.header.write(fp) fp.write(b'' # start off with empty bytes... + o8(self.format) # format + o8(self.flags) # flags + o8(self.compression) # compression + o8(self.transparency_index) # transparency index + o16(self.delay) # delay ) @property def is_transparent(self): return (self.flags & 0x01) == 0x01 @is_transparent.setter def is_transparent(self, val): if val: self.flags |= 0x01 else: self.flags &= ~0x01 @property def is_delta(self): return (self.flags & 0x02) == 0x02 @is_delta.setter def is_delta(self, val): if val: self.flags |= 0x02 else: self.flags &= ~0x02 ######################################################################################################################## class QGFFramePaletteDescriptorV1: type_id = 0x03 def __init__(self): self.header = QGFBlockHeader() self.header.type_id = QGFFramePaletteDescriptorV1.type_id self.header.length = 0 self.palette_entries = [(0xFF, 0xFF, 0xFF)] * 4 def write(self, fp): self.header.length = len(self.palette_entries) * 3 self.header.write(fp) for entry in self.palette_entries: fp.write(b'' # start off with empty bytes... + o8(entry[0]) # h + o8(entry[1]) # s + o8(entry[2]) # v ) ######################################################################################################################## class QGFFrameDeltaDescriptorV1: type_id = 0x04 length = 8 def __init__(self): self.header = QGFBlockHeader() self.header.type_id = QGFFrameDeltaDescriptorV1.type_id self.header.length = QGFFrameDeltaDescriptorV1.length self.left = 0 self.top = 0 self.right = 0 self.bottom = 0 def write(self, fp): self.header.write(fp) fp.write(b'' # start off with empty bytes... + o16(self.left) # left + o16(self.top) # top + o16(self.right) # right + o16(self.bottom) # bottom ) @property def bbox(self): return self.left, self.top, self.right, self.bottom @bbox.setter def bbox(self, bbox): self.left, self.top, self.right, self.bottom = bbox ######################################################################################################################## class QGFFrameDataDescriptorV1: type_id = 0x05 def __init__(self): self.header = QGFBlockHeader() self.header.type_id = QGFFrameDataDescriptorV1.type_id self.data = [] def write(self, fp): self.header.length = len(self.data) self.header.write(fp) fp.write(bytes(self.data)) ######################################################################################################################## class QGFImageFile(ImageFile.ImageFile): format = "QGF" format_description = "Quantum Graphics File Format" def _open(self): raise NotImplementedError("Reading QGF files is not supported") ######################################################################################################################## def _accept(prefix): """Helper method used by PIL to work out if it can parse an input file. Currently unimplemented. """ return False def _for_all_frames(x: FunctionType, /, images): frame_num = 0 last_frame = None for frame in images: # Get number of of frames in this image nfr = getattr(frame, "n_frames", 1) for idx in range(nfr): frame.seek(idx) frame.load() copy = frame.copy().convert("RGB") x(frame_num, copy, last_frame) last_frame = copy frame_num += 1 def _compress_image(frame, last_frame, *, use_rle, use_deltas, format_, **_kwargs): # Convert the original frame so we can do comparisons converted = qmk.painter.convert_requested_format(frame, format_) graphic_data = qmk.painter.convert_image_bytes(converted, format_) # Convert the raw data to RLE-encoded if requested raw_data = graphic_data[1] if use_rle: rle_data = qmk.painter.compress_bytes_qmk_rle(graphic_data[1]) use_raw_this_frame = not use_rle or len(raw_data) <= len(rle_data) image_data = raw_data if use_raw_this_frame else rle_data # Work out if a delta frame is smaller than injecting it directly use_delta_this_frame = False bbox = None if use_deltas and last_frame is not None: # If we want to use deltas, then find the difference diff = ImageChops.difference(frame, last_frame) # Get the bounding box of those differences bbox = diff.getbbox() # If we have a valid bounding box... if bbox: # ...create the delta frame by cropping the original. delta_frame = frame.crop(bbox) # Convert the delta frame to the requested format delta_converted = qmk.painter.convert_requested_format(delta_frame, format_) delta_graphic_data = qmk.painter.convert_image_bytes(delta_converted, format_) # Work out how large the delta frame is going to be with compression etc. delta_raw_data = delta_graphic_data[1] if use_rle: delta_rle_data = qmk.painter.compress_bytes_qmk_rle(delta_graphic_data[1]) delta_use_raw_this_frame = not use_rle or len(delta_raw_data) <= len(delta_rle_data) delta_image_data = delta_raw_data if delta_use_raw_this_frame else delta_rle_data # If the size of the delta frame (plus delta descriptor) is smaller than the original, use that instead # This ensures that if a non-delta is overall smaller in size, we use that in preference due to flash # sizing constraints. if (len(delta_image_data) + QGFFrameDeltaDescriptorV1.length) < len(image_data): # Copy across all the delta equivalents so that the rest of the processing acts on those graphic_data = delta_graphic_data raw_data = delta_raw_data rle_data = delta_rle_data use_raw_this_frame = delta_use_raw_this_frame image_data = delta_image_data use_delta_this_frame = True # Default to whole image bbox = bbox or [0, 0, *frame.size] # Fix sze (as per #20296), we need to cast first as tuples are inmutable bbox = list(bbox) bbox[2] -= 1 bbox[3] -= 1 return { "bbox": bbox, "graphic_data": graphic_data, "image_data": image_data, "use_delta_this_frame": use_delta_this_frame, "use_raw_this_frame": use_raw_this_frame, } # Helper function to save each frame to the output file def _write_frame(idx, frame, last_frame, *, fp, frame_offsets, metadata, **kwargs): # Not an argument of the function as it would then not be part of kwargs # This would cause an issue with `_compress_image(**kwargs)` missing an argument format_ = kwargs["format_"] # (potentially) Apply RLE and/or delta, and work out output image's information outputs = _compress_image(frame, last_frame, **kwargs) bbox = outputs["bbox"] graphic_data = outputs["graphic_data"] image_data = outputs["image_data"] use_delta_this_frame = outputs["use_delta_this_frame"] use_raw_this_frame = outputs["use_raw_this_frame"] # Write out the frame descriptor frame_offsets.frame_offsets[idx] = fp.tell() vprint(f'{f"Frame {idx:3d} base":26s} {fp.tell():5d}d / {fp.tell():04X}h') frame_descriptor = QGFFrameDescriptorV1() frame_descriptor.is_delta = use_delta_this_frame frame_descriptor.is_transparent = False frame_descriptor.format = format_['image_format_byte'] frame_descriptor.compression = 0x00 if use_raw_this_frame else 0x01 # See qp.h, painter_compression_t frame_descriptor.delay = frame.info.get('duration', 1000) # If we're not an animation, just pretend we're delaying for 1000ms frame_descriptor.write(fp) # Write out the palette if required if format_['has_palette']: palette = graphic_data[0] palette_descriptor = QGFFramePaletteDescriptorV1() # Convert all palette entries to HSV888 and write to the output palette_descriptor.palette_entries = list(map(rgb888_to_qmk_hsv888, palette)) vprint(f'{f"Frame {idx:3d} palette":26s} {fp.tell():5d}d / {fp.tell():04X}h') palette_descriptor.write(fp) # Write out the delta info if required if use_delta_this_frame: # Set up the rendering location of where the delta frame should be situated delta_descriptor = QGFFrameDeltaDescriptorV1() delta_descriptor.bbox = bbox # Write the delta frame to the output vprint(f'{f"Frame {idx:3d} delta":26s} {fp.tell():5d}d / {fp.tell():04X}h') delta_descriptor.write(fp) # Store metadata, showed later in a comment in the generated file frame_metadata = { "compression": frame_descriptor.compression, "delta": frame_descriptor.is_delta, "delay": frame_descriptor.delay, } if frame_metadata["delta"]: frame_metadata.update({"delta_rect": [ delta_descriptor.left, delta_descriptor.top, delta_descriptor.right, delta_descriptor.bottom, ]}) metadata.append(frame_metadata) # Write out the data for this frame to the output data_descriptor = QGFFrameDataDescriptorV1() data_descriptor.data = image_data vprint(f'{f"Frame {idx:3d} data":26s} {fp.tell():5d}d / {fp.tell():04X}h') data_descriptor.write(fp) def _save(im, fp, _filename): """Helper method used by PIL to write to an output file. """ # Work out from the parameters if we need to do anything special encoderinfo = im.encoderinfo.copy() # Store image file in metadata structure metadata = encoderinfo.get("metadata", []) metadata.append({"width": im.width, "height": im.height}) # Helper for prints, noop taking any args if not verbose global vprint verbose = encoderinfo.get("verbose", False) vprint = print if verbose else lambda *_args, **_kwargs: None # Helper to iterate through all frames in the input image append_images = list(encoderinfo.get("append_images", [])) for_all_frames = functools.partial(_for_all_frames, images=[im, *append_images]) # Collect all the frame sizes frame_sizes = [] for_all_frames(lambda _idx, frame, _last_frame: frame_sizes.append(frame.size)) # Make sure all frames are the same size if len(set(frame_sizes)) != 1: raise ValueError("Mismatching sizes on frames") # Write out the initial graphics descriptor (and write a dummy value), so that we can come back and fill in the # correct values once we've written all the frames to the output graphics_descriptor_location = fp.tell() graphics_descriptor = QGFGraphicsDescriptor() graphics_descriptor.frame_count = len(frame_sizes) graphics_descriptor.image_size = frame_sizes[0] vprint(f'{"Graphics descriptor block":26s} {fp.tell():5d}d / {fp.tell():04X}h') graphics_descriptor.write(fp) # Work out the frame offset descriptor location (and write a dummy value), so that we can come back and fill in the # correct offsets once we've written all the frames to the output frame_offset_location = fp.tell() frame_offsets = QGFFrameOffsetDescriptorV1(graphics_descriptor.frame_count) vprint(f'{"Frame offsets block":26s} {fp.tell():5d}d / {fp.tell():04X}h') frame_offsets.write(fp) # Iterate over each if the input frames, writing it to the output in the process write_frame = functools.partial(_write_frame, format_=encoderinfo["qmk_format"], fp=fp, use_deltas=encoderinfo.get("use_deltas", True), use_rle=encoderinfo.get("use_rle", True), frame_offsets=frame_offsets, metadata=metadata) for_all_frames(write_frame) # Go back and update the graphics descriptor now that we can determine the final file size graphics_descriptor.total_file_size = fp.tell() fp.seek(graphics_descriptor_location, 0) graphics_descriptor.write(fp) # Go back and update the frame offsets now that they're written to the file fp.seek(frame_offset_location, 0) frame_offsets.write(fp) ######################################################################################################################## # Register with PIL so that it knows about the QGF format Image.register_open(QGFImageFile.format, QGFImageFile, _accept) Image.register_save(QGFImageFile.format, _save) Image.register_save_all(QGFImageFile.format, _save) Image.register_extension(QGFImageFile.format, f".{QGFImageFile.format.lower()}") Image.register_mime(QGFImageFile.format, f"image/{QGFImageFile.format.lower()}")