jc-printer-sdk-ts 0.1.0 → 0.1.2

package/src/imagePrint.ts

@@ -0,0 +1,306 @@
+import { createLabelBuilder } from "./builder.js";
+import type { MaybePromise, PrintCallback, PrintDocument } from "./types.js";
+import {
+  type ImageDataSource,
+  type LoadedImage,
+  loadImageSources,
+} from "./browserImages.js";
+import type { NiimbotPrintTask } from "./niimbotProtocol.js";
+
+export interface FitRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ImagePrintSettings {
+  widthMm: number;
+  heightMm: number;
+  orientation?: number;
+  density?: number;
+  speed?: number;
+  copies?: number;
+  paperType?: number;
+  printMode?: number;
+  marginMm?: number;
+  fitMode?: "contain" | "cover";
+  printTask?: "auto" | NiimbotPrintTask;
+  dpi?: number;
+  threshold?: number;
+  printMultiple?: number;
+  color?: number;
+  quality?: number;
+  epc?: string;
+  meta?: Record<string, unknown>;
+  callback?: Partial<PrintCallback>;
+}
+
+export interface ResolvedImagePrintSettings {
+  widthMm: number;
+  heightMm: number;
+  orientation: number;
+  density: number;
+  speed: number;
+  copies: number;
+  paperType: number;
+  printMode: number;
+  marginMm: number;
+  fitMode: "contain" | "cover";
+  printTask: "auto" | NiimbotPrintTask;
+  dpi: number;
+  threshold: number;
+  printMultiple: number;
+  color?: number;
+  quality?: number;
+  epc?: string;
+  meta: Record<string, unknown>;
+  callback?: Partial<PrintCallback>;
+}
+
+export interface PrintableImageClient {
+  startPrintJob(
+    density: number,
+    paperType: number,
+    printMode: number,
+    callback: PrintCallback,
+  ): MaybePromise<void>;
+  commitDocument(document: PrintDocument): MaybePromise<void>;
+  endPrintJob(): MaybePromise<boolean>;
+  cancelJob?(): MaybePromise<boolean>;
+}
+
+export interface PrintImageResult {
+  document: PrintDocument;
+  images: LoadedImage[];
+}
+
+export type ImagePrintSource =
+  | ImageDataSource
+  | ArrayLike<ImageDataSource>
+  | Iterable<ImageDataSource>;
+
+export const DEFAULT_IMAGE_PRINT_SETTINGS: ResolvedImagePrintSettings = {
+  widthMm: 60,
+  heightMm: 40,
+  orientation: 0,
+  density: 3,
+  speed: 2,
+  copies: 1,
+  paperType: 1,
+  printMode: 1,
+  marginMm: 1,
+  fitMode: "contain",
+  printTask: "b1",
+  dpi: 0,
+  threshold: 127,
+  printMultiple: 8,
+  meta: {},
+};
+
+const imagePrintQueues = new WeakMap<PrintableImageClient, Promise<void>>();
+
+function finiteNumber(value: number | undefined, fallback: number): number {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+function positiveNumber(name: string, value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive number.`);
+  }
+  return value;
+}
+
+function positiveInteger(value: number, fallback: number): number {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+function normalizeSettings(settings: ImagePrintSettings): ResolvedImagePrintSettings {
+  const widthMm = positiveNumber("widthMm", finiteNumber(settings.widthMm, DEFAULT_IMAGE_PRINT_SETTINGS.widthMm));
+  const heightMm = positiveNumber("heightMm", finiteNumber(settings.heightMm, DEFAULT_IMAGE_PRINT_SETTINGS.heightMm));
+  const printTask = settings.printTask ?? DEFAULT_IMAGE_PRINT_SETTINGS.printTask;
+  const printMultiple = positiveInteger(
+    finiteNumber(settings.printMultiple, printTask === "b1" ? 8 : 1),
+    printTask === "b1" ? 8 : 1,
+  );
+  const resolved: ResolvedImagePrintSettings = {
+    widthMm,
+    heightMm,
+    orientation: finiteNumber(settings.orientation, DEFAULT_IMAGE_PRINT_SETTINGS.orientation),
+    density: finiteNumber(settings.density, DEFAULT_IMAGE_PRINT_SETTINGS.density),
+    speed: finiteNumber(settings.speed, DEFAULT_IMAGE_PRINT_SETTINGS.speed),
+    copies: positiveInteger(finiteNumber(settings.copies, DEFAULT_IMAGE_PRINT_SETTINGS.copies), DEFAULT_IMAGE_PRINT_SETTINGS.copies),
+    paperType: positiveInteger(finiteNumber(settings.paperType, DEFAULT_IMAGE_PRINT_SETTINGS.paperType), DEFAULT_IMAGE_PRINT_SETTINGS.paperType),
+    printMode: positiveInteger(finiteNumber(settings.printMode, DEFAULT_IMAGE_PRINT_SETTINGS.printMode), DEFAULT_IMAGE_PRINT_SETTINGS.printMode),
+    marginMm: Math.max(0, finiteNumber(settings.marginMm, DEFAULT_IMAGE_PRINT_SETTINGS.marginMm)),
+    fitMode: settings.fitMode ?? DEFAULT_IMAGE_PRINT_SETTINGS.fitMode,
+    printTask,
+    dpi: Math.max(0, finiteNumber(settings.dpi, DEFAULT_IMAGE_PRINT_SETTINGS.dpi)),
+    threshold: Math.max(0, Math.min(255, finiteNumber(settings.threshold, DEFAULT_IMAGE_PRINT_SETTINGS.threshold))),
+    printMultiple,
+    meta: { ...(settings.meta ?? {}) },
+    ...(Number.isFinite(settings.color) ? { color: Number(settings.color) } : {}),
+    ...(Number.isFinite(settings.quality) ? { quality: Number(settings.quality) } : {}),
+    ...(settings.epc ? { epc: settings.epc } : {}),
+    ...(settings.callback ? { callback: settings.callback } : {}),
+  };
+  return resolved;
+}
+
+function toPrintCallback(callback?: Partial<PrintCallback>): PrintCallback {
+  return {
+    onProgress: callback?.onProgress ?? (() => undefined),
+    onError: callback?.onError ?? (() => undefined),
+    onBufferFree: callback?.onBufferFree ?? (() => undefined),
+    onCancelJob: callback?.onCancelJob ?? (() => undefined),
+  };
+}
+
+function queueImagePrintJob<T>(
+  printer: PrintableImageClient,
+  run: () => Promise<T>,
+): Promise<T> {
+  const previous = imagePrintQueues.get(printer) ?? Promise.resolve();
+  const queued = previous.catch(() => undefined).then(run);
+  imagePrintQueues.set(
+    printer,
+    queued.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return queued;
+}
+
+export function fitRect(
+  boxWidth: number,
+  boxHeight: number,
+  contentWidth: number,
+  contentHeight: number,
+  mode: "contain" | "cover",
+): FitRect {
+  const safeBoxWidth = Math.max(0, boxWidth);
+  const safeBoxHeight = Math.max(0, boxHeight);
+  const safeContentWidth = Math.max(1, contentWidth);
+  const safeContentHeight = Math.max(1, contentHeight);
+  const scale =
+    mode === "cover"
+      ? Math.max(safeBoxWidth / safeContentWidth, safeBoxHeight / safeContentHeight)
+      : Math.min(safeBoxWidth / safeContentWidth, safeBoxHeight / safeContentHeight);
+  const width = safeContentWidth * scale;
+  const height = safeContentHeight * scale;
+
+  return {
+    x: (safeBoxWidth - width) / 2,
+    y: (safeBoxHeight - height) / 2,
+    width,
+    height,
+  };
+}
+
+export function buildPrintDocument(images: Iterable<LoadedImage>, settings: ImagePrintSettings): PrintDocument {
+  const loadedImages = Array.from(images);
+  if (!loadedImages.length) {
+    throw new Error("No images were provided for printing.");
+  }
+
+  const resolved = normalizeSettings(settings);
+  const builder = createLabelBuilder("mm");
+  builder.startJob(resolved.density, resolved.paperType, resolved.printMode);
+  builder.setTotalPrintQuantity(resolved.copies);
+
+  const margin = Math.max(0, resolved.marginMm);
+  const contentWidth = Math.max(0, resolved.widthMm - margin * 2);
+  const contentHeight = Math.max(0, resolved.heightMm - margin * 2);
+
+  for (const image of loadedImages) {
+    builder.drawEmptyLabel(resolved.widthMm, resolved.heightMm, resolved.orientation, []);
+    const box = fitRect(contentWidth, contentHeight, image.width, image.height, resolved.fitMode);
+    builder.drawLabelImage(image.dataUrl, margin + box.x, margin + box.y, box.width, box.height, {
+      actualSize: false,
+      rotation: 0,
+      scale: 1,
+      threshold: 0,
+    });
+  }
+
+  const document = builder.toDocument();
+  document.job.density = resolved.density;
+  document.job.paperType = resolved.paperType;
+  document.job.printMode = resolved.printMode;
+  document.job.totalQuantity = resolved.copies;
+  document.job.printMultiple = resolved.printMultiple;
+  if (resolved.color !== undefined) {
+    document.job.color = resolved.color;
+  }
+  if (resolved.quality !== undefined) {
+    document.job.quality = resolved.quality;
+  }
+  if (resolved.epc) {
+    document.job.epc = resolved.epc;
+  }
+  document.job.meta = {
+    ...resolved.meta,
+    widthMm: resolved.widthMm,
+    heightMm: resolved.heightMm,
+    speed: resolved.speed,
+    marginMm: resolved.marginMm,
+    fitMode: resolved.fitMode,
+    printTask: resolved.printTask,
+    dpi: resolved.dpi,
+    threshold: resolved.threshold,
+    imageCount: loadedImages.length,
+  };
+
+  return document;
+}
+
+export async function buildPrintDocumentFromSources(
+  sources: ImagePrintSource,
+  settings: ImagePrintSettings,
+): Promise<PrintDocument> {
+  const images = await loadImageSources(sources);
+  return buildPrintDocument(images, settings);
+}
+
+export async function printImageData(
+  printer: PrintableImageClient,
+  sources: ImagePrintSource,
+  settings: ImagePrintSettings,
+): Promise<PrintImageResult> {
+  return queueImagePrintJob(printer, async () => {
+    const resolved = normalizeSettings(settings);
+    const images = await loadImageSources(sources);
+    const document = buildPrintDocument(images, resolved);
+    const callback = toPrintCallback(resolved.callback);
+    let started = false;
+
+    try {
+      await printer.startPrintJob(resolved.density, resolved.paperType, resolved.printMode, callback);
+      started = true;
+      await printer.commitDocument(document);
+      await printer.endPrintJob();
+      return { document, images };
+    } catch (error) {
+      if (started && printer.cancelJob) {
+        try {
+          await printer.cancelJob();
+        } catch {
+          // Keep the original print error.
+        }
+      }
+      throw error;
+    }
+  });
+}
+
+export async function printCanvases(
+  printer: PrintableImageClient,
+  canvases: ArrayLike<HTMLCanvasElement | OffscreenCanvas> | Iterable<HTMLCanvasElement | OffscreenCanvas>,
+  settings: ImagePrintSettings,
+): Promise<PrintImageResult> {
+  return printImageData(printer, Array.from(canvases), settings);
+}

package/src/index.ts

@@ -3,3 +3,7 @@ export * from "./types.js";
 export * from "./builder.js";
 export * from "./transport.js";
 export * from "./client.js";
+export * from "./browserImages.js";
+export * from "./imagePrint.js";
+export * from "./niimbotProtocol.js";
+export * from "./webBluetoothTransport.js";

package/src/niimbotProtocol.ts

@@ -0,0 +1,355 @@
+import type { CanvasCommand, PrintDocument, PrintPage } from "./types.js";
+
+export type NiimbotPrintTask = "v4" | "b1";
+
+export interface NiimbotPrinterProfile {
+  modelId?: number;
+  protocolVersion?: number;
+  label: string;
+  task: NiimbotPrintTask;
+  dpi: number;
+  printheadWidthPx: number;
+  paceMs: number;
+}
+
+export interface NiimbotGeometry {
+  widthPx: number;
+  heightPx: number;
+  dpi: number;
+  printheadWidthPx: number;
+}
+
+export interface NiimbotRasterPage {
+  widthPx: number;
+  heightPx: number;
+  stride: number;
+  rows: Uint8Array[];
+  blackCounts: number[];
+}
+
+const MM_PER_INCH = 25.4;
+
+const modelProfiles = new Map<number, NiimbotPrinterProfile>([
+  [512, { modelId: 512, label: "D11", task: "b1", dpi: 203, printheadWidthPx: 96, paceMs: 10 }],
+  [513, { modelId: 513, label: "FUST", task: "b1", dpi: 203, printheadWidthPx: 96, paceMs: 10 }],
+  [514, { modelId: 514, label: "D11S", task: "b1", dpi: 203, printheadWidthPx: 96, paceMs: 10 }],
+  [528, { modelId: 528, label: "D11_H", task: "v4", dpi: 300, printheadWidthPx: 142, paceMs: 0 }],
+  [785, { modelId: 785, label: "B21_PRO", task: "v4", dpi: 300, printheadWidthPx: 591, paceMs: 0 }],
+  [4096, { modelId: 4096, label: "B1", task: "b1", dpi: 203, printheadWidthPx: 384, paceMs: 10 }],
+  [4097, { modelId: 4097, label: "B1 Pro", task: "v4", dpi: 300, printheadWidthPx: 567, paceMs: 0 }],
+  [4098, { modelId: 4098, label: "B1 SE", task: "b1", dpi: 203, printheadWidthPx: 384, paceMs: 10 }],
+  [4608, { modelId: 4608, label: "M2-H", task: "b1", dpi: 300, printheadWidthPx: 567, paceMs: 10 }],
+  [2304, { modelId: 2304, label: "D110", task: "b1", dpi: 203, printheadWidthPx: 96, paceMs: 10 }],
+  [2305, { modelId: 2305, label: "HI_D110", task: "b1", dpi: 203, printheadWidthPx: 120, paceMs: 10 }],
+  [2320, { modelId: 2320, label: "D110_M", task: "v4", dpi: 203, printheadWidthPx: 96, paceMs: 0 }],
+]);
+
+export function createFrame(cmd: number, data: number[] | Uint8Array = []): Uint8Array {
+  const payload = Array.from(data);
+  const packet = new Uint8Array(7 + payload.length);
+  packet[0] = 0x55;
+  packet[1] = 0x55;
+  packet[2] = cmd & 0xff;
+  packet[3] = payload.length & 0xff;
+  let checksum = packet[2] ^ packet[3];
+
+  for (let index = 0; index < payload.length; index += 1) {
+    const value = payload[index] & 0xff;
+    packet[4 + index] = value;
+    checksum ^= value;
+  }
+
+  packet[4 + payload.length] = checksum & 0xff;
+  packet[5 + payload.length] = 0xaa;
+  packet[6 + payload.length] = 0xaa;
+  return packet;
+}
+
+export function createConnectFrame(): Uint8Array {
+  const frame = createFrame(0xc1, [0x01]);
+  const packet = new Uint8Array(frame.length + 1);
+  packet[0] = 0x03;
+  packet.set(frame, 1);
+  return packet;
+}
+
+export function parseFrame(value: DataView): { cmd: number; data: number[] } | null {
+  if (value.byteLength < 7) {
+    return null;
+  }
+  if (value.getUint8(0) !== 0x55 || value.getUint8(1) !== 0x55) {
+    return null;
+  }
+  const cmd = value.getUint8(2);
+  const length = value.getUint8(3);
+  if (value.byteLength < length + 7) {
+    return null;
+  }
+
+  const data: number[] = [];
+  let checksum = cmd ^ length;
+  for (let index = 0; index < length; index += 1) {
+    const byte = value.getUint8(4 + index);
+    data.push(byte);
+    checksum ^= byte;
+  }
+
+  const packetChecksum = value.getUint8(4 + length);
+  if ((checksum & 0xff) !== packetChecksum) {
+    return null;
+  }
+  return { cmd, data };
+}
+
+export function identifyProfile(modelId?: number, protocolVersion?: number): NiimbotPrinterProfile | null {
+  if (modelId && modelProfiles.has(modelId)) {
+    const profile = modelProfiles.get(modelId)!;
+    return protocolVersion === undefined ? { ...profile } : { ...profile, protocolVersion };
+  }
+
+  if (protocolVersion === 3) {
+    return {
+      protocolVersion,
+      label: "Protocol 3 printer",
+      task: "b1",
+      dpi: 203,
+      printheadWidthPx: 384,
+      paceMs: 10,
+    };
+  }
+
+  if (protocolVersion && protocolVersion >= 4) {
+    return {
+      protocolVersion,
+      label: "Protocol 4+ printer",
+      task: "v4",
+      dpi: 300,
+      printheadWidthPx: 584,
+      paceMs: 0,
+    };
+  }
+
+  return null;
+}
+
+export function fallbackProfile(task: "auto" | NiimbotPrintTask, dpi: number): NiimbotPrinterProfile {
+  if (task === "b1") {
+    const safeDpi = dpi || 203;
+    return {
+      label: "Manual B1-compatible",
+      task: "b1",
+      dpi: safeDpi,
+      printheadWidthPx: safeDpi >= 300 ? 567 : 384,
+      paceMs: 10,
+    };
+  }
+
+  return {
+    label: task === "auto" ? "Auto fallback V4" : "Manual V4",
+    task: "v4",
+    dpi: dpi || 300,
+    printheadWidthPx: dpi && dpi < 250 ? 384 : 584,
+    paceMs: 0,
+  };
+}
+
+export function geometryFromPage(page: PrintPage, profile: NiimbotPrinterProfile): NiimbotGeometry {
+  const widthFromMm = Math.max(1, Math.round((page.width * profile.dpi) / MM_PER_INCH));
+  const heightPx = Math.max(1, Math.round((page.height * profile.dpi) / MM_PER_INCH));
+  return {
+    widthPx: Math.min(widthFromMm, profile.printheadWidthPx),
+    heightPx,
+    dpi: profile.dpi,
+    printheadWidthPx: profile.printheadWidthPx,
+  };
+}
+
+export async function rasterizeDocumentPage(
+  page: PrintPage,
+  printDocument: PrintDocument,
+  profile: NiimbotPrinterProfile,
+): Promise<NiimbotRasterPage> {
+  const geometry = geometryFromPage(page, profile);
+  const element = globalThis.document?.createElement("canvas");
+  if (!element) {
+    throw new Error("Canvas is required to rasterize the print image in the browser.");
+  }
+
+  element.width = geometry.widthPx;
+  element.height = geometry.heightPx;
+  const context = element.getContext("2d", { willReadFrequently: true });
+  if (!context) {
+    throw new Error("Failed to create a 2D canvas context for printing.");
+  }
+
+  context.fillStyle = "#ffffff";
+  context.fillRect(0, 0, element.width, element.height);
+
+  for (const command of page.commands) {
+    await drawCommand(context, command, page, profile);
+  }
+
+  const threshold = Number(printDocument.job.meta?.threshold ?? 128);
+  const imageData = context.getImageData(0, 0, element.width, element.height);
+  return encodeMonochrome(imageData, element.width, element.height, threshold);
+}
+
+export function createRowFrames(page: NiimbotRasterPage): Uint8Array[] {
+  const frames: Uint8Array[] = [];
+  let rowIndex = 0;
+
+  while (rowIndex < page.heightPx) {
+    const row = page.rows[rowIndex];
+    const blackCount = page.blackCounts[rowIndex];
+    let run = 1;
+    while (
+      rowIndex + run < page.heightPx &&
+      run < 200 &&
+      blackCount === page.blackCounts[rowIndex + run] &&
+      rowsEqual(row, page.rows[rowIndex + run])
+    ) {
+      run += 1;
+    }
+
+    if (blackCount === 0) {
+      frames.push(createFrame(0x84, [rowIndex >> 8, rowIndex & 0xff, run]));
+    } else {
+      frames.push(
+        createFrame(0x85, [
+          rowIndex >> 8,
+          rowIndex & 0xff,
+          0x00,
+          blackCount & 0xff,
+          (blackCount >> 8) & 0xff,
+          run,
+          ...row,
+        ]),
+      );
+    }
+    rowIndex += run;
+  }
+
+  return frames;
+}
+
+export function parseProtocolVersion(data: number[]): number | undefined {
+  if (data.length >= 13) {
+    const version = data[11] * 100 + data[12];
+    if (version >= 204 && version <= 299) {
+      return 3;
+    }
+    if (version >= 300 && version <= 301) {
+      return 4;
+    }
+    if (version >= 302) {
+      return 5;
+    }
+  }
+  return undefined;
+}
+
+export function parseModelId(data: number[]): number | undefined {
+  if (data.length >= 2) {
+    return (data[0] << 8) | data[1];
+  }
+  if (data.length === 1) {
+    return data[0] << 8;
+  }
+  return undefined;
+}
+
+async function drawCommand(
+  context: CanvasRenderingContext2D,
+  command: CanvasCommand,
+  page: PrintPage,
+  profile: NiimbotPrinterProfile,
+): Promise<void> {
+  if (command.kind !== "drawLabelImage") {
+    return;
+  }
+
+  const payload = command.payload as {
+    source?: unknown;
+    x?: unknown;
+    y?: unknown;
+    width?: unknown;
+    height?: unknown;
+  };
+  if (typeof payload.source !== "string") {
+    return;
+  }
+
+  const image = await loadImage(payload.source);
+  const scale = profile.dpi / MM_PER_INCH;
+  const x = clampPixel(Number(payload.x ?? 0) * scale, 0, context.canvas.width);
+  const y = clampPixel(Number(payload.y ?? 0) * scale, 0, context.canvas.height);
+  const width = clampPixel(Number(payload.width ?? page.width) * scale, 0, context.canvas.width - x);
+  const height = clampPixel(Number(payload.height ?? page.height) * scale, 0, context.canvas.height - y);
+
+  if (width > 0 && height > 0) {
+    context.drawImage(image, x, y, width, height);
+  }
+}
+
+function encodeMonochrome(
+  imageData: ImageData,
+  width: number,
+  height: number,
+  threshold: number,
+): NiimbotRasterPage {
+  const stride = Math.ceil(width / 8);
+  const rows: Uint8Array[] = [];
+  const blackCounts: number[] = [];
+
+  for (let y = 0; y < height; y += 1) {
+    const row = new Uint8Array(stride);
+    let total = 0;
+
+    for (let x = 0; x < width; x += 1) {
+      const offset = (y * width + x) * 4;
+      const alpha = imageData.data[offset + 3];
+      const luminance =
+        imageData.data[offset] * 0.299 +
+        imageData.data[offset + 1] * 0.587 +
+        imageData.data[offset + 2] * 0.114;
+      const black = alpha > 32 && luminance < threshold;
+      if (black) {
+        row[Math.floor(x / 8)] |= 0x80 >> (x % 8);
+        total += 1;
+      }
+    }
+
+    rows.push(row);
+    blackCounts.push(total);
+  }
+
+  return { widthPx: width, heightPx: height, stride, rows, blackCounts };
+}
+
+function loadImage(source: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new Error("Failed to decode print image."));
+    image.src = source;
+  });
+}
+
+function rowsEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function clampPixel(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) {
+    return min;
+  }
+  return Math.max(min, Math.min(max, Math.round(value)));
+}