Importing Images

Lopaka lets you bring any image into your embedded screen design and converts it to the binary format your platform needs — whether that's a 1-bit XBMP bitmap for a monochrome OLED or an RGB565 array for a color TFT.

There are two ways to start an import:

• Click the Image tool in the toolbar to open the Import Wizard.
• Drag a PNG or BMP file directly onto the canvas to skip the wizard and import with default settings.

The Import Wizard

The wizard opens as a modal. Press Escape or click outside it to cancel at any time.

Step 1 — Choose a source

Pick one of three import modes:

Icon Packs

Browse the built-in library of monochrome icons grouped by set (arrows, UI symbols, weather, etc.). A Current Project section at the top shows images you have already imported into this session — click any of them to reuse without re-uploading.

Click an icon to place it on the canvas immediately. The wizard closes and the layer is added.

When to use: You need a standard UI icon — battery, Wi-Fi, arrows, checkmarks — and don't want to prepare an image file.

Upload file

Drag one or more files onto the drop zone, or click Browse files to pick them from your filesystem. Accepted formats: any raster image (PNG, JPEG, BMP, WebP, etc.) and .gif.

• Multiple files — all files are queued. You can preview each one, but settings apply to all images at once.
• GIF files — each frame is extracted as a separate image automatically.

When to use: You have a custom logo, icon, or photo you want to display on the screen.

Input byte array

Paste a raw XBMP byte array directly — the kind typically produced by image conversion tools or found in existing firmware. Enter the Width and Height of the bitmap, enable Swap bytes if the byte order doesn't match the preview, and watch the live preview update as you type. Example input:

0xFF, 0x81, 0x81, 0x81, 0xFF

When to use: You are migrating from existing firmware code that already has bitmap arrays, or you received a bitmap from a tool that exports raw byte data.

Step 2 — Adjust in the image editor

After uploading files the wizard advances to the image editor. The editor looks and behaves differently depending on whether you uploaded one file or many.

Single image

When you upload exactly one file, the full editor is shown:

• Name is editable — set the C variable name now (e.g. wifi_icon → const uint8_t wifi_icon[]).
• Dimensions controls are shown — resize and the crop area updates accordingly.
• Crop area is active — drag the blue rectangle to select only part of the image.

Everything you set is applied to that one image when you click Import.

Multiple images

When you upload more than one file — or upload a GIF — the editor switches to multi-image mode:

• A thumbnail strip appears on the left. Click any thumbnail to preview it in the editor.
• Each thumbnail has a checkbox. All images start checked. Uncheck any to exclude it from the import.
• Select all — appears in the strip header when at least one image is unchecked. Click it to restore the full selection.
• Name is not editable — it is derived from the filename automatically. Rename layers in the inspector after importing if needed.
• Dimensions and crop are not shown. Each image is auto-fitted to the display size at import time, independently.
• All other settings — resampling, brightness, contrast, dithering, invert — apply to every selected image when you click Import.

GIF files

A GIF is treated as multiple images. Each frame is extracted automatically and appears as a separate entry in the thumbnail strip, named basename_frame_1, basename_frame_2, and so on. A single-frame GIF keeps just the base name.

This means you can import an animated icon as a sequence of bitmap layers — one per frame — ready to cycle through in your firmware.

Zoom

Drag the zoom slider to magnify the preview (0.5× to 10×). Double-click the slider to reset to 1×. This does not affect the exported image — it is a preview aid only.

Color mode

Visible on platforms that support both monochrome and color (e.g. TFT_eSPI). Toggle between:

• Monochrome — 1-bit XBMP, very compact. Each pixel is either on or off. The image is dithered or thresholded to black and white.
• RGB — RGB565, 2 bytes per pixel. Preserves color. Use this for color displays.

Platforms that only support one mode lock the toggle automatically.

Dimensions

Set the target width and height. Editing one value scales the other proportionally.

• Reset — restores the original image dimensions.
• Fit Screen — scales the image to fit within the current display size while preserving aspect ratio.

Crop area

A blue selection rectangle overlays the preview. Only the area inside it is imported.

• Drag the center of the rectangle to reposition it.
• Drag any corner to resize it.
• Edit X / Y / W / H fields directly for precise control.

When to use crop: You have a large image and only need a specific region — e.g., a status bar icon inside a full-screen screenshot, or a single glyph from a sprite sheet.

Byte size

The Byte size readout below the preview updates live to show how much RAM the cropped bitmap will use:

• Monochrome: 1 bit per pixel, packed into bytes.
• RGB: 2 bytes per pixel (RGB565).

Resampling

Controls the algorithm used when the image is scaled down to the target dimensions:

Algorithm	When to use
none	No scaling — use when the source is already the right size
nearest	Pixel art and icons — preserves hard edges
bilinear	General purpose, smooth result
spline	Smoother than bilinear, good for photos
lanczos	High-quality downscaling, sharpest result
gaussian	Soft blur effect during downscaling
mitchell	Balanced between sharpness and ringing

For most logos and icons on monochrome displays, nearest or bilinear works well.

Brightness and contrast

Shift brightness from −100 % to +100 % and contrast from −100 % to +100 %. Double-click either slider to reset to 0.

When to use: A photograph looks washed out after conversion to monochrome — increase contrast to make the dark pixels darker and the light pixels lighter. If a logo has a light background that bleeds into the bitmap, increase contrast or decrease brightness to push it to white.

Grayscale first

Converts the image to grayscale before thresholding or dithering. Turn this on when your source image is colorful and the auto-conversion is producing an unexpected result — for example, a red logo on a white background where the red and white end up at similar perceived brightness.

Dithering (monochrome only)

Applies Floyd-Steinberg dithering. Instead of a hard threshold (pixel is either black or white), dithering distributes the quantization error to neighboring pixels, producing a halftone-like result that preserves perceived gradients.

• On: Photos, gradients, and images with many shades look better.
• Off: Line art, logos, and icons with solid fills look cleaner without dithering noise.

Invert palette (monochrome only)

Swaps black and white before the dithering step. Use this when your source image has a white symbol on a black background but the display renders it inverted, or when the auto-threshold is treating the wrong color as the foreground.

Invert result

Inverts the final bitmap after all processing. Use this when the image looks correct in the preview but renders inverted on the physical display — for example, on displays where the background color is white but the default is black.

After importing

Each imported image becomes a Paint (bitmap) layer on the canvas. The layer name matches the variable name used in the generated code.

You can continue editing the bitmap with the Paint tool — draw or erase individual pixels directly.