<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library;
/**
* Decodes a black-and-white image coded the way scanned text is coded,
* giving back one byte per pixel: 0 for black, 1 for white.
*
* This coding is defined by ITU-T Recommendation T.88, known as JBIG2. It
* is met as a PDF stream whose Filter is JBIG2Decode, which is how a
* scanner or a magazine's typesetter often carries lettering meant to be
* painted in one color.
*
* The coding contexts each pixel from the ten pixels already decoded
* around it, and writes only how wrong the guess was, using an arithmetic
* coder that spends less than one bit on a pixel it expects. Both the
* coder and the guessing are done here.
*
* What is handled and what is not:
* - A stream of segments as a PDF embeds them, of which the page
* information and an immediate generic region are read and the rest
* skipped.
* - Generic region decoding with the arithmetic coder, all four
* templates, the adaptive pixels the region names, and the
* typical-prediction shortcut where a region says a row repeats the one
* above it.
* - It does NOT handle: symbol dictionaries and text regions, which is
* how a scanner stores a page as reused letter shapes; refinement;
* halftone regions; or generic regions coded the fax way rather than
* arithmetically. Nothing comes back for those rather than a wrong
* picture.
*
* Typical use:
* $rows = JBig2::decode($bytes, $width, $height);
* // $rows[$y][$x] is 0 for black or 1 for white
*
* @author Chris Pollett
*/
class JBig2
{
/**
* The chance of the less likely answer at each state the arithmetic
* coder can be in, with where to move next when the guess was right,
* where to move when it was wrong, and whether being wrong turns the
* two answers around. This is the table T.88 gives.
* @var array
*/
const STATES = [
[0x5601, 1, 1, 1], [0x3401, 2, 6, 0], [0x1801, 3, 9, 0],
[0x0AC1, 4, 12, 0], [0x0521, 5, 29, 0], [0x0221, 38, 33, 0],
[0x5601, 7, 6, 1], [0x5401, 8, 14, 0], [0x4801, 9, 14, 0],
[0x3801, 10, 14, 0], [0x3001, 11, 17, 0], [0x2401, 12, 18, 0],
[0x1C01, 13, 20, 0], [0x1601, 29, 21, 0], [0x5601, 15, 14, 1],
[0x5401, 16, 14, 0], [0x5101, 17, 15, 0], [0x4801, 18, 16, 0],
[0x3801, 19, 17, 0], [0x3401, 20, 18, 0], [0x3001, 21, 19, 0],
[0x2801, 22, 19, 0], [0x2401, 23, 20, 0], [0x2201, 24, 21, 0],
[0x1C01, 25, 22, 0], [0x1801, 26, 23, 0], [0x1601, 27, 24, 0],
[0x1401, 28, 25, 0], [0x1201, 29, 26, 0], [0x1101, 30, 27, 0],
[0x0AC1, 31, 28, 0], [0x09C1, 32, 29, 0], [0x08A1, 33, 30, 0],
[0x0521, 34, 31, 0], [0x0441, 35, 32, 0], [0x02A1, 36, 33, 0],
[0x0221, 37, 34, 0], [0x0141, 38, 35, 0], [0x0111, 39, 36, 0],
[0x0085, 40, 37, 0], [0x0049, 41, 38, 0], [0x0025, 42, 39, 0],
[0x0015, 43, 40, 0], [0x0009, 44, 41, 0], [0x0005, 45, 42, 0],
[0x0001, 45, 43, 0], [0x5601, 46, 46, 0]];
/**
* How many pixels of contextAroundPixel the first template looks at
* @var int
*/
const TEMPLATE_PIXELS = 16;
/**
* The kind number a segment carries when it holds page information
* @var int
*/
const PAGE_SEGMENT = 48;
/**
* The kind numbers a segment carries when it holds a generic region
* drawn straight onto the page
* @var array
*/
const REGION_SEGMENTS = [36, 38, 39];
/**
* The bytes being read
* @var string
*/
public $bytes;
/**
* Where in the bytes reading has got to
* @var int
*/
public $at;
/**
* The part of the range the coder is working in
* @var int
*/
public $range;
/**
* What the coder has read so far, held against the range
* @var int
*/
public $held;
/**
* How many bits of the held value are still good
* @var int
*/
public $good;
/**
* Which state each guess is in, and which answer it thinks more
* likely
* @var array
*/
public $contexts = [];
/**
* Sets up an arithmetic coder over a run of bytes.
*
* @param string $bytes the coded bytes
* @param int $at where in them to begin
*/
public function __construct($bytes, $at = 0)
{
$this->bytes = $bytes;
$this->at = $at;
$this->startArithmeticDecoder();
}
/**
* Decodes an image, giving back one byte per pixel. The bytes are a
* run of segments as a document embeds them; the first generic region
* among them is the picture.
*
* @param string $bytes the coded image
* @param int $wide how many pixels across
* @param int $high how many rows
* @return array each row as a list of 0 for black and 1 for white,
* empty where the coding is one this does not handle
*/
public static function decode($bytes, $wide, $high)
{
$found = self::genericRegionIn($bytes);
if ($found === false) {
return [];
}
$reader = new JBig2($bytes, $found["at"]);
return $reader->readGenericRegion($found["wide"], $found["high"],
$found["template"], $found["adaptive"], $found["typical"]);
}
/**
* Finds the generic region among a run of segments, and reads what it
* says about how it was coded.
*
* @param string $bytes the coded image
* @return mixed where the region's data begins and how it was coded,
* or false where there is no generic region to read
*/
public static function genericRegionIn($bytes)
{
$at = 0;
$length = strlen($bytes);
$steps = 0;
while ($at + 11 <= $length && $steps < 64) {
$steps++;
$number = unpack("N", substr($bytes, $at, 4))[1];
$flags = ord($bytes[$at + 4]);
$kind = $flags & 0x3f;
$page_wide = ($flags & 0x40) ? 4 : 1;
$refs = ord($bytes[$at + 5]) >> 5;
if ($refs == 7) {
return false;
}
$each = ($number <= 256) ? 1 : (($number <= 65536) ? 2 : 4);
$header = $at + 6 + $refs * $each + $page_wide;
if ($header + 4 > $length) {
return false;
}
$said = unpack("N", substr($bytes, $header, 4))[1];
$begins = $header + 4;
if (in_array($kind, self::REGION_SEGMENTS)) {
return self::genericRegionSettings($bytes, $begins);
}
$at = $begins + $said;
}
return false;
}
/**
* Reads what a generic region says about itself: how large it is, how
* it contexts a pixel from its contextAroundPixel, and which surrounding
* pixels it moved.
*
* @param string $bytes the coded image
* @param int $at where the region's data begins
* @return mixed the region's settings, or false where it is coded a
* way this does not handle
*/
public static function genericRegionSettings($bytes, $at)
{
if ($at + 18 > strlen($bytes)) {
return false;
}
$wide = unpack("N", substr($bytes, $at, 4))[1];
$high = unpack("N", substr($bytes, $at + 4, 4))[1];
$flags = ord($bytes[$at + 17]);
if ($flags & 1) {
/* Coded the fax way rather than arithmetically, which is a
different decoder. */
return false;
}
$template = ($flags >> 1) & 3;
$typical = (($flags >> 3) & 1) == 1;
$pairs = ($template == 0) ? 4 : 1;
$adaptive = [];
$reads = $at + 18;
for ($step = 0; $step < $pairs; $step++) {
$first_byte = ord($bytes[$reads]);
$second_byte = ord($bytes[$reads + 1]);
$adaptive[] = [($first_byte > 127) ? $first_byte - 256 :
$first_byte, ($second_byte > 127) ? $second_byte - 256 :
$second_byte];
$reads += 2;
}
return ["at" => $reads, "wide" => $wide, "high" => $high,
"template" => $template, "adaptive" => $adaptive,
"typical" => $typical];
}
/**
* Sets the arithmetic coder going, which reads its first bytes and
* lines them up against the range.
*/
public function startArithmeticDecoder()
{
$this->held = $this->codedByteAt($this->at) << 16;
$this->takeNextCodedByte();
$this->held <<= 7;
$this->good -= 7;
$this->range = 0x8000;
}
/**
* Gives the byte at a place, or a settled value past the end so the
* coder can run on to the end of the picture.
*
* @param int $at which byte
* @return int the byte
*/
public function codedByteAt($at)
{
return ($at < strlen($this->bytes)) ? ord($this->bytes[$at]) : 0xff;
}
/**
* Takes in the next byte, which the coder does whenever it has used
* up the bits it holds.
*/
public function takeNextCodedByte()
{
if ($this->codedByteAt($this->at) == 0xff) {
if ($this->codedByteAt($this->at + 1) > 0x8f) {
$this->held += 0xff00;
$this->good = 8;
} else {
$this->at++;
$this->held += $this->codedByteAt($this->at) << 9;
$this->good = 7;
}
} else {
$this->at++;
$this->held += $this->codedByteAt($this->at) << 8;
$this->good = 8;
}
}
/**
* Reads one answer from the coder, given which guess is being asked.
* The guess remembers how often it has been right and moves to a
* state that spends fewer bits when it keeps being right.
*
* @param int $which which guess
* @return int the answer, 0 or 1
*/
public function readDecisionBit($which)
{
if (!isset($this->contexts[$which])) {
$this->contexts[$which] = [0, 0];
}
list($state, $likely) = $this->contexts[$which];
$chance = self::STATES[$state][0];
$this->range -= $chance;
$answer = $likely;
if ((($this->held >> 16) & 0xffff) < $chance) {
/* The less likely answer came up. */
if ($this->range < $chance) {
$this->range = $chance;
$this->contexts[$which] = [self::STATES[$state][1],
$likely];
} else {
$this->range = $chance;
$answer = 1 - $likely;
if (self::STATES[$state][3] == 1) {
$likely = 1 - $likely;
}
$this->contexts[$which] = [self::STATES[$state][2],
$likely];
}
} else {
$this->held -= $chance << 16;
if (($this->range & 0x8000) != 0) {
return $answer;
}
if ($this->range < $chance) {
$answer = 1 - $likely;
if (self::STATES[$state][3] == 1) {
$likely = 1 - $likely;
}
$this->contexts[$which] = [self::STATES[$state][2],
$likely];
} else {
$this->contexts[$which] = [self::STATES[$state][1],
$likely];
}
}
/* Whichever way it went, the range has shrunk below half, so it
and what is held are doubled until it is back above. */
do {
if ($this->good == 0) {
$this->takeNextCodedByte();
}
$this->range <<= 1;
$this->held = ($this->held << 1) & 0xffffffff;
$this->good--;
} while (($this->range & 0x8000) == 0);
return $answer;
}
/**
* Reads a region, guessing each pixel from those already read around
* it and asking the coder how wrong the guess was.
*
* @param int $wide how many pixels across
* @param int $high how many rows
* @param int $template which set of surrounding pixels to look at
* @param array $adaptive the surrounding pixels the region moved
* @param bool $typical whether a row may say it repeats the one above
* @return array each row as a list of 0 for black and 1 for white
*/
public function readGenericRegion($wide, $high, $template, $adaptive,
$typical)
{
$rows = [];
$marks = [];
$same = 0;
for ($down = 0; $down < $high; $down++) {
if ($typical) {
$same ^= $this->readDecisionBit(
[0x9b25, 0x0795, 0x00e5, 0x0195][$template] ??
0x9b25);
if ($same == 1 && $down > 0) {
$marks[$down] = $marks[$down - 1];
continue;
}
}
$marks[$down] = array_fill(0, $wide, 0);
for ($across = 0; $across < $wide; $across++) {
$marks[$down][$across] = $this->readDecisionBit(
$this->contextAroundPixel($marks, $across, $down, $wide,
$template, $adaptive));
}
}
/* A one in this coding means ink, where a picture wants 0 for
black, so the two are turned around here. */
foreach ($marks as $down => $row) {
$rows[$down] = [];
foreach ($row as $one) {
$rows[$down][] = ($one == 1) ? 0 : 1;
}
}
return $rows;
}
/**
* Gives which guess to ask for one pixel, by reading the pixels
* already decoded around it. Which pixels those are is what a
* template says, and a region may move a few of them.
*
* @param array $marks the rows decoded so far
* @param int $across which pixel along the row
* @param int $down which row
* @param int $wide how many pixels across a row is
* @param int $template which set of surrounding pixels
* @param array $adaptive the pixels the region moved
* @return int which guess
*/
public function contextAroundPixel($marks, $across, $down, $wide, $template,
$adaptive)
{
$places = self::templateOffsets($template, $adaptive);
$which = 0;
foreach ($places as $place) {
$which = ($which << 1) |
$this->pixelAt($marks, $across + $place[0],
$down + $place[1], $wide);
}
return $which;
}
/**
* Gives the pixels a template looks at, in the order their answers
* are strung together, with the ones the region moved put in place.
*
* @param int $template which set of surrounding pixels
* @param array $adaptive the pixels the region moved
* @return array each as how far across and how far up
*/
public static function templateOffsets($template, $adaptive)
{
$first = $adaptive[0] ?? [3, -1];
$second = $adaptive[1] ?? [-3, -1];
$third = $adaptive[2] ?? [2, -2];
$fourth = $adaptive[3] ?? [-2, -2];
if ($template == 0) {
return [$fourth, [-1, -2], [0, -2], [1, -2], $third,
$second, [-2, -1], [-1, -1], [0, -1], [1, -1], [2, -1],
$first, [-4, 0], [-3, 0], [-2, 0], [-1, 0]];
}
if ($template == 1) {
return [[-1, -2], [0, -2], [1, -2], [2, -2], [-2, -1],
[-1, -1], [0, -1], [1, -1], [2, -1], $first,
[-3, 0], [-2, 0], [-1, 0]];
}
if ($template == 2) {
return [[-1, -2], [0, -2], [1, -2], [-2, -1], [-1, -1],
[0, -1], [1, -1], $first, [-2, 0], [-1, 0]];
}
return [[-3, -1], [-2, -1], [-1, -1], [0, -1], [1, -1], $first,
[-4, 0], [-3, 0], [-2, 0], [-1, 0]];
}
/**
* Gives what is at a place among the rows decoded so far, taking
* anything outside the picture as blank.
*
* @param array $marks the rows decoded so far
* @param int $across which pixel along the row
* @param int $down which row
* @param int $wide how many pixels across a row is
* @return int what is there, 0 or 1
*/
public function pixelAt($marks, $across, $down, $wide)
{
if ($down < 0 || $across < 0 || $across >= $wide) {
return 0;
}
return $marks[$down][$across] ?? 0;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software