basis/compression/lzw/lzw-docs.factor

   1 ! Copyright (C) 2009 Keith Lazuka
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: bitstreams byte-arrays classes help.markup help.syntax
   4 kernel math quotations sequences ;
   5 IN: compression.lzw
   6
   7 HELP: gif-lzw-uncompress
   8 { $values
   9     { "seq" sequence } { "code-size" integer }
  10     { "byte-array" byte-array }
  11 }
  12 { $description "Decompresses a sequence of LZW-compressed bytes obtained from a GIF file." } ;
  13
  14 HELP: tiff-lzw-uncompress
  15 { $values
  16     { "seq" sequence }
  17     { "byte-array" byte-array }
  18 }
  19 { $description "Decompresses a sequence of LZW-compressed bytes obtained from a TIFF file." } ;
  20
  21 HELP: lzw-read
  22 { $values
  23     { "lzw" lzw } { "n" integer }
  24 }
  25 { $description "Read the next LZW code." } ;
  26
  27 HELP: lzw-process-next-code
  28 { $values
  29     { "lzw" lzw } { "quot" quotation }
  30 }
  31 { $description "Read the next LZW code and, assuming that the code is neither the Clear Code nor the End of Information Code, conditionally processes it by calling " { $snippet "quot" } " with the lzw object and the LZW code. If it does read a Clear Code, this combinator will take care of handling the Clear Code for you." } ;
  32
  33 HELP: <lzw-uncompress>
  34 { $values
  35     { "input" bit-reader } { "code-size" "number of bits" } { "class" class }
  36     { "obj" object }
  37 }
  38 { $description "Instantiate a new LZW decompressor." } ;
  39
  40 HELP: code-space-full?
  41 { $values
  42     { "lzw" lzw }
  43     { "?" boolean }
  44 }
  45 { $description "Determines when to increment the variable length code's bit-width." } ;
  46
  47 HELP: reset-lzw-uncompress
  48 { $values
  49     { "lzw" lzw }
  50 }
  51 { $description "Reset the LZW uncompressor state (either at initialization time or immediately after receiving a Clear Code)." } ;
  52
  53 ARTICLE: "compression.lzw.differences" "LZW differences between TIFF and GIF"
  54 { $vocab-link "compression.lzw" }
  55 $nl
  56 "There are some subtle differences between the LZW algorithm used by TIFF and GIF images."
  57 { $heading "Variable Length Codes" }
  58 "Both TIFF and GIF use a variation of the LZW algorithm that uses variable length codes. In both cases, the maximum code size is 12 bits. The initial code size, however, is different between the two formats. TIFF's initial code size is always 9 bits. GIF's initial code size is specified on a per-file basis at the beginning of the image descriptor block, with a minimum of 3 bits."
  59 $nl
  60 "TIFF and GIF each switch to the next code size using slightly different algorithms. GIF increments the code size as soon as the LZW string table's length is equal to 2**code-size, while TIFF increments the code size when the table's length is equal to 2**code-size - 1."
  61 { $heading "Packing Bits into Bytes" }
  62 "TIFF and GIF LZW algorithms differ in how they pack the code bits into the byte stream. The least significant bit in a TIFF code is stored in the most significant bit of the bytestream, while the least significant bit in a GIF code is stored in the least significant bit of the bytestream."
  63 { $heading "Special Codes" }
  64 "TIFF and GIF both add the concept of a 'Clear Code' and a 'End of Information Code' to the LZW algorithm. In both cases, the 'Clear Code' is equal to 2**(code-size - 1) and the 'End of Information Code' is equal to the Clear Code + 1. These 2 codes are reserved in the string table. So in both cases, the LZW string table is initialized to have a length equal to the End of Information Code + 1."
  65 ;
  66
  67 ARTICLE: "compression.lzw" "LZW compression"
  68 { $vocab-link "compression.lzw" }
  69 $nl
  70 "Implements both the TIFF and GIF variations of the LZW algorithm."
  71 { $heading "Decompression" }
  72 { $subsections
  73     tiff-lzw-uncompress
  74     gif-lzw-uncompress
  75 }
  76 { $heading "Compression" }
  77 "Compression has not yet been implemented."
  78 $nl
  79 "Implementation details:"
  80 { $subsections "compression.lzw.differences" }
  81 ;
  82
  83 ABOUT: "compression.lzw"