summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormid-kid <esteve.varela@gmail.com>2020-09-09 18:20:11 +0200
committermid-kid <esteve.varela@gmail.com>2020-09-09 18:20:11 +0200
commit0766385242deec8441dad782df297f884b885c36 (patch)
tree022ad9920db05829d8f3cfff71f05283ef249b7b
Initial commit, add mgbdis
Diffstat
-rw-r--r--mgbdis/.gitignore4
-rw-r--r--mgbdis/LICENSE21
-rw-r--r--mgbdis/README.md110
-rw-r--r--mgbdis/hardware.inc776
-rw-r--r--mgbdis/instruction_set.py602
-rwxr-xr-xmgbdis/mgbdis.py1184
-rw-r--r--mgbdis/png.py2638
7 files changed, 5335 insertions, 0 deletions
diff --git a/mgbdis/.gitignore b/mgbdis/.gitignore
new file mode 100644
index 0000000..2d20127
--- /dev/null
+++ b/mgbdis/.gitignore
@@ -0,0 +1,4 @@
+__pycache__/
+disassembly/
+test/
+tmp/ \ No newline at end of file
diff --git a/mgbdis/LICENSE b/mgbdis/LICENSE
new file mode 100644
index 0000000..13a7cca
--- /dev/null
+++ b/mgbdis/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Matt Currie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/mgbdis/README.md b/mgbdis/README.md
new file mode 100644
index 0000000..5c99f2f
--- /dev/null
+++ b/mgbdis/README.md
@@ -0,0 +1,110 @@
+# mgbdis
+
+A Game Boy ROM disassembler.
+
+
+## Features
+
+- Generates assembly code compatible with RGBDS (v0.3.8+ recommended, see [Notes](#notes))
+- Supports ROMs with multiple banks
+- Supports .sym files to define labels, code, data, text and image blocks
+- Outputs a makefile to rebuild the ROM
+- Uses defines from hardware.inc v2.7 for hardware registers ([source](https://github.com/tobiasvl/hardware.inc))
+- Slow on large ROMs
+
+
+## Usage
+
+Disassemble a ROM:
+
+ ./mgbdis.py some-game.gb
+
+Default output is to the ```disassembly``` directory. You can verify the result of the disassembly by running ```make``` and then checking the ```game.gb``` (or ```game.gbc```) file created:
+
+ cd disassembly && make
+
+There are also a number of options available to control the formatting and instruction style of the generated assembly code. You can view these by running:
+
+ ./mgbdis.py -h
+
+## Symbol Files
+
+Symbol files allow you to indicate where code, data, test and image data blocks are in the ROM.
+
+The instructions of the Game Boy CPU (SM83) have different lengths, and data can be interleaved with code in the ROM, so it is not possible to always accurately identify where an instruction starts and stops. Defining code blocks in a symbol file can help to avoid problems with mgbdis trying to disassemble in the middle of an instruction.
+
+If you do not have a symbol file, you can try generating one with my Game Boy emulator - [Beaten Dying Moon](https://mattcurrie.com/bdm-demo/). It can generate a symbol file with code block definitions based on the the addresses of the instructions that have actually been executed while you have been playing the game, avoiding instruction alignment issues.
+
+To use a symbol file with mgbdis, it should exist in the same directory as the ROM and have the same name, except change the extension to be ```.sym```.
+
+All values (except for image widths) should be in hexadecimal. Entries start with a bank number followed by the address in memory.
+
+Block types can be defined by using the ```.code```, ```.data```, ```.text```, and ```.image``` magic labels, followed by the length of the block in bytes.
+
+### Code
+
+Adding a label for some code:
+
+```
+03:47f2 Read_Joypad_State
+```
+
+### Data
+
+Adding a label for 512 bytes of data:
+
+```
+0d:4800 Level_Data
+0d:4800 .data:200
+```
+
+### Text
+
+Adding a label for 16 bytes of text:
+
+```
+00:3d00 Character_Name
+00:3d00 .text:10
+```
+
+### Image
+
+The ```.image``` magic label allows you to define blocks of 1 or 2 bits per pixel tile data in the ROM. Images are output as PNG files in the ```/gfx``` directory of the disassembly, and are converted back to 1bpp or 2bpp tile data by the makefile using rgbgfx. If a label is specified at the address of the image block then it will be used for the name of the PNG file.
+
+The block length in bytes should be a multiple of 16, as each tile requires 16 bytes of image data.
+
+The image width in pixels can be specified as a decimal number prefixed with ```w```. The width value should be a multiple of 8, and the combination of block length and image width must result in a rectangluar image without any empty tiles. The default image width is ```128``` pixels, or if the block length indicates an odd number of tiles, then an image with a single row of tiles will be generated.
+
+The palette is a byte sized value which selects the shades of grey to use when generating the image. It uses the same format as the BGP register at ```0xFF47```. The value can be specified in hexidecimal prefixed with ```p```. The default palette is ```E4```.
+
+The default is to treat it as 2 bits per pixel tile data. A ```1bpp``` option can be supplied to treat the data as 1 bit per pixel tile data.
+
+Adding a label for 1280 bytes of tile data, with a width of 128 pixels and palette 0xE4:
+
+```
+02:791a Title_Screen_Tile_Data
+02:791a .image:500:w128,pe4
+```
+
+Resulting image:
+
+![Imgur](https://i.imgur.com/2duQ7Py.png)
+
+
+Example for 1bpp tile data:
+
+```
+05:4000 Font
+05:4000 .image:200:w128,1bpp
+```
+
+Resulting image:
+
+![Imgur](https://i.imgur.com/iX5FCXL.png)
+
+## Notes
+
+- For constant expressions, RGBDS will by default optimise instructions like ```LD [$FF40],a``` to ```LDH [$FF00+40],a```, so these are encoded as data bytes using a macro to ensure exact reproduction of the original ROM (thanks to ISSOtm). RGBDS >= v0.3.7 has an option to disable this optimisation. Use ```--disable-auto-ldh``` with mgbdis to disable the macro.
+- RGBDS automatically adds ```NOP``` instructions after ```STOP``` and ```HALT```, so the disassembler will output these as data bytes if the instruction is not followed by a ```NOP``` in the original ROM. Use ```--disable-halt-nops``` with mgbdis to instruct RGBDS to disable inserting automatic ```NOP``` instructions after ```HALT``` instructions.
+- RGBDS v0.3.6 has an off by one error for some ```JR``` instructions, causing the assembled ROM to not match the original.
+- RGBDS v0.3.7 ```rgbfix``` generates an invalid global checksum in the ROM header, causing the assembled ROM to not match the original.
diff --git a/mgbdis/hardware.inc b/mgbdis/hardware.inc
new file mode 100644
index 0000000..102b764
--- /dev/null
+++ b/mgbdis/hardware.inc
@@ -0,0 +1,776 @@
+;*
+;* Gameboy Hardware definitions
+;*
+;* Based on Jones' hardware.inc
+;* And based on Carsten Sorensen's ideas.
+;*
+;* Rev 1.1 - 15-Jul-97 : Added define check
+;* Rev 1.2 - 18-Jul-97 : Added revision check macro
+;* Rev 1.3 - 19-Jul-97 : Modified for RGBASM V1.05
+;* Rev 1.4 - 27-Jul-97 : Modified for new subroutine prefixes
+;* Rev 1.5 - 15-Aug-97 : Added _HRAM, PAD, CART defines
+;* : and Nintendo Logo
+;* Rev 1.6 - 30-Nov-97 : Added rDIV, rTIMA, rTMA, & rTAC
+;* Rev 1.7 - 31-Jan-98 : Added _SCRN0, _SCRN1
+;* Rev 1.8 - 15-Feb-98 : Added rSB, rSC
+;* Rev 1.9 - 16-Feb-98 : Converted I/O registers to $FFXX format
+;* Rev 2.0 - : Added GBC registers
+;* Rev 2.1 - : Added MBC5 & cart RAM enable/disable defines
+;* Rev 2.2 - : Fixed NR42,NR43, & NR44 equates
+;* Rev 2.3 - : Fixed incorrect _HRAM equate
+;* Rev 2.4 - 27-Apr-13 : Added some cart defines (AntonioND)
+;* Rev 2.5 - 03-May-15 : Fixed format (AntonioND)
+;* Rev 2.6 - 09-Apr-16 : Added GBC OAM and cart defines (AntonioND)
+;* Rev 2.7 - 19-Jan-19 : Added rPCMXX (ISSOtm)
+
+; If all of these are already defined, don't do it again.
+
+ IF !DEF(HARDWARE_INC)
+HARDWARE_INC SET 1
+
+rev_Check_hardware_inc : MACRO
+;NOTE: REVISION NUMBER CHANGES MUST BE ADDED
+;TO SECOND PARAMETER IN FOLLOWING LINE.
+ IF \1 > 2.7 ;PUT REVISION NUMBER HERE
+ WARN "Version \1 or later of 'hardware.inc' is required."
+ ENDC
+ENDM
+
+_HW EQU $FF00
+
+_VRAM EQU $8000 ; $8000->$9FFF
+_SCRN0 EQU $9800 ; $9800->$9BFF
+_SCRN1 EQU $9C00 ; $9C00->$9FFF
+_SRAM EQU $A000 ; $A000->$BFFF
+_RAM EQU $C000 ; $C000->$DFFF
+_OAMRAM EQU $FE00 ; $FE00->$FE9F
+_AUD3WAVERAM EQU $FF30 ; $FF30->$FF3F
+_HRAM EQU $FF80 ; $FF80->$FFFE
+
+; *** MBC5 Equates ***
+
+rRAMG EQU $0000 ; $0000->$1fff
+rROMB0 EQU $2000 ; $2000->$2fff
+rROMB1 EQU $3000 ; $3000->$3fff - If more than 256 ROM banks are present.
+rRAMB EQU $4000 ; $4000->$5fff - Bit 3 enables rumble (if present)
+
+
+; --
+; -- OAM flags
+; --
+
+OAMF_PRI EQU %10000000 ; Priority
+OAMF_YFLIP EQU %01000000 ; Y flip
+OAMF_XFLIP EQU %00100000 ; X flip
+OAMF_PAL0 EQU %00000000 ; Palette number; 0,1 (DMG)
+OAMF_PAL1 EQU %00010000 ; Palette number; 0,1 (DMG)
+OAMF_BANK0 EQU %00000000 ; Bank number; 0,1 (GBC)
+OAMF_BANK1 EQU %00001000 ; Bank number; 0,1 (GBC)
+
+OAMF_PALMASK EQU %00000111 ; Palette (GBC)
+
+OAMB_PRI EQU 7 ; Priority
+OAMB_YFLIP EQU 6 ; Y flip
+OAMB_XFLIP EQU 5 ; X flip
+OAMB_PAL1 EQU 4 ; Palette number; 0,1 (DMG)
+OAMB_BANK1 EQU 3 ; Bank number; 0,1 (GBC)
+
+
+;***************************************************************************
+;*
+;* Custom registers
+;*
+;***************************************************************************
+
+; --
+; -- P1 ($FF00)
+; -- Register for reading joy pad info. (R/W)
+; --
+rP1 EQU $FF00
+
+P1F_5 EQU %00100000 ; P15 out port
+P1F_4 EQU %00010000 ; P14 out port
+P1F_3 EQU %00001000 ; P13 in port
+P1F_2 EQU %00000100 ; P12 in port
+P1F_1 EQU %00000010 ; P11 in port
+P1F_0 EQU %00000001 ; P10 in port
+
+; --
+; -- SB ($FF01)
+; -- Serial Transfer Data (R/W)
+; --
+rSB EQU $FF01
+
+; --
+; -- SC ($FF02)
+; -- Serial I/O Control (R/W)
+; --
+rSC EQU $FF02
+
+; --
+; -- DIV ($FF04)
+; -- Divider register (R/W)
+; --
+rDIV EQU $FF04
+
+
+; --
+; -- TIMA ($FF05)
+; -- Timer counter (R/W)
+; --
+rTIMA EQU $FF05
+
+
+; --
+; -- TMA ($FF06)
+; -- Timer modulo (R/W)
+; --
+rTMA EQU $FF06
+
+
+; --
+; -- TAC ($FF07)
+; -- Timer control (R/W)
+; --
+rTAC EQU $FF07
+
+TACF_START EQU %00000100
+TACF_STOP EQU %00000000
+TACF_4KHZ EQU %00000000
+TACF_16KHZ EQU %00000011
+TACF_65KHZ EQU %00000010
+TACF_262KHZ EQU %00000001
+
+; --
+; -- IF ($FF0F)
+; -- Interrupt Flag (R/W)
+; --
+rIF EQU $FF0F
+
+; --
+; -- LCDC ($FF40)
+; -- LCD Control (R/W)
+; --
+rLCDC EQU $FF40
+
+LCDCF_OFF EQU %00000000 ; LCD Control Operation
+LCDCF_ON EQU %10000000 ; LCD Control Operation
+LCDCF_WIN9800 EQU %00000000 ; Window Tile Map Display Select
+LCDCF_WIN9C00 EQU %01000000 ; Window Tile Map Display Select
+LCDCF_WINOFF EQU %00000000 ; Window Display
+LCDCF_WINON EQU %00100000 ; Window Display
+LCDCF_BG8800 EQU %00000000 ; BG & Window Tile Data Select
+LCDCF_BG8000 EQU %00010000 ; BG & Window Tile Data Select
+LCDCF_BG9800 EQU %00000000 ; BG Tile Map Display Select
+LCDCF_BG9C00 EQU %00001000 ; BG Tile Map Display Select
+LCDCF_OBJ8 EQU %00000000 ; OBJ Construction
+LCDCF_OBJ16 EQU %00000100 ; OBJ Construction
+LCDCF_OBJOFF EQU %00000000 ; OBJ Display
+LCDCF_OBJON EQU %00000010 ; OBJ Display
+LCDCF_BGOFF EQU %00000000 ; BG Display
+LCDCF_BGON EQU %00000001 ; BG Display
+; "Window Character Data Select" follows BG
+
+
+; --
+; -- STAT ($FF41)
+; -- LCDC Status (R/W)
+; --
+rSTAT EQU $FF41
+
+STATF_LYC EQU %01000000 ; LYCEQULY Coincidence (Selectable)
+STATF_MODE10 EQU %00100000 ; Mode 10
+STATF_MODE01 EQU %00010000 ; Mode 01 (V-Blank)
+STATF_MODE00 EQU %00001000 ; Mode 00 (H-Blank)
+STATF_LYCF EQU %00000100 ; Coincidence Flag
+STATF_HB EQU %00000000 ; H-Blank
+STATF_VB EQU %00000001 ; V-Blank
+STATF_OAM EQU %00000010 ; OAM-RAM is used by system
+STATF_LCD EQU %00000011 ; Both OAM and VRAM used by system
+STATF_BUSY EQU %00000010 ; When set, VRAM access is unsafe
+
+
+; --
+; -- SCY ($FF42)
+; -- Scroll Y (R/W)
+; --
+rSCY EQU $FF42
+
+
+; --
+; -- SCY ($FF43)
+; -- Scroll X (R/W)
+; --
+rSCX EQU $FF43
+
+
+; --
+; -- LY ($FF44)
+; -- LCDC Y-Coordinate (R)
+; --
+; -- Values range from 0->153. 144->153 is the VBlank period.
+; --
+rLY EQU $FF44
+
+
+; --
+; -- LYC ($FF45)
+; -- LY Compare (R/W)
+; --
+; -- When LYEQUEQULYC, STATF_LYCF will be set in STAT
+; --
+rLYC EQU $FF45
+
+
+; --
+; -- DMA ($FF46)
+; -- DMA Transfer and Start Address (W)
+; --
+rDMA EQU $FF46
+
+
+; --
+; -- BGP ($FF47)
+; -- BG Palette Data (W)
+; --
+; -- Bit 7-6 - Intensity for %11
+; -- Bit 5-4 - Intensity for %10
+; -- Bit 3-2 - Intensity for %01
+; -- Bit 1-0 - Intensity for %00
+; --
+rBGP EQU $FF47
+
+
+; --
+; -- OBP0 ($FF48)
+; -- Object Palette 0 Data (W)
+; --
+; -- See BGP for info
+; --
+rOBP0 EQU $FF48
+
+
+; --
+; -- OBP1 ($FF49)
+; -- Object Palette 1 Data (W)
+; --
+; -- See BGP for info
+; --
+rOBP1 EQU $FF49
+
+
+; --
+; -- WY ($FF4A)
+; -- Window Y Position (R/W)
+; --
+; -- 0 <EQU WY <EQU 143
+; --
+rWY EQU $FF4A
+
+
+; --
+; -- WX ($FF4B)
+; -- Window X Position (R/W)
+; --
+; -- 7 <EQU WX <EQU 166
+; --
+rWX EQU $FF4B
+
+
+; --
+; -- KEY 1 ($FF4D)
+; -- Select CPU Speed (R/W)
+; --
+rKEY1 EQU $FF4D
+
+
+; --
+; -- VBK ($FF4F)
+; -- Select Video RAM Bank (R/W)
+; --
+rVBK EQU $FF4F
+
+
+; --
+; -- HDMA1 ($FF51)
+; -- Horizontal Blanking, General Purpose DMA (W)
+; --
+rHDMA1 EQU $FF51
+
+
+; --
+; -- HDMA2 ($FF52)
+; -- Horizontal Blanking, General Purpose DMA (W)
+; --
+rHDMA2 EQU $FF52
+
+
+; --
+; -- HDMA3 ($FF53)
+; -- Horizontal Blanking, General Purpose DMA (W)
+; --
+rHDMA3 EQU $FF53
+
+
+; --
+; -- HDMA4 ($FF54)
+; -- Horizontal Blanking, General Purpose DMA (W)
+; --
+rHDMA4 EQU $FF54
+
+
+; --
+; -- HDMA5 ($FF55)
+; -- Horizontal Blanking, General Purpose DMA (R/W)
+; --
+rHDMA5 EQU $FF55
+
+
+; --
+; -- RP ($FF56)
+; -- Infrared Communications Port (R/W)
+; --
+rRP EQU $FF56
+
+
+; --
+; -- BCPS ($FF68)
+; -- Background Color Palette Specification (R/W)
+; --
+rBCPS EQU $FF68
+
+
+; --
+; -- BCPD ($FF69)
+; -- Background Color Palette Data (R/W)
+; --
+rBCPD EQU $FF69
+
+
+; --
+; -- BCPS ($FF6A)
+; -- Object Color Palette Specification (R/W)
+; --
+rOCPS EQU $FF6A
+
+
+; --
+; -- BCPD ($FF6B)
+; -- Object Color Palette Data (R/W)
+; --
+rOCPD EQU $FF6B
+
+
+; --
+; -- SVBK ($FF4F)
+; -- Select Main RAM Bank (R/W)
+; --
+rSVBK EQU $FF70
+
+
+; --
+; -- IE ($FFFF)
+; -- Interrupt Enable (R/W)
+; --
+rIE EQU $FFFF
+
+
+IEF_HILO EQU %00010000 ; Transition from High to Low of Pin number P10-P13
+IEF_SERIAL EQU %00001000 ; Serial I/O transfer end
+IEF_TIMER EQU %00000100 ; Timer Overflow
+IEF_LCDC EQU %00000010 ; LCDC (see STAT)
+IEF_VBLANK EQU %00000001 ; V-Blank
+
+
+
+
+;***************************************************************************
+;*
+;* Sound control registers
+;*
+;***************************************************************************
+
+; --
+; -- AUDVOL/NR50 ($FF24)
+; -- Channel control / ON-OFF / Volume (R/W)
+; --
+; -- Bit 7 - Vin->SO2 ON/OFF (Vin??)
+; -- Bit 6-4 - SO2 output level (volume) (# 0-7)
+; -- Bit 3 - Vin->SO1 ON/OFF (Vin??)
+; -- Bit 2-0 - SO1 output level (volume) (# 0-7)
+; --
+rNR50 EQU $FF24
+rAUDVOL EQU rNR50
+
+
+; --
+; -- AUDTERM/NR51 ($FF25)
+; -- Selection of Sound output terminal (R/W)
+; --
+; -- Bit 7 - Output sound 4 to SO2 terminal
+; -- Bit 6 - Output sound 3 to SO2 terminal
+; -- Bit 5 - Output sound 2 to SO2 terminal
+; -- Bit 4 - Output sound 1 to SO2 terminal
+; -- Bit 3 - Output sound 4 to SO1 terminal
+; -- Bit 2 - Output sound 3 to SO1 terminal
+; -- Bit 1 - Output sound 2 to SO1 terminal
+; -- Bit 0 - Output sound 0 to SO1 terminal
+; --
+rNR51 EQU $FF25
+rAUDTERM EQU rNR51
+
+
+; --
+; -- AUDENA/NR52 ($FF26)
+; -- Sound on/off (R/W)
+; --
+; -- Bit 7 - All sound on/off (sets all audio regs to 0!)
+; -- Bit 3 - Sound 4 ON flag (doesn't work!)
+; -- Bit 2 - Sound 3 ON flag (doesn't work!)
+; -- Bit 1 - Sound 2 ON flag (doesn't work!)
+; -- Bit 0 - Sound 1 ON flag (doesn't work!)
+; --
+rNR52 EQU $FF26
+rAUDENA EQU rNR52
+
+
+;***************************************************************************
+;*
+;* SoundChannel #1 registers
+;*
+;***************************************************************************
+
+; --
+; -- AUD1SWEEP/NR10 ($FF10)
+; -- Sweep register (R/W)
+; --
+; -- Bit 6-4 - Sweep Time
+; -- Bit 3 - Sweep Increase/Decrease
+; -- 0: Addition (frequency increases???)
+; -- 1: Subtraction (frequency increases???)
+; -- Bit 2-0 - Number of sweep shift (# 0-7)
+; -- Sweep Time: (n*7.8ms)
+; --
+rNR10 EQU $FF10
+rAUD1SWEEP EQU rNR10
+
+
+; --
+; -- AUD1LEN/NR11 ($FF11)
+; -- Sound length/Wave pattern duty (R/W)
+; --
+; -- Bit 7-6 - Wave Pattern Duty (00:12.5% 01:25% 10:50% 11:75%)
+; -- Bit 5-0 - Sound length data (# 0-63)
+; --
+rNR11 EQU $FF11
+rAUD1LEN EQU rNR11
+
+
+; --
+; -- AUD1ENV/NR12 ($FF12)
+; -- Envelope (R/W)
+; --
+; -- Bit 7-4 - Initial value of envelope
+; -- Bit 3 - Envelope UP/DOWN
+; -- 0: Decrease
+; -- 1: Range of increase
+; -- Bit 2-0 - Number of envelope sweep (# 0-7)
+; --
+rNR12 EQU $FF12
+rAUD1ENV EQU rNR12
+
+
+; --
+; -- AUD1LOW/NR13 ($FF13)
+; -- Frequency lo (W)
+; --
+rNR13 EQU $FF13
+rAUD1LOW EQU rNR13
+
+
+; --
+; -- AUD1HIGH/NR14 ($FF14)
+; -- Frequency hi (W)
+; --
+; -- Bit 7 - Initial (when set, sound restarts)
+; -- Bit 6 - Counter/consecutive selection
+; -- Bit 2-0 - Frequency's higher 3 bits
+; --
+rNR14 EQU $FF14
+rAUD1HIGH EQU rNR14
+
+
+;***************************************************************************
+;*
+;* SoundChannel #2 registers
+;*
+;***************************************************************************
+
+; --
+; -- AUD2LEN/NR21 ($FF16)
+; -- Sound Length; Wave Pattern Duty (R/W)
+; --
+; -- see AUD1LEN for info
+; --
+rNR21 EQU $FF16
+rAUD2LEN EQU rNR21
+
+
+; --
+; -- AUD2ENV/NR22 ($FF17)
+; -- Envelope (R/W)
+; --
+; -- see AUD1ENV for info
+; --
+rNR22 EQU $FF17
+rAUD2ENV EQU rNR22
+
+
+; --
+; -- AUD2LOW/NR23 ($FF18)
+; -- Frequency lo (W)
+; --
+rNR23 EQU $FF18
+rAUD2LOW EQU rNR23
+
+
+; --
+; -- AUD2HIGH/NR24 ($FF19)
+; -- Frequency hi (W)
+; --
+; -- see AUD1HIGH for info
+; --
+rNR24 EQU $FF19
+rAUD2HIGH EQU rNR24
+
+
+;***************************************************************************
+;*
+;* SoundChannel #3 registers
+;*
+;***************************************************************************
+
+; --
+; -- AUD3ENA/NR30 ($FF1A)
+; -- Sound on/off (R/W)
+; --
+; -- Bit 7 - Sound ON/OFF (1EQUON,0EQUOFF)
+; --
+rNR30 EQU $FF1A
+rAUD3ENA EQU rNR30
+
+
+; --
+; -- AUD3LEN/NR31 ($FF1B)
+; -- Sound length (R/W)
+; --
+; -- Bit 7-0 - Sound length
+; --
+rNR31 EQU $FF1B
+rAUD3LEN EQU rNR31
+
+
+; --
+; -- AUD3LEVEL/NR32 ($FF1C)
+; -- Select output level
+; --
+; -- Bit 6-5 - Select output level
+; -- 00: 0/1 (mute)
+; -- 01: 1/1
+; -- 10: 1/2
+; -- 11: 1/4
+; --
+rNR32 EQU $FF1C
+rAUD3LEVEL EQU rNR32
+
+
+; --
+; -- AUD3LOW/NR33 ($FF1D)
+; -- Frequency lo (W)
+; --
+; -- see AUD1LOW for info
+; --
+rNR33 EQU $FF1D
+rAUD3LOW EQU rNR33
+
+
+; --
+; -- AUD3HIGH/NR34 ($FF1E)
+; -- Frequency hi (W)
+; --
+; -- see AUD1HIGH for info
+; --
+rNR34 EQU $FF1E
+rAUD3HIGH EQU rNR34
+
+
+; --
+; -- AUD4LEN/NR41 ($FF20)
+; -- Sound length (R/W)
+; --
+; -- Bit 5-0 - Sound length data (# 0-63)
+; --
+rNR41 EQU $FF20
+rAUD4LEN EQU rNR41
+
+
+; --
+; -- AUD4ENV/NR42 ($FF21)
+; -- Envelope (R/W)
+; --
+; -- see AUD1ENV for info
+; --
+rNR42 EQU $FF21
+rAUD4ENV EQU rNR42
+
+
+; --
+; -- AUD4POLY/NR43 ($FF22)
+; -- Polynomial counter (R/W)
+; --
+; -- Bit 7-4 - Selection of the shift clock frequency of the (scf)
+; -- polynomial counter (0000-1101)
+; -- freqEQUdrf*1/2^scf (not sure)
+; -- Bit 3 - Selection of the polynomial counter's step
+; -- 0: 15 steps
+; -- 1: 7 steps
+; -- Bit 2-0 - Selection of the dividing ratio of frequencies (drf)
+; -- 000: f/4 001: f/8 010: f/16 011: f/24
+; -- 100: f/32 101: f/40 110: f/48 111: f/56 (fEQU4.194304 Mhz)
+; --
+rNR43 EQU $FF22
+rAUD4POLY EQU rNR43
+
+
+; --
+; -- AUD4GO/NR44 ($FF23)
+; -- (has wrong name and value (ff30) in Dr.Pan's doc!)
+; --
+; -- Bit 7 - Inital
+; -- Bit 6 - Counter/consecutive selection
+; --
+rNR44 EQU $FF23
+rAUD4GO EQU rNR44 ; silly name!
+
+
+; --
+; -- PCM12 ($FF76)
+; -- Sound channel 1&2 PCM amplitude (R)
+; --
+; -- Bit 7-4 - Copy of sound channel 2's PCM amplitude
+; -- Bit 3-0 - Copy of sound channel 1's PCM amplitude
+; --
+rPCM12 EQU $FF76
+
+
+; --
+; -- PCM34 ($FF77)
+; -- Sound channel 3&4 PCM amplitude (R)
+; --
+; -- Bit 7-4 - Copy of sound channel 4's PCM amplitude
+; -- Bit 3-0 - Copy of sound channel 3's PCM amplitude
+; --
+rPCM34 EQU $FF77
+
+;***************************************************************************
+;*
+;* Cart related
+;*
+;***************************************************************************
+
+CART_COMPATIBLE_DMG EQU $00
+CART_COMPATIBLE_DMG_GBC EQU $80
+CART_COMPATIBLE_GBC EQU $C0
+
+CART_ROM EQU $00
+CART_ROM_MBC1 EQU $01
+CART_ROM_MBC1_RAM EQU $02
+CART_ROM_MBC1_RAM_BAT EQU $03
+CART_ROM_MBC2 EQU $05
+CART_ROM_MBC2_BAT EQU $06
+CART_ROM_RAM EQU $08
+CART_ROM_RAM_BAT EQU $09
+CART_ROM_MBC3_BAT_RTC EQU $0F
+CART_ROM_MBC3_RAM_BAT_RTC EQU $10
+CART_ROM_MBC3 EQU $11
+CART_ROM_MBC3_RAM EQU $12
+CART_ROM_MBC3_RAM_BAT EQU $13
+CART_ROM_MBC5 EQU $19
+CART_ROM_MBC5_BAT EQU $1A
+CART_ROM_MBC5_RAM_BAT EQU $1B
+CART_ROM_MBC5_RUMBLE EQU $1C
+CART_ROM_MBC5_RAM_RUMBLE EQU $1D
+CART_ROM_MBC5_RAM_BAT_RUMBLE EQU $1E
+CART_ROM_MBC7_RAM_BAT_GYRO EQU $22
+CART_ROM_POCKET_CAMERA EQU $FC
+
+CART_ROM_256K EQU 0 ; 2 banks
+CART_ROM_512K EQU 1 ; 4 banks
+CART_ROM_1M EQU 2 ; 8 banks
+CART_ROM_2M EQU 3 ; 16 banks
+CART_ROM_4M EQU 4 ; 32 banks
+CART_ROM_8M EQU 5 ; 64 banks
+CART_ROM_16M EQU 6 ; 128 banks
+CART_ROM_32M EQU 7 ; 256 banks
+CART_ROM_64M EQU 8 ; 512 banks
+
+CART_RAM_NONE EQU 0
+CART_RAM_16K EQU 1 ; 1 incomplete bank
+CART_RAM_64K EQU 2 ; 1 bank
+CART_RAM_256K EQU 3 ; 4 banks
+CART_RAM_1M EQU 4 ; 16 banks
+
+CART_RAM_ENABLE EQU $0A
+CART_RAM_DISABLE EQU $00
+
+;***************************************************************************
+;*
+;* Keypad related
+;*
+;***************************************************************************
+
+PADF_DOWN EQU $80
+PADF_UP EQU $40
+PADF_LEFT EQU $20
+PADF_RIGHT EQU $10
+PADF_START EQU $08
+PADF_SELECT EQU $04
+PADF_B EQU $02
+PADF_A EQU $01
+
+PADB_DOWN EQU $7
+PADB_UP EQU $6
+PADB_LEFT EQU $5
+PADB_RIGHT EQU $4
+PADB_START EQU $3
+PADB_SELECT EQU $2
+PADB_B EQU $1
+PADB_A EQU $0
+
+;***************************************************************************
+;*
+;* Screen related
+;*
+;***************************************************************************
+
+SCRN_X EQU 160 ; Width of screen in pixels
+SCRN_Y EQU 144 ; Height of screen in pixels
+SCRN_X_B EQU 20 ; Width of screen in bytes
+SCRN_Y_B EQU 18 ; Height of screen in bytes
+
+SCRN_VX EQU 256 ; Virtual width of screen in pixels
+SCRN_VY EQU 256 ; Virtual height of screen in pixels
+SCRN_VX_B EQU 32 ; Virtual width of screen in bytes
+SCRN_VY_B EQU 32 ; Virtual height of screen in bytes
+
+;*
+;* Nintendo scrolling logo
+;* (Code won't work on a real GameBoy)
+;* (if next lines are altered.)
+NINTENDO_LOGO : MACRO
+ DB $CE,$ED,$66,$66,$CC,$0D,$00,$0B,$03,$73,$00,$83,$00,$0C,$00,$0D
+ DB $00,$08,$11,$1F,$88,$89,$00,$0E,$DC,$CC,$6E,$E6,$DD,$DD,$D9,$99
+ DB $BB,$BB,$67,$63,$6E,$0E,$EC,$CC,$DD,$DC,$99,$9F,$BB,$B9,$33,$3E
+ENDM
+
+ ENDC ;HARDWARE_INC \ No newline at end of file
diff --git a/mgbdis/instruction_set.py b/mgbdis/instruction_set.py
new file mode 100644
index 0000000..0368b62
--- /dev/null
+++ b/mgbdis/instruction_set.py
@@ -0,0 +1,602 @@
+instructions = {
+
+ 0x00: 'nop',
+ 0x01: 'ld bc,d16',
+ 0x02: 'ld [bc],a',
+ 0x03: 'inc bc',
+ 0x04: 'inc b',
+ 0x05: 'dec b',
+ 0x06: 'ld b,d8',
+ 0x07: 'rlca',
+ 0x08: 'ld [a16],sp',
+ 0x09: 'add hl,bc',
+ 0x0a: 'ld a,[bc]',
+ 0x0b: 'dec bc',
+ 0x0c: 'inc c',
+ 0x0d: 'dec c',
+ 0x0e: 'ld c,d8',
+ 0x0f: 'rrca',
+
+ 0x10: 'stop',
+ 0x11: 'ld de,d16',
+ 0x12: 'ld [de],a',
+ 0x13: 'inc de',
+ 0x14: 'inc d',
+ 0x15: 'dec d',
+ 0x16: 'ld d,d8',
+ 0x17: 'rla',
+ 0x18: 'jr pc+r8',
+ 0x19: 'add hl,de',
+ 0x1a: 'ld a,[de]',
+ 0x1b: 'dec de',
+ 0x1c: 'inc e',
+ 0x1d: 'dec e',
+ 0x1e: 'ld e,d8',
+ 0x1f: 'rra',
+
+ 0x20: 'jr nz,pc+r8',
+ 0x21: 'ld hl,d16',
+ 0x22: 'ld [hl+],a',
+ 0x23: 'inc hl',
+ 0x24: 'inc h',
+ 0x25: 'dec h',
+ 0x26: 'ld h,d8',
+ 0x27: 'daa',
+ 0x28: 'jr z,pc+r8',
+ 0x29: 'add hl,hl',
+ 0x2a: 'ld a,[hl+]',
+ 0x2b: 'dec hl',
+ 0x2c: 'inc l',
+ 0x2d: 'dec l',
+ 0x2e: 'ld l,d8',
+ 0x2f: 'cpl',
+
+ 0x30: 'jr nc,pc+r8',
+ 0x31: 'ld sp,d16',
+ 0x32: 'ld [hl-],a',
+ 0x33: 'inc sp',
+ 0x34: 'inc [hl]',
+ 0x35: 'dec [hl]',
+ 0x36: 'ld [hl],d8',
+ 0x37: 'scf',
+ 0x38: 'jr c,pc+r8',
+ 0x39: 'add hl,sp',
+ 0x3a: 'ld a,[hl-]',
+ 0x3b: 'dec sp',
+ 0x3c: 'inc a',
+ 0x3d: 'dec a',
+ 0x3e: 'ld a,d8',
+ 0x3f: 'ccf',
+
+ 0x40: 'ld b,b',
+ 0x41: 'ld b,c',
+ 0x42: 'ld b,d',
+ 0x43: 'ld b,e',
+ 0x44: 'ld b,h',
+ 0x45: 'ld b,l',
+ 0x46: 'ld b,[hl]',
+ 0x47: 'ld b,a',
+ 0x48: 'ld c,b',
+ 0x49: 'ld c,c',
+ 0x4a: 'ld c,d',
+ 0x4b: 'ld c,e',
+ 0x4c: 'ld c,h',
+ 0x4d: 'ld c,l',
+ 0x4e: 'ld c,[hl]',
+ 0x4f: 'ld c,a',
+
+ 0x50: 'ld d,b',
+ 0x51: 'ld d,c',
+ 0x52: 'ld d,d',
+ 0x53: 'ld d,e',
+ 0x54: 'ld d,h',
+ 0x55: 'ld d,l',
+ 0x56: 'ld d,[hl]',
+ 0x57: 'ld d,a',
+ 0x58: 'ld e,b',
+ 0x59: 'ld e,c',
+ 0x5a: 'ld e,d',
+ 0x5b: 'ld e,e',
+ 0x5c: 'ld e,h',
+ 0x5d: 'ld e,l',
+ 0x5e: 'ld e,[hl]',
+ 0x5f: 'ld e,a',
+
+ 0x60: 'ld h,b',
+ 0x61: 'ld h,c',
+ 0x62: 'ld h,d',
+ 0x63: 'ld h,e',
+ 0x64: 'ld h,h',
+ 0x65: 'ld h,l',
+ 0x66: 'ld h,[hl]',
+ 0x67: 'ld h,a',
+ 0x68: 'ld l,b',
+ 0x69: 'ld l,c',
+ 0x6a: 'ld l,d',
+ 0x6b: 'ld l,e',
+ 0x6c: 'ld l,h',
+ 0x6d: 'ld l,l',
+ 0x6e: 'ld l,[hl]',
+ 0x6f: 'ld l,a',
+
+ 0x70: 'ld [hl],b',
+ 0x71: 'ld [hl],c',
+ 0x72: 'ld [hl],d',
+ 0x73: 'ld [hl],e',
+ 0x74: 'ld [hl],h',
+ 0x75: 'ld [hl],l',
+ 0x76: 'halt',
+ 0x77: 'ld [hl],a',
+ 0x78: 'ld a,b',
+ 0x79: 'ld a,c',
+ 0x7a: 'ld a,d',
+ 0x7b: 'ld a,e',
+ 0x7c: 'ld a,h',
+ 0x7d: 'ld a,l',
+ 0x7e: 'ld a,[hl]',
+ 0x7f: 'ld a,a',
+
+ 0x80: 'add b',
+ 0x81: 'add c',
+ 0x82: 'add d',
+ 0x83: 'add e',
+ 0x84: 'add h',
+ 0x85: 'add l',
+ 0x86: 'add [hl]',
+ 0x87: 'add a',
+ 0x88: 'adc b',
+ 0x89: 'adc c',
+ 0x8a: 'adc d',
+ 0x8b: 'adc e',
+ 0x8c: 'adc h',
+ 0x8d: 'adc l',
+ 0x8e: 'adc [hl]',
+ 0x8f: 'adc a',
+
+ 0x90: 'sub b',
+ 0x91: 'sub c',
+ 0x92: 'sub d',
+ 0x93: 'sub e',
+ 0x94: 'sub h',
+ 0x95: 'sub l',
+ 0x96: 'sub [hl]',
+ 0x97: 'sub a',
+ 0x98: 'sbc b',
+ 0x99: 'sbc c',
+ 0x9a: 'sbc d',
+ 0x9b: 'sbc e',
+ 0x9c: 'sbc h',
+ 0x9d: 'sbc l',
+ 0x9e: 'sbc [hl]',
+ 0x9f: 'sbc a',
+
+ 0xa0: 'and b',
+ 0xa1: 'and c',
+ 0xa2: 'and d',
+ 0xa3: 'and e',
+ 0xa4: 'and h',
+ 0xa5: 'and l',
+ 0xa6: 'and [hl]',
+ 0xa7: 'and a',
+ 0xa8: 'xor b',
+ 0xa9: 'xor c',
+ 0xaa: 'xor d',
+ 0xab: 'xor e',
+ 0xac: 'xor h',
+ 0xad: 'xor l',
+ 0xae: 'xor [hl]',
+ 0xaf: 'xor a',
+
+ 0xb0: 'or b',
+ 0xb1: 'or c',
+ 0xb2: 'or d',
+ 0xb3: 'or e',
+ 0xb4: 'or h',
+ 0xb5: 'or l',
+ 0xb6: 'or [hl]',
+ 0xb7: 'or a',
+ 0xb8: 'cp b',
+ 0xb9: 'cp c',
+ 0xba: 'cp d',
+ 0xbb: 'cp e',
+ 0xbc: 'cp h',
+ 0xbd: 'cp l',
+ 0xbe: 'cp [hl]',
+ 0xbf: 'cp a',
+
+ 0xc0: 'ret nz',
+ 0xc1: 'pop bc',
+ 0xc2: 'jp nz,a16',
+ 0xc3: 'jp a16',
+ 0xc4: 'call nz,a16',
+ 0xc5: 'push bc',
+ 0xc6: 'add d8',
+ 0xc7: 'rst $00',
+ 0xc8: 'ret z',
+ 0xc9: 'ret',
+ 0xca: 'jp z,a16',
+ 0xcb: 'CBPREFIX',
+ 0xcc: 'call z,a16',
+ 0xcd: 'call a16',
+ 0xce: 'adc d8',
+ 0xcf: 'rst $08',
+
+ 0xd0: 'ret nc',
+ 0xd1: 'pop de',
+ 0xd2: 'jp nc,a16',
+ 0xd3: 'db $d3',
+ 0xd4: 'call nc,a16',
+ 0xd5: 'push de',
+ 0xd6: 'sub d8',
+ 0xd7: 'rst $10',
+ 0xd8: 'ret c',
+ 0xd9: 'reti',
+ 0xda: 'jp c,a16',
+ 0xdb: 'db $db',
+ 0xdc: 'call c,a16',
+ 0xdd: 'db $dd',
+ 0xde: 'sbc d8',
+ 0xdf: 'rst $18',
+
+ 0xe0: 'ldh [a8],a',
+ 0xe1: 'pop hl',
+ 0xe2: 'ld [c],a',
+ 0xe3: 'db $e3',
+ 0xe4: 'db $e4',
+ 0xe5: 'push hl',
+ 0xe6: 'and d8',
+ 0xe7: 'rst $20',
+ 0xe8: 'add sp,r8',
+ 0xe9: 'jp hl',
+ 0xea: 'ld [a16],a',
+ 0xeb: 'db $eb',
+ 0xec: 'db $ec',
+ 0xed: 'db $ed',
+ 0xee: 'xor d8',
+ 0xef: 'rst $28',
+
+ 0xf0: 'ldh a,[a8]',
+ 0xf1: 'pop af',
+ 0xf2: 'ld a,[c]',
+ 0xf3: 'di',
+ 0xf4: 'db $f4',
+ 0xf5: 'push af',
+ 0xf6: 'or d8',
+ 0xf7: 'rst $30',
+ 0xf8: 'ld hl,sp+r8',
+ 0xf9: 'ld sp,hl',
+ 0xfa: 'ld a,[a16]',
+ 0xfb: 'ei',
+ 0xfc: 'db $fc',
+ 0xfd: 'db $fd',
+ 0xfe: 'cp d8',
+ 0xff: 'rst $38',
+
+}
+
+cb_instructions = {
+
+ 0x00: 'rlc b',
+ 0x01: 'rlc c',
+ 0x02: 'rlc d',
+ 0x03: 'rlc e',
+ 0x04: 'rlc h',
+ 0x05: 'rlc l',
+ 0x06: 'rlc [hl]',
+ 0x07: 'rlc a',
+ 0x08: 'rrc b',
+ 0x09: 'rrc c',
+ 0x0a: 'rrc d',
+ 0x0b: 'rrc e',
+ 0x0c: 'rrc h',
+ 0x0d: 'rrc l',
+ 0x0e: 'rrc [hl]',
+ 0x0f: 'rrc a',
+
+ 0x10: 'rl b',
+ 0x11: 'rl c',
+ 0x12: 'rl d',
+ 0x13: 'rl e',
+ 0x14: 'rl h',
+ 0x15: 'rl l',
+ 0x16: 'rl [hl]',
+ 0x17: 'rl a',
+ 0x18: 'rr b',
+ 0x19: 'rr c',
+ 0x1a: 'rr d',
+ 0x1b: 'rr e',
+ 0x1c: 'rr h',
+ 0x1d: 'rr l',
+ 0x1e: 'rr [hl]',
+ 0x1f: 'rr a',
+
+ 0x20: 'sla b',
+ 0x21: 'sla c',
+ 0x22: 'sla d',
+ 0x23: 'sla e',
+ 0x24: 'sla h',
+ 0x25: 'sla l',
+ 0x26: 'sla [hl]',
+ 0x27: 'sla a',
+ 0x28: 'sra b',
+ 0x29: 'sra c',
+ 0x2a: 'sra d',
+ 0x2b: 'sra e',
+ 0x2c: 'sra h',
+ 0x2d: 'sra l',
+ 0x2e: 'sra [hl]',
+ 0x2f: 'sra a',
+
+ 0x30: 'swap b',
+ 0x31: 'swap c',
+ 0x32: 'swap d',
+ 0x33: 'swap e',
+ 0x34: 'swap h',
+ 0x35: 'swap l',
+ 0x36: 'swap [hl]',
+ 0x37: 'swap a',
+ 0x38: 'srl b',
+ 0x39: 'srl c',
+ 0x3a: 'srl d',
+ 0x3b: 'srl e',
+ 0x3c: 'srl h',
+ 0x3d: 'srl l',
+ 0x3e: 'srl [hl]',
+ 0x3f: 'srl a',
+
+ 0x40: 'bit 0,b',
+ 0x41: 'bit 0,c',
+ 0x42: 'bit 0,d',
+ 0x43: 'bit 0,e',
+ 0x44: 'bit 0,h',
+ 0x45: 'bit 0,l',
+ 0x46: 'bit 0,[hl]',
+ 0x47: 'bit 0,a',
+ 0x48: 'bit 1,b',
+ 0x49: 'bit 1,c',
+ 0x4a: 'bit 1,d',
+ 0x4b: 'bit 1,e',
+ 0x4c: 'bit 1,h',
+ 0x4d: 'bit 1,l',
+ 0x4e: 'bit 1,[hl]',
+ 0x4f: 'bit 1,a',
+
+ 0x50: 'bit 2,b',
+ 0x51: 'bit 2,c',
+ 0x52: 'bit 2,d',
+ 0x53: 'bit 2,e',
+ 0x54: 'bit 2,h',
+ 0x55: 'bit 2,l',
+ 0x56: 'bit 2,[hl]',
+ 0x57: 'bit 2,a',
+ 0x58: 'bit 3,b',
+ 0x59: 'bit 3,c',
+ 0x5a: 'bit 3,d',
+ 0x5b: 'bit 3,e',
+ 0x5c: 'bit 3,h',
+ 0x5d: 'bit 3,l',
+ 0x5e: 'bit 3,[hl]',
+ 0x5f: 'bit 3,a',
+
+ 0x60: 'bit 4,b',
+ 0x61: 'bit 4,c',
+ 0x62: 'bit 4,d',
+ 0x63: 'bit 4,e',
+ 0x64: 'bit 4,h',
+ 0x65: 'bit 4,l',
+ 0x66: 'bit 4,[hl]',
+ 0x67: 'bit 4,a',
+ 0x68: 'bit 5,b',
+ 0x69: 'bit 5,c',
+ 0x6a: 'bit 5,d',
+ 0x6b: 'bit 5,e',
+ 0x6c: 'bit 5,h',
+ 0x6d: 'bit 5,l',
+ 0x6e: 'bit 5,[hl]',
+ 0x6f: 'bit 5,a',
+
+ 0x70: 'bit 6,b',
+ 0x71: 'bit 6,c',
+ 0x72: 'bit 6,d',
+ 0x73: 'bit 6,e',
+ 0x74: 'bit 6,h',
+ 0x75: 'bit 6,l',
+ 0x76: 'bit 6,[hl]',
+ 0x77: 'bit 6,a',
+ 0x78: 'bit 7,b',
+ 0x79: 'bit 7,c',
+ 0x7a: 'bit 7,d',
+ 0x7b: 'bit 7,e',
+ 0x7c: 'bit 7,h',
+ 0x7d: 'bit 7,l',
+ 0x7e: 'bit 7,[hl]',
+ 0x7f: 'bit 7,a',
+
+ 0x80: 'res 0,b',
+ 0x81: 'res 0,c',
+ 0x82: 'res 0,d',
+ 0x83: 'res 0,e',
+ 0x84: 'res 0,h',
+ 0x85: 'res 0,l',
+ 0x86: 'res 0,[hl]',
+ 0x87: 'res 0,a',
+ 0x88: 'res 1,b',
+ 0x89: 'res 1,c',
+ 0x8a: 'res 1,d',
+ 0x8b: 'res 1,e',
+ 0x8c: 'res 1,h',
+ 0x8d: 'res 1,l',
+ 0x8e: 'res 1,[hl]',
+ 0x8f: 'res 1,a',
+
+ 0x90: 'res 2,b',
+ 0x91: 'res 2,c',
+ 0x92: 'res 2,d',
+ 0x93: 'res 2,e',
+ 0x94: 'res 2,h',
+ 0x95: 'res 2,l',
+ 0x96: 'res 2,[hl]',
+ 0x97: 'res 2,a',
+ 0x98: 'res 3,b',
+ 0x99: 'res 3,c',
+ 0x9a: 'res 3,d',
+ 0x9b: 'res 3,e',
+ 0x9c: 'res 3,h',
+ 0x9d: 'res 3,l',
+ 0x9e: 'res 3,[hl]',
+ 0x9f: 'res 3,a',
+
+ 0xa0: 'res 4,b',
+ 0xa1: 'res 4,c',
+ 0xa2: 'res 4,d',
+ 0xa3: 'res 4,e',
+ 0xa4: 'res 4,h',
+ 0xa5: 'res 4,l',
+ 0xa6: 'res 4,[hl]',
+ 0xa7: 'res 4,a',
+ 0xa8: 'res 5,b',
+ 0xa9: 'res 5,c',
+ 0xaa: 'res 5,d',
+ 0xab: 'res 5,e',
+ 0xac: 'res 5,h',
+ 0xad: 'res 5,l',
+ 0xae: 'res 5,[hl]',
+ 0xaf: 'res 5,a',
+
+ 0xb0: 'res 6,b',
+ 0xb1: 'res 6,c',
+ 0xb2: 'res 6,d',
+ 0xb3: 'res 6,e',
+ 0xb4: 'res 6,h',
+ 0xb5: 'res 6,l',
+ 0xb6: 'res 6,[hl]',
+ 0xb7: 'res 6,a',
+ 0xb8: 'res 7,b',
+ 0xb9: 'res 7,c',
+ 0xba: 'res 7,d',
+ 0xbb: 'res 7,e',
+ 0xbc: 'res 7,h',
+ 0xbd: 'res 7,l',
+ 0xbe: 'res 7,[hl]',
+ 0xbf: 'res 7,a',
+
+
+ 0xc0: 'set 0,b',
+ 0xc1: 'set 0,c',
+ 0xc2: 'set 0,d',
+ 0xc3: 'set 0,e',
+ 0xc4: 'set 0,h',
+ 0xc5: 'set 0,l',
+ 0xc6: 'set 0,[hl]',
+ 0xc7: 'set 0,a',
+ 0xc8: 'set 1,b',
+ 0xc9: 'set 1,c',
+ 0xca: 'set 1,d',
+ 0xcb: 'set 1,e',
+ 0xcc: 'set 1,h',
+ 0xcd: 'set 1,l',
+ 0xce: 'set 1,[hl]',
+ 0xcf: 'set 1,a',
+
+ 0xd0: 'set 2,b',
+ 0xd1: 'set 2,c',
+ 0xd2: 'set 2,d',
+ 0xd3: 'set 2,e',
+ 0xd4: 'set 2,h',
+ 0xd5: 'set 2,l',
+ 0xd6: 'set 2,[hl]',
+ 0xd7: 'set 2,a',
+ 0xd8: 'set 3,b',
+ 0xd9: 'set 3,c',
+ 0xda: 'set 3,d',
+ 0xdb: 'set 3,e',
+ 0xdc: 'set 3,h',
+ 0xdd: 'set 3,l',
+ 0xde: 'set 3,[hl]',
+ 0xdf: 'set 3,a',
+
+ 0xe0: 'set 4,b',
+ 0xe1: 'set 4,c',
+ 0xe2: 'set 4,d',
+ 0xe3: 'set 4,e',
+ 0xe4: 'set 4,h',
+ 0xe5: 'set 4,l',
+ 0xe6: 'set 4,[hl]',
+ 0xe7: 'set 4,a',
+ 0xe8: 'set 5,b',
+ 0xe9: 'set 5,c',
+ 0xea: 'set 5,d',
+ 0xeb: 'set 5,e',
+ 0xec: 'set 5,h',
+ 0xed: 'set 5,l',
+ 0xee: 'set 5,[hl]',
+ 0xef: 'set 5,a',
+
+ 0xf0: 'set 6,b',
+ 0xf1: 'set 6,c',
+ 0xf2: 'set 6,d',
+ 0xf3: 'set 6,e',
+ 0xf4: 'set 6,h',
+ 0xf5: 'set 6,l',
+ 0xf6: 'set 6,[hl]',
+ 0xf7: 'set 6,a',
+ 0xf8: 'set 7,b',
+ 0xf9: 'set 7,c',
+ 0xfa: 'set 7,d',
+ 0xfb: 'set 7,e',
+ 0xfc: 'set 7,h',
+ 0xfd: 'set 7,l',
+ 0xfe: 'set 7,[hl]',
+ 0xff: 'set 7,a'
+}
+
+instruction_variants = {
+ 'hli': {
+ 'hl+': {
+ 0x22: 'ld [hl+],a',
+ 0x2a: 'ld a,[hl+]',
+ 0x32: 'ld [hl-],a',
+ 0x3a: 'ld a,[hl-]'
+ },
+ 'hli': {
+ 0x22: 'ld [hli],a',
+ 0x2a: 'ld a,[hli]',
+ 0x32: 'ld [hld],a',
+ 0x3a: 'ld a,[hld]'
+ },
+ 'ldi': {
+ 0x22: 'ldi [hl],a',
+ 0x2a: 'ldi a,[hl]',
+ 0x32: 'ldd [hl],a',
+ 0x3a: 'ldd a,[hl]'
+ }
+ },
+ 'ldh_a8': {
+ 'ldh_a8': {
+ 0xe0: 'ldh [a8],a',
+ 0xf0: 'ldh a,[a8]'
+ },
+ 'ldh_ffa8': {
+ 0xe0: 'ldh [$ffa8],a',
+ 0xf0: 'ldh a,[$ffa8]'
+ },
+ 'ld_ff00_a8': {
+ 0xe0: 'ld [$ff00+a8],a',
+ 0xf0: 'ld a,[$ff00+a8]'
+ }
+ },
+ 'ld_c': {
+ 'ld_c': {
+ 0xe2: 'ld [c],a',
+ 0xf2: 'ld a,[c]'
+ },
+ 'ldh_c': {
+ 0xe2: 'ldh [c],a',
+ 0xf2: 'ldh a,[c]'
+ },
+ 'ld_ff00_c': {
+ 0xe2: 'ld [$ff00+c],a',
+ 0xf2: 'ld a,[$ff00+c]'
+ }
+ }
+}
diff --git a/mgbdis/mgbdis.py b/mgbdis/mgbdis.py
new file mode 100755
index 0000000..529126e
--- /dev/null
+++ b/mgbdis/mgbdis.py
@@ -0,0 +1,1184 @@
+#!/usr/bin/env python3
+
+"""Disassemble a Game Boy ROM into RGBDS compatible assembly code"""
+
+__author__ = 'Matt Currie and contributors'
+__credits__ = ['mattcurrie', 'kemenaran', 'bnzis']
+__version__ = '1.4'
+__copyright__ = 'Copyright 2018 by Matt Currie'
+__license__ = 'MIT'
+
+import argparse
+import glob
+import hashlib
+import os
+import png
+from shutil import copyfile
+
+from instruction_set import instructions, cb_instructions, instruction_variants
+
+default_symbols = [
+ '00:0000 RST_00',
+ '00:0000 .code:8',
+ '00:0008 RST_08',
+ '00:0008 .code:8',
+ '00:0010 RST_10',
+ '00:0010 .code:8',
+ '00:0018 RST_18',
+ '00:0018 .code:8',
+ '00:0020 RST_20',
+ '00:0020 .code:8',
+ '00:0028 RST_28',
+ '00:0028 .code:8',
+ '00:0030 RST_30',
+ '00:0030 .code:8',
+ '00:0038 RST_38',
+ '00:0038 .code:8',
+
+ '00:0040 VBlankInterrupt',
+ '00:0040 .code:8',
+ '00:0048 LCDCInterrupt',
+ '00:0048 .code:8',
+ '00:0050 TimerOverflowInterrupt',
+ '00:0050 .code:8',
+ '00:0058 SerialTransferCompleteInterrupt',
+ '00:0058 .code:8',
+ '00:0060 JoypadTransitionInterrupt',
+ '00:0060 .code:8',
+
+ '00:0100 Boot',
+ '00:0100 .code:4',
+ '00:0104 HeaderLogo',
+ '00:0104 .data:30',
+ '00:0134 HeaderTitle',
+ '00:0134 .text:10',
+ '00:0144 .data:c',
+ '00:0144 HeaderNewLicenseeCode',
+ '00:0146 HeaderSGBFlag',
+ '00:0147 HeaderCartridgeType',
+ '00:0148 HeaderROMSize',
+ '00:0149 HeaderRAMSize',
+ '00:014a HeaderDestinationCode',
+ '00:014b HeaderOldLicenseeCode',
+ '00:014c HeaderMaskROMVersion',
+ '00:014d HeaderComplementCheck',
+ '00:014e HeaderGlobalChecksum',
+]
+
+gbc_symbols = [
+ '00:0134 .text:b',
+ '00:013f HeaderManufacturerCode',
+ '00:013f .text:4',
+ '00:0143 HeaderCGBFlag',
+ '00:0143 .data:1'
+]
+
+hardware_labels = {
+ 0xFF00: 'rP1',
+ 0xFF01: 'rSB',
+ 0xFF02: 'rSC',
+ 0xFF04: 'rDIV',
+ 0xFF05: 'rTIMA',
+ 0xFF06: 'rTMA',
+ 0xFF07: 'rTAC',
+ 0xFF0F: 'rIF',
+ 0xFF40: 'rLCDC',
+ 0xFF41: 'rSTAT',
+ 0xFF42: 'rSCY',
+ 0xFF43: 'rSCX',
+ 0xFF44: 'rLY',
+ 0xFF45: 'rLYC',
+ 0xFF46: 'rDMA',
+ 0xFF47: 'rBGP',
+ 0xFF48: 'rOBP0',
+ 0xFF49: 'rOBP1',
+ 0xFF4A: 'rWY',
+ 0xFF4B: 'rWX',
+ 0xFF4D: 'rKEY1',
+ 0xFF4F: 'rVBK',
+ 0xFF51: 'rHDMA1',
+ 0xFF52: 'rHDMA2',
+ 0xFF53: 'rHDMA3',
+ 0xFF54: 'rHDMA4',
+ 0xFF55: 'rHDMA5',
+ 0xFF56: 'rRP',
+ 0xFF68: 'rBCPS',
+ 0xFF69: 'rBCPD',
+ 0xFF6A: 'rOCPS',
+ 0xFF6B: 'rOCPD',
+ 0xFF70: 'rSVBK',
+ 0xFFFF: 'rIE',
+ 0xFF24: 'rNR50',
+ 0xFF25: 'rNR51',
+ 0xFF26: 'rNR52',
+ 0xFF10: 'rNR10',
+ 0xFF11: 'rNR11',
+ 0xFF12: 'rNR12',
+ 0xFF13: 'rNR13',
+ 0xFF14: 'rNR14',
+ 0xFF16: 'rNR21',
+ 0xFF17: 'rNR22',
+ 0xFF18: 'rNR23',
+ 0xFF19: 'rNR24',
+ 0xFF1A: 'rNR30',
+ 0xFF1B: 'rNR31',
+ 0xFF1C: 'rNR32',
+ 0xFF1D: 'rNR33',
+ 0xFF1E: 'rNR34',
+ 0xFF20: 'rNR41',
+ 0xFF21: 'rNR42',
+ 0xFF22: 'rNR43',
+ 0xFF23: 'rNR44',
+ 0xFF76: 'rPCM12',
+ 0xFF77: 'rPCM34',
+}
+
+ldh_a8_formatters = {
+ 'ldh_a8': lambda value: '[{0}]'.format(hex_byte(value)),
+ 'ld_ff00_a8': lambda value: '[{0}+{1}]'.format(hex_word(0xff00), hex_byte(value)),
+ 'ldh_ffa8': lambda value: '[{0}]'.format(hex_word(0xff00 + value)),
+}
+
+def abort(message):
+ print(message)
+ os._exit(1)
+
+
+def hex_word(value):
+ return format_hex('${:04x}'.format(value))
+
+
+def hex_byte(value):
+ return format_hex('${:02x}'.format(value))
+
+
+def format_hex(hex_string):
+ if style['uppercase_hex']:
+ return hex_string.upper()
+ else:
+ return hex_string.lower()
+
+def bytes_to_string(data):
+ return ' '.join(hex_byte(byte) for byte in data)
+
+
+def rom_address_to_mem_address(address):
+ if address < 0x4000:
+ return address
+ else:
+ return ((address % 0x4000) + 0x4000)
+
+
+def to_signed(value):
+ if value > 127:
+ return (256 - value) * -1
+ return value
+
+def apply_style_to_instructions(style, instructions):
+ # set undefined opcodes to use db/DB
+ for opcode, instruction in instructions.items():
+ if instruction.startswith('db '):
+ instructions[opcode] = style['db'] + ' ' + hex_byte(opcode)
+
+ # set instruction variants
+ for variant_name, variants in instruction_variants.items():
+ for opcode, instruction in variants[style[variant_name]].items():
+ instructions[opcode] = instruction
+
+ return instructions
+
+
+class Bank:
+
+ def __init__(self, number, symbols, style):
+ self.style = style
+ self.bank_number = number
+ self.blocks = dict()
+ self.disassembled_addresses = set()
+ self.symbols = symbols
+
+ if number == 0:
+ self.memory_base_address = 0
+ self.rom_base_address = 0
+ else:
+ self.memory_base_address = 0x4000
+ self.rom_base_address = (number - 1) * 0x4000
+
+ self.target_addresses = dict({
+ 'call': set(),
+ 'jp': set(),
+ 'jr': set()
+ })
+
+ self.instruction_label_prefixes = dict({
+ 'call': 'Call',
+ 'jp': 'Jump',
+ 'jr': 'jr'
+ })
+
+ self.disassemble_block_range = dict({
+ 'code': self.process_code_in_range,
+ 'data': self.process_data_in_range,
+ 'text': self.process_text_in_range,
+ 'image': self.process_image_in_range
+ })
+
+
+ def add_target_address(self, instruction_name, address):
+ if address not in self.target_addresses[instruction_name]:
+ self.target_addresses[instruction_name].add(address)
+
+
+ def resolve_blocks(self):
+ blocks = self.symbols.get_blocks(self.bank_number)
+ block_start_addresses = sorted(blocks.keys())
+ resolved_blocks = dict()
+
+ for index in range(len(block_start_addresses)):
+
+ start_address = block_start_addresses[index]
+ block = blocks[start_address]
+ end_address = start_address + block['length']
+
+ # check if there is another block after this block
+ next_start_address = None
+ if index < len(block_start_addresses) - 1:
+ next_start_address = block_start_addresses[index + 1]
+
+ # if the next block starts before this one finishes, then adjust end address
+ if next_start_address < end_address:
+ end_address = next_start_address
+
+ resolved_blocks[start_address] = {
+ 'type': block['type'],
+ 'length': end_address - start_address,
+ 'arguments': block['arguments'],
+ }
+
+ if next_start_address is None and (end_address != self.memory_base_address + 0x4000):
+ # no more blocks and didn't finish at the end of the block, so finish up with a code block
+ resolved_blocks[end_address] = {
+ 'type': 'code',
+ 'length': (self.memory_base_address + 0x4000) - end_address,
+ 'arguments': None
+ }
+
+ if next_start_address is not None and end_address < next_start_address:
+ # we have another block, but there is a gap until the next block, so fill in the gap with a code block
+ resolved_blocks[end_address] = {
+ 'type': 'code',
+ 'length': next_start_address - end_address,
+ 'arguments': None
+ }
+
+ self.blocks = resolved_blocks
+
+ def get_label_for_instruction_operand(self, value):
+ # an operand value lower than $100 is more probably an actual value than an address:
+ # don't lookup symbols for it
+ if value <= 0x100:
+ return None
+
+ return self.symbols.get_label(self.bank_number, value)
+
+ def get_label_for_jump_target(self, instruction_name, address):
+ if self.bank_number == 0:
+ if address not in self.disassembled_addresses:
+ return None
+ else:
+ # TODO: if target address is in bank 0 then should check if that address
+ # has been disassembled in bank 0. requires access to bank 0 from
+ # other bank objects
+
+ is_in_switchable_bank = 0x4000 <= address < 0x8000
+ if is_in_switchable_bank and address not in self.disassembled_addresses:
+ return None
+
+ label = self.symbols.get_label(self.bank_number, address)
+ if label is not None:
+ # if the address has a specific label then just use that
+ return label
+
+ if address in self.target_addresses[instruction_name]:
+ return self.format_label(instruction_name, address)
+
+ return None
+
+
+ def get_labels_for_non_code_address(self, address):
+ labels = list()
+
+ label = self.symbols.get_label(self.bank_number, address)
+ if label is not None:
+ is_local = label.startswith('.')
+ if is_local:
+ labels.append(label + ':')
+ else:
+ labels.append(label + '::')
+
+ return labels
+
+
+ def get_labels_for_address(self, address):
+ labels = list()
+
+ label = self.symbols.get_label(self.bank_number, address)
+ if label is not None:
+ # if the address has a specific label then just use that
+ is_local = label.startswith('.')
+ if is_local:
+ labels.append(label + ':')
+ else:
+ labels.append(label + '::')
+ else:
+ # otherwise, if the address was marked as a target address, generate a label
+ for instruction_name in ['call', 'jp', 'jr']:
+ if address in self.target_addresses[instruction_name]:
+ labels.append(self.format_label(instruction_name, address) + ':')
+
+ return labels
+
+
+ def format_label(self, instruction_name, address):
+ formatted_bank = format_hex('{:03x}'.format(self.bank_number))
+ formatted_address = format_hex('{:04x}'.format(address))
+ return '{0}_{1}_{2}'.format(self.instruction_label_prefixes[instruction_name], formatted_bank, formatted_address)
+
+
+ def format_image_label(self, address):
+ return 'image_{0:03x}_{1:04x}'.format(self.bank_number, address)
+
+
+ def format_instruction(self, instruction_name, operands, address = None, source_bytes = None):
+ instruction = '{indentation}{instruction_name:<{operand_padding}} {operands}'.format(
+ indentation=self.style['indentation'],
+ instruction_name=instruction_name,
+ operand_padding=self.style['operand_padding'],
+ operands=', '.join(operands)
+ )
+
+ if self.style['print_hex'] and address is not None and source_bytes is not None:
+ return '{0:<50}; {1}: {2}'.format(instruction, hex_word(address), bytes_to_string(source_bytes))
+ else:
+ return '{0}'.format(instruction.rstrip())
+
+
+ def format_data(self, data):
+ return self.format_instruction(self.style['db'], data)
+
+
+ def append_output(self, text):
+ self.output.append(text)
+
+
+ def append_labels_to_output(self, labels):
+ self.append_empty_line_if_none_already()
+ self.append_output('\n'.join(labels))
+
+
+ def append_empty_line_if_none_already(self):
+ if len(self.output) > 0 and self.output[len(self.output) - 1] != '':
+ self.append_output('')
+
+
+ def disassemble(self, rom, first_pass = False):
+ self.first_pass = first_pass
+
+ if first_pass:
+ self.resolve_blocks()
+
+ self.output = list()
+
+ if self.bank_number == 0:
+ self.append_output('SECTION "ROM Bank ${0:03x}", ROM0[$0]'.format(self.bank_number))
+ else:
+ self.append_output('SECTION "ROM Bank ${0:03x}", ROMX[$4000], BANK[${0:x}]'.format(self.bank_number))
+ self.append_output('')
+
+ block_start_addresses = sorted(self.blocks.keys())
+
+ for index in range(len(block_start_addresses)):
+ start_address = block_start_addresses[index]
+ block = self.blocks[start_address]
+ end_address = start_address + block['length']
+ self.disassemble_block_range[block['type']](rom, self.rom_base_address + start_address, self.rom_base_address + end_address, block['arguments'])
+ self.append_empty_line_if_none_already()
+
+ return '\n'.join(self.output)
+
+
+ def process_code_in_range(self, rom, start_address, end_address, arguments = None):
+ if not self.first_pass and debug:
+ print('Disassembling code in range: {} - {}'.format(hex_word(start_address), hex_word(end_address)))
+
+ self.pc = start_address
+ while self.pc < end_address:
+ instruction = self.disassemble_at_pc(rom, end_address)
+
+
+ def disassemble_at_pc(self, rom, end_address):
+ pc = self.pc
+ pc_mem_address = rom_address_to_mem_address(pc)
+ length = 1
+ opcode = rom.data[pc]
+ comment = None
+ operands = None
+ operand_values = list()
+
+ if opcode not in instructions:
+ abort('Unhandled opcode: {} at {}'.format(hex_byte(opcode), hex_word(pc)))
+
+ if opcode == 0xCB:
+ cb_opcode = rom.data[pc + 1]
+ length += 1
+
+ instruction_name = rom.cb_instruction_name[cb_opcode]
+ operands = rom.cb_instruction_operands[cb_opcode]
+ else:
+ instruction_name = rom.instruction_names[opcode]
+ operands = rom.instruction_operands[opcode]
+
+ if instruction_name == 'stop' or (instruction_name == 'halt' and not self.style['disable_halt_nops']):
+ if rom.data[pc + 1] == 0x00:
+ # rgbds adds a nop instruction after a stop/halt, so if that instruction
+ # exists then we can insert it as a stop/halt command with length 2
+ length += 1
+ else:
+ # otherwise handle it as a data byte
+ instruction_name = self.style['db']
+ operands = [hex_byte(opcode)]
+
+
+ # figure out the operand values for each operand
+ for operand in operands:
+ value = None
+
+ if operand == 'a16':
+ length += 2
+ value = rom.data[pc + 1] + rom.data[pc + 2] * 256
+ operand_values.append(hex_word(value))
+
+ elif operand == '[a16]':
+ length += 2
+ value = rom.data[pc + 1] + rom.data[pc + 2] * 256
+ label = self.get_label_for_instruction_operand(value)
+ if label:
+ operand_values.append('[' + label + ']')
+ else:
+ operand_values.append('[' + hex_word(value) + ']')
+
+ # rgbds converts "ld [$ff40],a" into "ld [$ff00+40],a" automatically,
+ # so use a macro to encode it as data to ensure exact binary reproduction of the rom
+ if not self.style['disable_auto_ldh']:
+ if value >= 0xff00 and (opcode == 0xea or opcode == 0xfa):
+ rom.has_ld_long = True
+
+ # use ld_long macro
+ instruction_name = 'ld_long'
+
+ # cannot wrap the address value with square brackets
+ operand_values.pop()
+ operand_values.append(hex_word(value))
+
+ elif operand == '[$ff00+a8]' or operand == '[a8]' or operand == '[$ffa8]':
+ length += 1
+ value = rom.data[pc + 1]
+ full_value = 0xff00 + value
+ label = self.get_label_for_instruction_operand(full_value)
+ if label is not None:
+ # when referencing a label, we need to explicitely tell rgbds to use the short load opcode
+ instruction_name = 'ldh'
+ operand_values.append('[{}]'.format(label))
+ elif full_value in hardware_labels:
+ operand_values.append('[{}]'.format(hardware_labels[full_value]))
+ else:
+ # use one of the ldh_a8_formatters formatters
+ operand_values.append(ldh_a8_formatters[self.style['ldh_a8']](value))
+
+ elif operand == 'd8':
+ length += 1
+ value = rom.data[pc + 1]
+ operand_values.append(hex_byte(value))
+
+ elif operand == 'd16':
+ length += 2
+ value = rom.data[pc + 1] + rom.data[pc + 2] * 256
+ label = self.get_label_for_instruction_operand(value)
+ if label is not None:
+ operand_values.append(label)
+ else:
+ operand_values.append(hex_word(value))
+
+ elif operand == 'r8':
+ length += 1
+ value = to_signed(rom.data[pc + 1])
+ if value < 0:
+ operand_values.append('-' + hex_byte(abs(value)))
+ else:
+ operand_values.append(hex_byte(value))
+
+ elif operand == 'pc+r8':
+ length += 1
+ value = to_signed(rom.data[pc + 1])
+
+ # calculate the absolute address for the jump
+ value = pc + 2 + value
+
+ relative_value = value - pc
+ if relative_value >= 0:
+ operand_values.append('@+' + hex_byte(relative_value))
+ else:
+ operand_values.append('@-' + hex_byte(relative_value * -1))
+
+ target_bank = value // 0x4000
+
+ # convert to banked value so it can be used as a label
+ value = rom_address_to_mem_address(value)
+
+ if self.bank_number != target_bank:
+ # don't use labels for relative jumps across banks
+ value = None
+
+ if target_bank < self.bank_number:
+ # output as data, otherwise RGBDS will complain
+ instruction_name = self.style['db']
+ operand_values = [hex_byte(opcode), hex_byte(rom.data[pc + 1])]
+
+ # exit the loop to avoid processing the operands any further
+ break
+
+ elif operand == 'sp+r8':
+ length += 1
+ value = to_signed(rom.data[pc + 1])
+
+ if value < 0:
+ operand_values.append('sp-' + hex_byte(abs(value)))
+ else:
+ operand_values.append('sp+' + hex_byte(value))
+
+ elif operand == '[$ff00+c]':
+ operand_values.append('[{0}+c]'.format(hex_word(0xff00)))
+
+ elif type(operand) is str:
+ operand_values.append(operand)
+
+ else:
+ operand_values.append(hex_byte(operand))
+
+
+ if instruction_name in ['jr', 'jp', 'call'] and value is not None and value < 0x8000:
+ mem_address = rom_address_to_mem_address(value)
+
+ if self.first_pass:
+ # dont allow switched banks to create labels in bank 0
+ is_address_in_current_bank = (mem_address < 0x4000 and self.bank_number == 0) or (mem_address >= 0x4000 and self.bank_number > 0)
+ if is_address_in_current_bank:
+ # add the label
+ self.add_target_address(instruction_name, mem_address)
+ else:
+ # fetch the label name
+ label = self.get_label_for_jump_target(instruction_name, mem_address)
+ if label is not None:
+ # remove the address from operand values and use the label instead
+ operand_values.pop()
+ operand_values.append(label)
+
+
+ # check the instruction is not spanning 2 banks
+ if pc + length - 1 >= end_address:
+ # must handle it as data
+ length = 1
+ instruction_name = self.style['db']
+ operand_values = [hex_byte(opcode)]
+
+ self.pc += length
+
+ if self.first_pass:
+ self.disassembled_addresses.add(pc_mem_address)
+ else:
+ labels = self.get_labels_for_address(pc_mem_address)
+ if len(labels):
+ self.append_labels_to_output(labels)
+
+ if comment is not None:
+ self.append_output(comment)
+
+ instruction_bytes = rom.data[pc:pc + length]
+ self.append_output(self.format_instruction(instruction_name, operand_values, pc_mem_address, instruction_bytes))
+
+ # add some empty lines after returns and jumps to break up the code blocks
+ if instruction_name in ['ret', 'reti', 'jr', 'jp']:
+ if (
+ instruction_name == 'jr' or
+ (instruction_name == 'jp' and len(operand_values) > 1) or
+ (instruction_name == 'ret' and len(operand_values) > 0)
+ ):
+ # conditional or jr
+ self.append_output('')
+ else:
+ # always executes
+ self.append_output('')
+ self.append_output('')
+
+
+ def process_data_in_range(self, rom, start_address, end_address, arguments = None):
+ if not self.first_pass and debug:
+ print('Outputting data in range: {} - {}'.format(hex_word(start_address), hex_word(end_address)))
+
+ values = list()
+
+ for address in range(start_address, end_address):
+ mem_address = rom_address_to_mem_address(address)
+
+ labels = self.get_labels_for_non_code_address(mem_address)
+ if len(labels):
+ # add any existing values to the output and reset the list
+ if len(values) > 0:
+ self.append_output(self.format_data(values))
+ values = list()
+
+ self.append_labels_to_output(labels)
+
+ values.append(hex_byte(rom.data[address]))
+
+ # output max of 16 bytes per line, and ensure any remaining values are output
+ if len(values) == 16 or (address == end_address - 1 and len(values)):
+ self.append_output(self.format_data(values))
+ values = list()
+
+
+ def process_text_in_range(self, rom, start_address, end_address, arguments = None):
+ if not self.first_pass and debug:
+ print('Outputting text in range: {} - {}'.format(hex_word(start_address), hex_word(end_address)))
+
+ values = list()
+ text = ''
+
+ for address in range(start_address, end_address):
+ mem_address = rom_address_to_mem_address(address)
+
+ labels = self.get_labels_for_non_code_address(mem_address)
+ if len(labels):
+ # add any existing values to the output and reset the list
+ if len(text):
+ values.append('"{}"'.format(text))
+ text = ''
+
+ if len(values):
+ self.append_output(self.format_data(values))
+ values = list()
+
+ self.append_labels_to_output(labels)
+
+ byte = rom.data[address]
+ if byte >= 0x20 and byte < 0x7F:
+ text += chr(byte)
+ else:
+ if len(text):
+ values.append('"{}"'.format(text))
+ text = ''
+ values.append(hex_byte(byte))
+
+ if len(text):
+ values.append('"{}"'.format(text))
+
+ if len(values):
+ self.append_output(self.format_data(values))
+
+ def process_image_in_range(self, rom, start_address, end_address, arguments = None):
+ if not self.first_pass and debug:
+ print('Outputting image in range: {} - {}'.format(hex_word(start_address), hex_word(end_address)))
+
+ if self.first_pass:
+ return
+
+ mem_address = rom_address_to_mem_address(start_address)
+ labels = self.get_labels_for_non_code_address(mem_address)
+ if len(labels):
+ self.append_labels_to_output(labels)
+ basename = labels[0].rstrip(':')
+ else:
+ basename = self.format_image_label(mem_address)
+
+ full_filename = rom.write_image(basename, arguments, rom.data[start_address:end_address])
+ self.append_output(self.format_instruction('INCBIN', ['\"' + full_filename + '\"']))
+
+
+
+
+class Symbols:
+ def __init__(self):
+ self.symbols = dict()
+ self.blocks = dict()
+
+ def load_sym_file(self, symbols_path):
+ f = open(symbols_path, 'r')
+
+ for line in f:
+ # ignore comments and empty lines
+ if line[0] != ';' and len(line.strip()):
+ self.add_symbol_definition(line)
+
+ f.close()
+
+
+ def add_symbol_definition(self, symbol_def):
+ try:
+ location, label = symbol_def.split()
+ bank, address = location.split(':')
+ bank = int(bank, 16)
+ address = int(address, 16)
+ except:
+ print("Ignored invalid symbol definition: {}\n".format(symbol_def))
+ else:
+ label_parts = label.split(':')
+ is_block_definition = label[0] == '.' and len(label_parts) >= 2
+
+ if is_block_definition:
+ # add a block
+ block_type = label_parts[0].lower()
+ data_length = int(label_parts[1], 16)
+
+ if block_type in ['.byt', '.data']:
+ block_type = 'data'
+
+ elif block_type in ['.asc', '.text']:
+ block_type = 'text'
+
+ elif block_type in ['.code']:
+ block_type = 'code'
+
+ elif block_type in ['.image']:
+ block_type = 'image'
+
+ else:
+ return
+
+ if len(label_parts) == 3:
+ arguments = label_parts[2]
+ else:
+ arguments = None
+
+ self.add_block(bank, address, block_type, data_length, arguments)
+
+ else:
+ # add the label
+ self.add_label(bank, address, label)
+
+ def add_block(self, bank, address, block_type, length, arguments = None):
+ memory_base_address = 0x0000 if bank == 0 else 0x4000
+
+ if address >= memory_base_address:
+ blocks = self.get_blocks(bank)
+ blocks[address] = {
+ 'type': block_type,
+ 'length': length,
+ 'arguments': arguments
+ }
+
+ def add_label(self, bank, address, label):
+ if bank not in self.symbols:
+ self.symbols[bank] = dict()
+
+ is_symbol_banked = 0x4000 <= address < 0x8000
+ if is_symbol_banked:
+ self.symbols[bank][address] = label
+ else:
+ self.symbols[0][address] = label
+
+ def get_label(self, bank, address):
+ # attempt to find a banked symbol
+ is_symbol_banked = 0x4000 <= address < 0x8000
+ if is_symbol_banked and bank in self.symbols and address in self.symbols[bank]:
+ return self.symbols[bank][address]
+
+ # attempt to find a symbol in non-banked space (stored as bank 0)
+ if 0 in self.symbols and address in self.symbols[0]:
+ return self.symbols[0][address]
+
+ return None
+
+ def get_blocks(self, bank):
+ memory_base_address = 0x0000 if bank == 0 else 0x4000
+
+ if bank not in self.blocks:
+ self.blocks[bank] = dict()
+ # each bank defaults to having a single code block
+ self.add_block(bank, memory_base_address, 'code', 0x4000)
+
+ return self.blocks[bank]
+
+class ROM:
+
+ def __init__(self, rom_path, style):
+ self.style = style
+ self.script_dir = os.path.dirname(os.path.realpath(__file__))
+ self.rom_path = rom_path
+ self.load()
+ self.split_instructions()
+ self.has_ld_long = False
+
+ self.image_output_directory = 'gfx'
+ self.image_dependencies = []
+
+ print('ROM MD5 hash:', hashlib.md5(self.data).hexdigest())
+
+ self.symbols = self.load_symbols()
+
+ # add some bytes to avoid an index out of range error
+ # when processing last few instructions in the rom
+ self.data += b'\x00\x00'
+
+ self.banks = dict()
+ for bank in range(0, self.num_banks):
+ self.banks[bank] = Bank(bank, self.symbols, style)
+
+ def load(self):
+ if os.path.isfile(self.rom_path):
+ print('Loading "{}"...'.format(self.rom_path))
+ self.data = open(self.rom_path, 'rb').read()
+ self.rom_size = len(self.data)
+ self.num_banks = self.rom_size // 0x4000
+ else:
+ abort('"{}" not found'.format(self.rom_path))
+
+
+ def split_instructions(self):
+ # split the instructions and operands
+ self.instruction_names = dict()
+ self.instruction_operands = dict()
+ self.cb_instruction_name = dict()
+ self.cb_instruction_operands = dict()
+
+ for opcode in instructions:
+ instruction_parts = instructions[opcode].split()
+ self.instruction_names[opcode] = instruction_parts[0]
+ if len(instruction_parts) > 1:
+ self.instruction_operands[opcode] = instruction_parts[1].split(',')
+ else:
+ self.instruction_operands[opcode] = list()
+
+ for cb_opcode in cb_instructions:
+ instruction_parts = cb_instructions[cb_opcode].split()
+ self.cb_instruction_name[cb_opcode] = instruction_parts[0]
+ if len(instruction_parts) > 1:
+ self.cb_instruction_operands[cb_opcode] = instruction_parts[1].split(',')
+ else:
+ self.cb_instruction_operands[cb_opcode] = list()
+
+
+ def load_symbols(self):
+ symbols = Symbols()
+
+ for symbol_def in default_symbols:
+ symbols.add_symbol_definition(symbol_def)
+
+ if self.supports_gbc():
+ for symbol_def in gbc_symbols:
+ symbols.add_symbol_definition(symbol_def)
+
+ symbols_path = os.path.splitext(self.rom_path)[0] + '.sym'
+ if os.path.isfile(symbols_path):
+ print('Processing symbol file "{}"...'.format(symbols_path))
+ symbols.load_sym_file(symbols_path)
+
+ return symbols
+
+
+ def supports_gbc(self):
+ return ((self.data[0x143] & 0x80) == 0x80)
+
+
+ def disassemble(self, output_dir):
+
+ self.output_directory = os.path.abspath(output_dir.rstrip(os.sep))
+
+ if os.path.exists(self.output_directory):
+ if not args.overwrite:
+ abort('Output directory "{}" already exists!'.format(self.output_directory))
+
+ if not os.path.isdir(self.output_directory):
+ abort('Output path "{}" already exists and is not a directory!'.format(self.output_directory))
+ else:
+ os.makedirs(self.output_directory)
+
+
+ print('Generating labels...')
+ self.generate_labels()
+
+ self.image_dependencies = []
+
+ print('Generating disassembly', end='')
+ if debug:
+ print('')
+
+ for bank in range(0, self.num_banks):
+ self.write_bank_asm(bank)
+
+ self.copy_hardware_inc()
+ self.write_game_asm()
+ self.write_makefile()
+
+ print('\nDisassembly generated in "{}"'.format(self.output_directory))
+
+
+ def generate_labels(self):
+ for bank in range(0, self.num_banks):
+ self.banks[bank].disassemble(rom, True)
+
+
+ def write_bank_asm(self, bank):
+ if not debug:
+ # progress indicator
+ print('.', end='', flush=True)
+
+ path = os.path.join(self.output_directory, 'bank_{0:03x}.asm'.format(bank))
+ f = open(path, 'w')
+
+ self.write_header(f)
+ f.write(self.banks[bank].disassemble(rom))
+
+ f.close()
+
+
+ def write_header(self, f):
+ f.write('; Disassembly of "{}"\n'.format(os.path.basename(self.rom_path)))
+ f.write('; This file was created with:\n')
+ f.write('; {}\n'.format(app_name))
+ f.write('; https://github.com/mattcurrie/mgbdis\n\n')
+
+
+ def copy_hardware_inc(self):
+ src = os.path.join(self.script_dir, 'hardware.inc')
+ dest = os.path.join(self.output_directory, 'hardware.inc')
+ copyfile(src, dest)
+
+
+ def write_game_asm(self):
+ path = os.path.join(self.output_directory, 'game.asm')
+ f = open(path, 'w')
+
+ self.write_header(f)
+
+ if self.has_ld_long:
+
+ f.write(
+"""ld_long: MACRO
+ IF STRLWR("\\1") == "a"
+ ; ld a, [$ff40]
+ db $FA
+ dw \\2
+ ELSE
+ IF STRLWR("\\2") == "a"
+ ; ld [$ff40], a
+ db $EA
+ dw \\1
+ ENDC
+ ENDC
+ENDM
+
+""")
+
+ f.write('INCLUDE "hardware.inc"')
+ for bank in range(0, self.num_banks):
+ f.write('\nINCLUDE "bank_{0:03x}.asm"'.format(bank))
+ f.close()
+
+
+ def write_image(self, basename, arguments, data):
+
+ # defaults
+ width = 128
+ palette = 0xe4
+ bpp = 2
+
+ # process arguments
+ if arguments is not None:
+ for argument in arguments.split(','):
+ if len(argument) > 1:
+ if argument[0] == 'w':
+ # width is in decimal
+ width = int(argument[1:], 10)
+
+ elif argument[0] == 'p':
+ palette = int(argument[1:], 16)
+
+ elif argument == '1bpp':
+ bpp = 1
+
+ image_output_path = os.path.join(self.output_directory, self.image_output_directory)
+ if os.path.exists(image_output_path):
+ if not os.path.isdir(image_output_path):
+ abort('File already exists named "{}". Cannot store images!'.format(image_output_path))
+ else:
+ os.makedirs(image_output_path)
+
+ relative_path = os.path.join(self.image_output_directory, basename + '.' + "{}bpp".format(bpp))
+ self.image_dependencies.append(relative_path)
+ path = os.path.join(self.output_directory, self.image_output_directory, basename + '.png')
+
+ bytes_per_tile_row = bpp # 8 pixels at 1 or 2 bits per pixel
+ bytes_per_tile = bytes_per_tile_row * 8 # 8 rows per tile
+
+ num_tiles = len(data) // bytes_per_tile
+ tiles_per_row = width // 8
+
+ # if we have fewer tiles than the number of tiles per row, or if an odd number of tiles
+ if (num_tiles < tiles_per_row) or (num_tiles & 1):
+ # then just make a single row of tiles
+ tiles_per_row = num_tiles
+ width = num_tiles * 8
+
+ tile_rows = (num_tiles / tiles_per_row)
+ if not tile_rows.is_integer():
+ abort('Invalid length ${:0x} or width {} for image block: {}'.format(len(data), width, basename))
+
+ height = int(tile_rows) * 8
+
+ pixel_data = self.convert_to_pixel_data(data, width, height, bpp)
+ rgb_palette = self.convert_palette_to_rgb(palette, bpp)
+
+ f = open(path, 'wb')
+ w = png.Writer(width, height, alpha=False, bitdepth=2, palette=rgb_palette)
+ w.write(f, pixel_data)
+ f.close()
+
+ return relative_path
+
+
+ def convert_to_pixel_data(self, data, width, height, bpp):
+ result = []
+ for y in range(0, height):
+ row = []
+ for x in range(0, width):
+ offset = self.coordinate_to_tile_offset(x, y, width, bpp)
+
+ if offset < len(data):
+ # extract the color from the one or two bytes of tile data at the offset
+ shift = (7 - (x & 7))
+ mask = (1 << shift)
+ if bpp == 2:
+ color = ((data[offset] & mask) >> shift) + (((data[offset + 1] & mask) >> shift) << 1)
+ else:
+ color = ((data[offset] & mask) >> shift)
+ else:
+ color = 0
+
+ row.append(color)
+ result.append(row)
+
+ return result
+
+
+ def coordinate_to_tile_offset(self, x, y, width, bpp):
+ bytes_per_tile_row = bpp # 8 pixels at 1 or 2 bits per pixel
+ bytes_per_tile = bytes_per_tile_row * 8 # 8 rows per tile
+ tiles_per_row = width // 8
+
+ tile_y = y // 8
+ tile_x = x // 8
+ row_of_tile = y & 7
+
+ return (tile_y * tiles_per_row * bytes_per_tile) + (tile_x * bytes_per_tile) + (row_of_tile * bytes_per_tile_row)
+
+
+ def convert_palette_to_rgb(self, palette, bpp):
+ col0 = 255 - (((palette & 0x03) ) << 6)
+ col1 = 255 - (((palette & 0x0C) >> 2) << 6)
+ col2 = 255 - (((palette & 0x30) >> 4) << 6)
+ col3 = 255 - (((palette & 0xC0) >> 6) << 6)
+ if bpp == 2:
+ return [
+ (col0, col0, col0),
+ (col1, col1, col1),
+ (col2, col2, col2),
+ (col3, col3, col3)
+ ]
+ else:
+ return [
+ (col0, col0, col0),
+ (col3, col3, col3)
+ ]
+
+
+ def write_makefile(self):
+ rom_extension = 'gb'
+ if self.supports_gbc():
+ rom_extension = 'gbc'
+
+ path = os.path.join(self.output_directory, 'Makefile')
+ f = open(path, 'w')
+
+ if len(self.image_dependencies):
+ f.write('IMAGE_DEPS = {}\n\n'.format(' '.join(self.image_dependencies)))
+
+ f.write('all: game.{}\n\n'.format(rom_extension))
+
+ f.write('%.2bpp: %.png\n')
+ f.write('\trgbgfx -o $@ $<\n\n')
+
+ f.write('%.1bpp: %.png\n')
+ f.write('\trgbgfx -d 1 -o $@ $<\n\n')
+
+ if len(self.image_dependencies):
+ f.write('game.o: game.asm bank_*.asm $(IMAGE_DEPS)\n')
+ else:
+ f.write('game.o: game.asm bank_*.asm\n')
+
+ parameters = []
+ if self.style['disable_halt_nops']:
+ parameters.append('-h')
+ if self.style['disable_auto_ldh']:
+ parameters.append('-L')
+ f.write('\trgbasm {} -o game.o game.asm\n\n'.format(' '.join(parameters)))
+
+ f.write('game.{}: game.o\n'.format(rom_extension))
+ f.write('\trgblink -n game.sym -m game.map -o $@ $<\n')
+ f.write('\trgbfix -v -p 255 $@\n\n')
+ f.write('\tmd5 $@\n\n')
+
+ f.write('clean:\n')
+ f.write('\trm -f game.o game.{} game.sym game.map\n'.format(rom_extension))
+ f.write('\tfind . \\( -iname \'*.1bpp\' -o -iname \'*.2bpp\' \\) -exec rm {} +')
+
+ f.close()
+
+
+
+app_name = 'mgbdis v{version} - Game Boy ROM disassembler by {author}.'.format(version=__version__, author=__author__)
+parser = argparse.ArgumentParser(description=app_name)
+parser.add_argument('rom_path', help='Game Boy (Color) ROM file to disassemble')
+parser.add_argument('--output-dir', default='disassembly', help='Directory to write the files into. Defaults to "disassembly"', action='store')
+parser.add_argument('--uppercase-hex', help='Print hexadecimal numbers using uppercase characters', action='store_true')
+parser.add_argument('--print-hex', help='Print the hexadecimal representation next to the opcodes', action='store_true')
+parser.add_argument('--align-operands', help='Format the instruction operands to align them vertically', action='store_true')
+parser.add_argument('--indent-spaces', help='Number of spaces to use to indent instructions', type=int, default=4)
+parser.add_argument('--indent-tabs', help='Use tabs for indenting instructions', action='store_true')
+parser.add_argument('--uppercase-db', help='Use uppercase for DB data declarations', action='store_true')
+parser.add_argument('--hli', help='Mnemonic to use for \'ld [hl+], a\' type instructions.', type=str, default='hl+', choices=['hl+', 'hli', 'ldi'])
+parser.add_argument('--ldh_a8', help='Mnemonic to use for \'ldh [a8], a\' type instructions.', type=str, default='ldh_a8', choices=['ldh_a8', 'ldh_ffa8', 'ld_ff00_a8'])
+parser.add_argument('--ld_c', help='Mnemonic to use for \'ld [c], a\' type instructions.', type=str, default='ld_c', choices=['ld_c', 'ldh_c', 'ld_ff00_c'])
+parser.add_argument('--disable-halt-nops', help='Disable RGBDS\'s automatic insertion of \'nop\' instructions after \'halt\' instructions.', action='store_true')
+parser.add_argument('--disable-auto-ldh', help='Disable RGBDS\'s automatic optimisation of \'ld [$ff00+a8], a\' to \'ldh [a8], a\' instructions. Requires RGBDS >= v0.3.7', action='store_true')
+parser.add_argument('--overwrite', help='Allow generating a disassembly into an already existing directory', action='store_true')
+parser.add_argument('--debug', help='Display debug output', action='store_true')
+args = parser.parse_args()
+
+debug = args.debug
+
+style = {
+ 'uppercase_hex': args.uppercase_hex,
+ 'print_hex': args.print_hex,
+ 'indentation': '\t' if args.indent_tabs else ' ' * args.indent_spaces,
+ 'operand_padding': 4 if args.align_operands else 0,
+ 'db': 'DB' if args.uppercase_db else 'db',
+ 'hli': args.hli,
+ 'ldh_a8': args.ldh_a8,
+ 'ld_c': args.ld_c,
+ 'disable_halt_nops': args.disable_halt_nops,
+ 'disable_auto_ldh': args.disable_auto_ldh,
+}
+instructions = apply_style_to_instructions(style, instructions)
+
+rom = ROM(args.rom_path, style)
+rom.disassemble(args.output_dir)
diff --git a/mgbdis/png.py b/mgbdis/png.py
new file mode 100644
index 0000000..5343308
--- /dev/null
+++ b/mgbdis/png.py
@@ -0,0 +1,2638 @@
+#!/usr/bin/env python
+
+from __future__ import print_function
+
+# png.py - PNG encoder/decoder in pure Python
+#
+# Copyright (C) 2006 Johann C. Rocholl <johann@browsershots.org>
+# Portions Copyright (C) 2009 David Jones <drj@pobox.com>
+# And probably portions Copyright (C) 2006 Nicko van Someren <nicko@nicko.org>
+#
+# Original concept by Johann C. Rocholl.
+#
+# LICENCE (MIT)
+#
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation files
+# (the "Software"), to deal in the Software without restriction,
+# including without limitation the rights to use, copy, modify, merge,
+# publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Pure Python PNG Reader/Writer
+
+This Python module implements support for PNG images (see PNG
+specification at http://www.w3.org/TR/2003/REC-PNG-20031110/ ). It reads
+and writes PNG files with all allowable bit depths
+(1/2/4/8/16/24/32/48/64 bits per pixel) and colour combinations:
+greyscale (1/2/4/8/16 bit); RGB, RGBA, LA (greyscale with alpha) with
+8/16 bits per channel; colour mapped images (1/2/4/8 bit).
+Adam7 interlacing is supported for reading and
+writing. A number of optional chunks can be specified (when writing)
+and understood (when reading): ``tRNS``, ``bKGD``, ``gAMA``.
+
+For help, type ``import png; help(png)`` in your python interpreter.
+
+A good place to start is the :class:`Reader` and :class:`Writer`
+classes.
+
+Requires Python 2.3. Limited support is available for Python 2.2, but
+not everything works. Best with Python 2.4 and higher. Installation is
+trivial, but see the ``README.txt`` file (with the source distribution)
+for details.
+
+This file can also be used as a command-line utility to convert
+`Netpbm <http://netpbm.sourceforge.net/>`_ PNM files to PNG, and the
+reverse conversion from PNG to PNM. The interface is similar to that
+of the ``pnmtopng`` program from Netpbm. Type ``python png.py --help``
+at the shell prompt for usage and a list of options.
+
+A note on spelling and terminology
+----------------------------------
+
+Generally British English spelling is used in the documentation. So
+that's "greyscale" and "colour". This not only matches the author's
+native language, it's also used by the PNG specification.
+
+The major colour models supported by PNG (and hence by PyPNG) are:
+greyscale, RGB, greyscale--alpha, RGB--alpha. These are sometimes
+referred to using the abbreviations: L, RGB, LA, RGBA. In this case
+each letter abbreviates a single channel: *L* is for Luminance or Luma
+or Lightness which is the channel used in greyscale images; *R*, *G*,
+*B* stand for Red, Green, Blue, the components of a colour image; *A*
+stands for Alpha, the opacity channel (used for transparency effects,
+but higher values are more opaque, so it makes sense to call it
+opacity).
+
+A note on formats
+-----------------
+
+When getting pixel data out of this module (reading) and presenting
+data to this module (writing) there are a number of ways the data could
+be represented as a Python value. Generally this module uses one of
+three formats called "flat row flat pixel", "boxed row flat pixel", and
+"boxed row boxed pixel". Basically the concern is whether each pixel
+and each row comes in its own little tuple (box), or not.
+
+Consider an image that is 3 pixels wide by 2 pixels high, and each pixel
+has RGB components:
+
+Boxed row flat pixel::
+
+ list([R,G,B, R,G,B, R,G,B],
+ [R,G,B, R,G,B, R,G,B])
+
+Each row appears as its own list, but the pixels are flattened so
+that three values for one pixel simply follow the three values for
+the previous pixel. This is the most common format used, because it
+provides a good compromise between space and convenience. PyPNG regards
+itself as at liberty to replace any sequence type with any sufficiently
+compatible other sequence type; in practice each row is an array (from
+the array module), and the outer list is sometimes an iterator rather
+than an explicit list (so that streaming is possible).
+
+Flat row flat pixel::
+
+ [R,G,B, R,G,B, R,G,B,
+ R,G,B, R,G,B, R,G,B]
+
+The entire image is one single giant sequence of colour values.
+Generally an array will be used (to save space), not a list.
+
+Boxed row boxed pixel::
+
+ list([ (R,G,B), (R,G,B), (R,G,B) ],
+ [ (R,G,B), (R,G,B), (R,G,B) ])
+
+Each row appears in its own list, but each pixel also appears in its own
+tuple. A serious memory burn in Python.
+
+In all cases the top row comes first, and for each row the pixels are
+ordered from left-to-right. Within a pixel the values appear in the
+order, R-G-B-A (or L-A for greyscale--alpha).
+
+There is a fourth format, mentioned because it is used internally,
+is close to what lies inside a PNG file itself, and has some support
+from the public API. This format is called packed. When packed,
+each row is a sequence of bytes (integers from 0 to 255), just as
+it is before PNG scanline filtering is applied. When the bit depth
+is 8 this is essentially the same as boxed row flat pixel; when the
+bit depth is less than 8, several pixels are packed into each byte;
+when the bit depth is 16 (the only value more than 8 that is supported
+by the PNG image format) each pixel value is decomposed into 2 bytes
+(and `packed` is a misnomer). This format is used by the
+:meth:`Writer.write_packed` method. It isn't usually a convenient
+format, but may be just right if the source data for the PNG image
+comes from something that uses a similar format (for example, 1-bit
+BMPs, or another PNG file).
+
+And now, my famous members
+--------------------------
+"""
+
+__version__ = "0.0.18"
+
+import itertools
+import math
+import re
+# http://www.python.org/doc/2.4.4/lib/module-operator.html
+import operator
+import struct
+import sys
+# http://www.python.org/doc/2.4.4/lib/module-warnings.html
+import warnings
+import zlib
+
+from array import array
+from functools import reduce
+
+try:
+ # `cpngfilters` is a Cython module: it must be compiled by
+ # Cython for this import to work.
+ # If this import does work, then it overrides pure-python
+ # filtering functions defined later in this file (see `class
+ # pngfilters`).
+ import cpngfilters as pngfilters
+except ImportError:
+ pass
+
+
+__all__ = ['Image', 'Reader', 'Writer', 'write_chunks', 'from_array']
+
+
+# The PNG signature.
+# http://www.w3.org/TR/PNG/#5PNG-file-signature
+_signature = struct.pack('8B', 137, 80, 78, 71, 13, 10, 26, 10)
+
+_adam7 = ((0, 0, 8, 8),
+ (4, 0, 8, 8),
+ (0, 4, 4, 8),
+ (2, 0, 4, 4),
+ (0, 2, 2, 4),
+ (1, 0, 2, 2),
+ (0, 1, 1, 2))
+
+def group(s, n):
+ # See http://www.python.org/doc/2.6/library/functions.html#zip
+ return list(zip(*[iter(s)]*n))
+
+def isarray(x):
+ return isinstance(x, array)
+
+def tostring(row):
+ return row.tostring()
+
+def interleave_planes(ipixels, apixels, ipsize, apsize):
+ """
+ Interleave (colour) planes, e.g. RGB + A = RGBA.
+
+ Return an array of pixels consisting of the `ipsize` elements of
+ data from each pixel in `ipixels` followed by the `apsize` elements
+ of data from each pixel in `apixels`. Conventionally `ipixels`
+ and `apixels` are byte arrays so the sizes are bytes, but it
+ actually works with any arrays of the same type. The returned
+ array is the same type as the input arrays which should be the
+ same type as each other.
+ """
+
+ itotal = len(ipixels)
+ atotal = len(apixels)
+ newtotal = itotal + atotal
+ newpsize = ipsize + apsize
+ # Set up the output buffer
+ # See http://www.python.org/doc/2.4.4/lib/module-array.html#l2h-1356
+ out = array(ipixels.typecode)
+ # It's annoying that there is no cheap way to set the array size :-(
+ out.extend(ipixels)
+ out.extend(apixels)
+ # Interleave in the pixel data
+ for i in range(ipsize):
+ out[i:newtotal:newpsize] = ipixels[i:itotal:ipsize]
+ for i in range(apsize):
+ out[i+ipsize:newtotal:newpsize] = apixels[i:atotal:apsize]
+ return out
+
+def check_palette(palette):
+ """Check a palette argument (to the :class:`Writer` class)
+ for validity. Returns the palette as a list if okay; raises an
+ exception otherwise.
+ """
+
+ # None is the default and is allowed.
+ if palette is None:
+ return None
+
+ p = list(palette)
+ if not (0 < len(p) <= 256):
+ raise ValueError("a palette must have between 1 and 256 entries")
+ seen_triple = False
+ for i,t in enumerate(p):
+ if len(t) not in (3,4):
+ raise ValueError(
+ "palette entry %d: entries must be 3- or 4-tuples." % i)
+ if len(t) == 3:
+ seen_triple = True
+ if seen_triple and len(t) == 4:
+ raise ValueError(
+ "palette entry %d: all 4-tuples must precede all 3-tuples" % i)
+ for x in t:
+ if int(x) != x or not(0 <= x <= 255):
+ raise ValueError(
+ "palette entry %d: values must be integer: 0 <= x <= 255" % i)
+ return p
+
+def check_sizes(size, width, height):
+ """Check that these arguments, in supplied, are consistent.
+ Return a (width, height) pair.
+ """
+
+ if not size:
+ return width, height
+
+ if len(size) != 2:
+ raise ValueError(
+ "size argument should be a pair (width, height)")
+ if width is not None and width != size[0]:
+ raise ValueError(
+ "size[0] (%r) and width (%r) should match when both are used."
+ % (size[0], width))
+ if height is not None and height != size[1]:
+ raise ValueError(
+ "size[1] (%r) and height (%r) should match when both are used."
+ % (size[1], height))
+ return size
+
+def check_color(c, greyscale, which):
+ """Checks that a colour argument for transparent or
+ background options is the right form. Returns the colour
+ (which, if it's a bar integer, is "corrected" to a 1-tuple).
+ """
+
+ if c is None:
+ return c
+ if greyscale:
+ try:
+ len(c)
+ except TypeError:
+ c = (c,)
+ if len(c) != 1:
+ raise ValueError("%s for greyscale must be 1-tuple" %
+ which)
+ if not isinteger(c[0]):
+ raise ValueError(
+ "%s colour for greyscale must be integer" % which)
+ else:
+ if not (len(c) == 3 and
+ isinteger(c[0]) and
+ isinteger(c[1]) and
+ isinteger(c[2])):
+ raise ValueError(
+ "%s colour must be a triple of integers" % which)
+ return c
+
+class Error(Exception):
+ def __str__(self):
+ return self.__class__.__name__ + ': ' + ' '.join(self.args)
+
+class FormatError(Error):
+ """Problem with input file format. In other words, PNG file does
+ not conform to the specification in some way and is invalid.
+ """
+
+class ChunkError(FormatError):
+ pass
+
+
+class Writer:
+ """
+ PNG encoder in pure Python.
+ """
+
+ def __init__(self, width=None, height=None,
+ size=None,
+ greyscale=False,
+ alpha=False,
+ bitdepth=8,
+ palette=None,
+ transparent=None,
+ background=None,
+ gamma=None,
+ compression=None,
+ interlace=False,
+ bytes_per_sample=None, # deprecated
+ planes=None,
+ colormap=None,
+ maxval=None,
+ chunk_limit=2**20,
+ x_pixels_per_unit = None,
+ y_pixels_per_unit = None,
+ unit_is_meter = False):
+ """
+ Create a PNG encoder object.
+
+ Arguments:
+
+ width, height
+ Image size in pixels, as two separate arguments.
+ size
+ Image size (w,h) in pixels, as single argument.
+ greyscale
+ Input data is greyscale, not RGB.
+ alpha
+ Input data has alpha channel (RGBA or LA).
+ bitdepth
+ Bit depth: from 1 to 16.
+ palette
+ Create a palette for a colour mapped image (colour type 3).
+ transparent
+ Specify a transparent colour (create a ``tRNS`` chunk).
+ background
+ Specify a default background colour (create a ``bKGD`` chunk).
+ gamma
+ Specify a gamma value (create a ``gAMA`` chunk).
+ compression
+ zlib compression level: 0 (none) to 9 (more compressed);
+ default: -1 or None.
+ interlace
+ Create an interlaced image.
+ chunk_limit
+ Write multiple ``IDAT`` chunks to save memory.
+ x_pixels_per_unit
+ Number of pixels a unit along the x axis (write a
+ `pHYs` chunk).
+ y_pixels_per_unit
+ Number of pixels a unit along the y axis (write a
+ `pHYs` chunk). Along with `x_pixel_unit`, this gives
+ the pixel size ratio.
+ unit_is_meter
+ `True` to indicate that the unit (for the `pHYs`
+ chunk) is metre.
+
+ The image size (in pixels) can be specified either by using the
+ `width` and `height` arguments, or with the single `size`
+ argument. If `size` is used it should be a pair (*width*,
+ *height*).
+
+ `greyscale` and `alpha` are booleans that specify whether
+ an image is greyscale (or colour), and whether it has an
+ alpha channel (or not).
+
+ `bitdepth` specifies the bit depth of the source pixel values.
+ Each source pixel value must be an integer between 0 and
+ ``2**bitdepth-1``. For example, 8-bit images have values
+ between 0 and 255. PNG only stores images with bit depths of
+ 1,2,4,8, or 16. When `bitdepth` is not one of these values,
+ the next highest valid bit depth is selected, and an ``sBIT``
+ (significant bits) chunk is generated that specifies the
+ original precision of the source image. In this case the
+ supplied pixel values will be rescaled to fit the range of
+ the selected bit depth.
+
+ The details of which bit depth / colour model combinations the
+ PNG file format supports directly, are somewhat arcane
+ (refer to the PNG specification for full details). Briefly:
+ "small" bit depths (1,2,4) are only allowed with greyscale and
+ colour mapped images; colour mapped images cannot have bit depth
+ 16.
+
+ For colour mapped images (in other words, when the `palette`
+ argument is specified) the `bitdepth` argument must match one of
+ the valid PNG bit depths: 1, 2, 4, or 8. (It is valid to have a
+ PNG image with a palette and an ``sBIT`` chunk, but the meaning
+ is slightly different; it would be awkward to press the
+ `bitdepth` argument into service for this.)
+
+ The `palette` option, when specified, causes a colour
+ mapped image to be created: the PNG colour type is set to 3;
+ `greyscale` must not be set; `alpha` must not be set;
+ `transparent` must not be set; the bit depth must be 1,2,4,
+ or 8. When a colour mapped image is created, the pixel values
+ are palette indexes and the `bitdepth` argument specifies the
+ size of these indexes (not the size of the colour values in
+ the palette).
+
+ The palette argument value should be a sequence of 3- or
+ 4-tuples. 3-tuples specify RGB palette entries; 4-tuples
+ specify RGBA palette entries. If both 4-tuples and 3-tuples
+ appear in the sequence then all the 4-tuples must come
+ before all the 3-tuples. A ``PLTE`` chunk is created; if there
+ are 4-tuples then a ``tRNS`` chunk is created as well. The
+ ``PLTE`` chunk will contain all the RGB triples in the same
+ sequence; the ``tRNS`` chunk will contain the alpha channel for
+ all the 4-tuples, in the same sequence. Palette entries
+ are always 8-bit.
+
+ If specified, the `transparent` and `background` parameters must
+ be a tuple with three integer values for red, green, blue, or
+ a simple integer (or singleton tuple) for a greyscale image.
+
+ If specified, the `gamma` parameter must be a positive number
+ (generally, a `float`). A ``gAMA`` chunk will be created.
+ Note that this will not change the values of the pixels as
+ they appear in the PNG file, they are assumed to have already
+ been converted appropriately for the gamma specified.
+
+ The `compression` argument specifies the compression level to
+ be used by the ``zlib`` module. Values from 1 to 9 specify
+ compression, with 9 being "more compressed" (usually smaller
+ and slower, but it doesn't always work out that way). 0 means
+ no compression. -1 and ``None`` both mean that the default
+ level of compession will be picked by the ``zlib`` module
+ (which is generally acceptable).
+
+ If `interlace` is true then an interlaced image is created
+ (using PNG's so far only interace method, *Adam7*). This does
+ not affect how the pixels should be presented to the encoder,
+ rather it changes how they are arranged into the PNG file.
+ On slow connexions interlaced images can be partially decoded
+ by the browser to give a rough view of the image that is
+ successively refined as more image data appears.
+
+ .. note ::
+
+ Enabling the `interlace` option requires the entire image
+ to be processed in working memory.
+
+ `chunk_limit` is used to limit the amount of memory used whilst
+ compressing the image. In order to avoid using large amounts of
+ memory, multiple ``IDAT`` chunks may be created.
+ """
+
+ # At the moment the `planes` argument is ignored;
+ # its purpose is to act as a dummy so that
+ # ``Writer(x, y, **info)`` works, where `info` is a dictionary
+ # returned by Reader.read and friends.
+ # Ditto for `colormap`.
+
+ width, height = check_sizes(size, width, height)
+ del size
+
+ if width <= 0 or height <= 0:
+ raise ValueError("width and height must be greater than zero")
+ if not isinteger(width) or not isinteger(height):
+ raise ValueError("width and height must be integers")
+ # http://www.w3.org/TR/PNG/#7Integers-and-byte-order
+ if width > 2**32-1 or height > 2**32-1:
+ raise ValueError("width and height cannot exceed 2**32-1")
+
+ if alpha and transparent is not None:
+ raise ValueError(
+ "transparent colour not allowed with alpha channel")
+
+ if bytes_per_sample is not None:
+ warnings.warn('please use bitdepth instead of bytes_per_sample',
+ DeprecationWarning)
+ if bytes_per_sample not in (0.125, 0.25, 0.5, 1, 2):
+ raise ValueError(
+ "bytes per sample must be .125, .25, .5, 1, or 2")
+ bitdepth = int(8*bytes_per_sample)
+ del bytes_per_sample
+ if not isinteger(bitdepth) or bitdepth < 1 or 16 < bitdepth:
+ raise ValueError("bitdepth (%r) must be a positive integer <= 16" %
+ bitdepth)
+
+ self.rescale = None
+ palette = check_palette(palette)
+ if palette:
+ if bitdepth not in (1,2,4,8):
+ raise ValueError("with palette, bitdepth must be 1, 2, 4, or 8")
+ if transparent is not None:
+ raise ValueError("transparent and palette not compatible")
+ if alpha:
+ raise ValueError("alpha and palette not compatible")
+ if greyscale:
+ raise ValueError("greyscale and palette not compatible")
+ else:
+ # No palette, check for sBIT chunk generation.
+ if alpha or not greyscale:
+ if bitdepth not in (8,16):
+ targetbitdepth = (8,16)[bitdepth > 8]
+ self.rescale = (bitdepth, targetbitdepth)
+ bitdepth = targetbitdepth
+ del targetbitdepth
+ else:
+ assert greyscale
+ assert not alpha
+ if bitdepth not in (1,2,4,8,16):
+ if bitdepth > 8:
+ targetbitdepth = 16
+ elif bitdepth == 3:
+ targetbitdepth = 4
+ else:
+ assert bitdepth in (5,6,7)
+ targetbitdepth = 8
+ self.rescale = (bitdepth, targetbitdepth)
+ bitdepth = targetbitdepth
+ del targetbitdepth
+
+ if bitdepth < 8 and (alpha or not greyscale and not palette):
+ raise ValueError(
+ "bitdepth < 8 only permitted with greyscale or palette")
+ if bitdepth > 8 and palette:
+ raise ValueError(
+ "bit depth must be 8 or less for images with palette")
+
+ transparent = check_color(transparent, greyscale, 'transparent')
+ background = check_color(background, greyscale, 'background')
+
+ # It's important that the true boolean values (greyscale, alpha,
+ # colormap, interlace) are converted to bool because Iverson's
+ # convention is relied upon later on.
+ self.width = width
+ self.height = height
+ self.transparent = transparent
+ self.background = background
+ self.gamma = gamma
+ self.greyscale = bool(greyscale)
+ self.alpha = bool(alpha)
+ self.colormap = bool(palette)
+ self.bitdepth = int(bitdepth)
+ self.compression = compression
+ self.chunk_limit = chunk_limit
+ self.interlace = bool(interlace)
+ self.palette = palette
+ self.x_pixels_per_unit = x_pixels_per_unit
+ self.y_pixels_per_unit = y_pixels_per_unit
+ self.unit_is_meter = bool(unit_is_meter)
+
+ self.color_type = 4*self.alpha + 2*(not greyscale) + 1*self.colormap
+ assert self.color_type in (0,2,3,4,6)
+
+ self.color_planes = (3,1)[self.greyscale or self.colormap]
+ self.planes = self.color_planes + self.alpha
+ # :todo: fix for bitdepth < 8
+ self.psize = (self.bitdepth/8) * self.planes
+
+ def make_palette(self):
+ """Create the byte sequences for a ``PLTE`` and if necessary a
+ ``tRNS`` chunk. Returned as a pair (*p*, *t*). *t* will be
+ ``None`` if no ``tRNS`` chunk is necessary.
+ """
+
+ p = array('B')
+ t = array('B')
+
+ for x in self.palette:
+ p.extend(x[0:3])
+ if len(x) > 3:
+ t.append(x[3])
+ p = tostring(p)
+ t = tostring(t)
+ if t:
+ return p,t
+ return p,None
+
+ def write(self, outfile, rows):
+ """Write a PNG image to the output file. `rows` should be
+ an iterable that yields each row in boxed row flat pixel
+ format. The rows should be the rows of the original image,
+ so there should be ``self.height`` rows of ``self.width *
+ self.planes`` values. If `interlace` is specified (when
+ creating the instance), then an interlaced PNG file will
+ be written. Supply the rows in the normal image order;
+ the interlacing is carried out internally.
+
+ .. note ::
+
+ Interlacing will require the entire image to be in working
+ memory.
+ """
+
+ if self.interlace:
+ fmt = 'BH'[self.bitdepth > 8]
+ a = array(fmt, itertools.chain(*rows))
+ return self.write_array(outfile, a)
+
+ nrows = self.write_passes(outfile, rows)
+ if nrows != self.height:
+ raise ValueError(
+ "rows supplied (%d) does not match height (%d)" %
+ (nrows, self.height))
+
+ def write_passes(self, outfile, rows, packed=False):
+ """
+ Write a PNG image to the output file.
+
+ Most users are expected to find the :meth:`write` or
+ :meth:`write_array` method more convenient.
+
+ The rows should be given to this method in the order that
+ they appear in the output file. For straightlaced images,
+ this is the usual top to bottom ordering, but for interlaced
+ images the rows should have already been interlaced before
+ passing them to this function.
+
+ `rows` should be an iterable that yields each row. When
+ `packed` is ``False`` the rows should be in boxed row flat pixel
+ format; when `packed` is ``True`` each row should be a packed
+ sequence of bytes.
+ """
+
+ # http://www.w3.org/TR/PNG/#5PNG-file-signature
+ outfile.write(_signature)
+
+ # http://www.w3.org/TR/PNG/#11IHDR
+ write_chunk(outfile, b'IHDR',
+ struct.pack("!2I5B", self.width, self.height,
+ self.bitdepth, self.color_type,
+ 0, 0, self.interlace))
+
+ # See :chunk:order
+ # http://www.w3.org/TR/PNG/#11gAMA
+ if self.gamma is not None:
+ write_chunk(outfile, b'gAMA',
+ struct.pack("!L", int(round(self.gamma*1e5))))
+
+ # See :chunk:order
+ # http://www.w3.org/TR/PNG/#11sBIT
+ if self.rescale:
+ write_chunk(outfile, b'sBIT',
+ struct.pack('%dB' % self.planes,
+ *[self.rescale[0]]*self.planes))
+
+ # :chunk:order: Without a palette (PLTE chunk), ordering is
+ # relatively relaxed. With one, gAMA chunk must precede PLTE
+ # chunk which must precede tRNS and bKGD.
+ # See http://www.w3.org/TR/PNG/#5ChunkOrdering
+ if self.palette:
+ p,t = self.make_palette()
+ write_chunk(outfile, b'PLTE', p)
+ if t:
+ # tRNS chunk is optional. Only needed if palette entries
+ # have alpha.
+ write_chunk(outfile, b'tRNS', t)
+
+ # http://www.w3.org/TR/PNG/#11tRNS
+ if self.transparent is not None:
+ if self.greyscale:
+ write_chunk(outfile, b'tRNS',
+ struct.pack("!1H", *self.transparent))
+ else:
+ write_chunk(outfile, b'tRNS',
+ struct.pack("!3H", *self.transparent))
+
+ # http://www.w3.org/TR/PNG/#11bKGD
+ if self.background is not None:
+ if self.greyscale:
+ write_chunk(outfile, b'bKGD',
+ struct.pack("!1H", *self.background))
+ else:
+ write_chunk(outfile, b'bKGD',
+ struct.pack("!3H", *self.background))
+
+ # http://www.w3.org/TR/PNG/#11pHYs
+ if self.x_pixels_per_unit is not None and self.y_pixels_per_unit is not None:
+ tup = (self.x_pixels_per_unit, self.y_pixels_per_unit, int(self.unit_is_meter))
+ write_chunk(outfile, b'pHYs', struct.pack("!LLB",*tup))
+
+ # http://www.w3.org/TR/PNG/#11IDAT
+ if self.compression is not None:
+ compressor = zlib.compressobj(self.compression)
+ else:
+ compressor = zlib.compressobj()
+
+ # Choose an extend function based on the bitdepth. The extend
+ # function packs/decomposes the pixel values into bytes and
+ # stuffs them onto the data array.
+ data = array('B')
+ if self.bitdepth == 8 or packed:
+ extend = data.extend
+ elif self.bitdepth == 16:
+ # Decompose into bytes
+ def extend(sl):
+ fmt = '!%dH' % len(sl)
+ data.extend(array('B', struct.pack(fmt, *sl)))
+ else:
+ # Pack into bytes
+ assert self.bitdepth < 8
+ # samples per byte
+ spb = int(8/self.bitdepth)
+ def extend(sl):
+ a = array('B', sl)
+ # Adding padding bytes so we can group into a whole
+ # number of spb-tuples.
+ l = float(len(a))
+ extra = math.ceil(l / float(spb))*spb - l
+ a.extend([0]*int(extra))
+ # Pack into bytes
+ l = group(a, spb)
+ l = [reduce(lambda x,y:
+ (x << self.bitdepth) + y, e) for e in l]
+ data.extend(l)
+ if self.rescale:
+ oldextend = extend
+ factor = \
+ float(2**self.rescale[1]-1) / float(2**self.rescale[0]-1)
+ def extend(sl):
+ oldextend([int(round(factor*x)) for x in sl])
+
+ # Build the first row, testing mostly to see if we need to
+ # changed the extend function to cope with NumPy integer types
+ # (they cause our ordinary definition of extend to fail, so we
+ # wrap it). See
+ # http://code.google.com/p/pypng/issues/detail?id=44
+ enumrows = enumerate(rows)
+ del rows
+
+ # First row's filter type.
+ data.append(0)
+ # :todo: Certain exceptions in the call to ``.next()`` or the
+ # following try would indicate no row data supplied.
+ # Should catch.
+ i,row = next(enumrows)
+ try:
+ # If this fails...
+ extend(row)
+ except:
+ # ... try a version that converts the values to int first.
+ # Not only does this work for the (slightly broken) NumPy
+ # types, there are probably lots of other, unknown, "nearly"
+ # int types it works for.
+ def wrapmapint(f):
+ return lambda sl: f([int(x) for x in sl])
+ extend = wrapmapint(extend)
+ del wrapmapint
+ extend(row)
+
+ for i,row in enumrows:
+ # Add "None" filter type. Currently, it's essential that
+ # this filter type be used for every scanline as we do not
+ # mark the first row of a reduced pass image; that means we
+ # could accidentally compute the wrong filtered scanline if
+ # we used "up", "average", or "paeth" on such a line.
+ data.append(0)
+ extend(row)
+ if len(data) > self.chunk_limit:
+ compressed = compressor.compress(tostring(data))
+ if len(compressed):
+ write_chunk(outfile, b'IDAT', compressed)
+ # Because of our very witty definition of ``extend``,
+ # above, we must re-use the same ``data`` object. Hence
+ # we use ``del`` to empty this one, rather than create a
+ # fresh one (which would be my natural FP instinct).
+ del data[:]
+ if len(data):
+ compressed = compressor.compress(tostring(data))
+ else:
+ compressed = b''
+ flushed = compressor.flush()
+ if len(compressed) or len(flushed):
+ write_chunk(outfile, b'IDAT', compressed + flushed)
+ # http://www.w3.org/TR/PNG/#11IEND
+ write_chunk(outfile, b'IEND')
+ return i+1
+
+ def write_array(self, outfile, pixels):
+ """
+ Write an array in flat row flat pixel format as a PNG file on
+ the output file. See also :meth:`write` method.
+ """
+
+ if self.interlace:
+ self.write_passes(outfile, self.array_scanlines_interlace(pixels))
+ else:
+ self.write_passes(outfile, self.array_scanlines(pixels))
+
+ def write_packed(self, outfile, rows):
+ """
+ Write PNG file to `outfile`. The pixel data comes from `rows`
+ which should be in boxed row packed format. Each row should be
+ a sequence of packed bytes.
+
+ Technically, this method does work for interlaced images but it
+ is best avoided. For interlaced images, the rows should be
+ presented in the order that they appear in the file.
+
+ This method should not be used when the source image bit depth
+ is not one naturally supported by PNG; the bit depth should be
+ 1, 2, 4, 8, or 16.
+ """
+
+ if self.rescale:
+ raise Error("write_packed method not suitable for bit depth %d" %
+ self.rescale[0])
+ return self.write_passes(outfile, rows, packed=True)
+
+ def convert_pnm(self, infile, outfile):
+ """
+ Convert a PNM file containing raw pixel data into a PNG file
+ with the parameters set in the writer object. Works for
+ (binary) PGM, PPM, and PAM formats.
+ """
+
+ if self.interlace:
+ pixels = array('B')
+ pixels.fromfile(infile,
+ (self.bitdepth/8) * self.color_planes *
+ self.width * self.height)
+ self.write_passes(outfile, self.array_scanlines_interlace(pixels))
+ else:
+ self.write_passes(outfile, self.file_scanlines(infile))
+
+ def convert_ppm_and_pgm(self, ppmfile, pgmfile, outfile):
+ """
+ Convert a PPM and PGM file containing raw pixel data into a
+ PNG outfile with the parameters set in the writer object.
+ """
+ pixels = array('B')
+ pixels.fromfile(ppmfile,
+ (self.bitdepth/8) * self.color_planes *
+ self.width * self.height)
+ apixels = array('B')
+ apixels.fromfile(pgmfile,
+ (self.bitdepth/8) *
+ self.width * self.height)
+ pixels = interleave_planes(pixels, apixels,
+ (self.bitdepth/8) * self.color_planes,
+ (self.bitdepth/8))
+ if self.interlace:
+ self.write_passes(outfile, self.array_scanlines_interlace(pixels))
+ else:
+ self.write_passes(outfile, self.array_scanlines(pixels))
+
+ def file_scanlines(self, infile):
+ """
+ Generates boxed rows in flat pixel format, from the input file
+ `infile`. It assumes that the input file is in a "Netpbm-like"
+ binary format, and is positioned at the beginning of the first
+ pixel. The number of pixels to read is taken from the image
+ dimensions (`width`, `height`, `planes`) and the number of bytes
+ per value is implied by the image `bitdepth`.
+ """
+
+ # Values per row
+ vpr = self.width * self.planes
+ row_bytes = vpr
+ if self.bitdepth > 8:
+ assert self.bitdepth == 16
+ row_bytes *= 2
+ fmt = '>%dH' % vpr
+ def line():
+ return array('H', struct.unpack(fmt, infile.read(row_bytes)))
+ else:
+ def line():
+ scanline = array('B', infile.read(row_bytes))
+ return scanline
+ for y in range(self.height):
+ yield line()
+
+ def array_scanlines(self, pixels):
+ """
+ Generates boxed rows (flat pixels) from flat rows (flat pixels)
+ in an array.
+ """
+
+ # Values per row
+ vpr = self.width * self.planes
+ stop = 0
+ for y in range(self.height):
+ start = stop
+ stop = start + vpr
+ yield pixels[start:stop]
+
+ def array_scanlines_interlace(self, pixels):
+ """
+ Generator for interlaced scanlines from an array. `pixels` is
+ the full source image in flat row flat pixel format. The
+ generator yields each scanline of the reduced passes in turn, in
+ boxed row flat pixel format.
+ """
+
+ # http://www.w3.org/TR/PNG/#8InterlaceMethods
+ # Array type.
+ fmt = 'BH'[self.bitdepth > 8]
+ # Value per row
+ vpr = self.width * self.planes
+ for xstart, ystart, xstep, ystep in _adam7:
+ if xstart >= self.width:
+ continue
+ # Pixels per row (of reduced image)
+ ppr = int(math.ceil((self.width-xstart)/float(xstep)))
+ # number of values in reduced image row.
+ row_len = ppr*self.planes
+ for y in range(ystart, self.height, ystep):
+ if xstep == 1:
+ offset = y * vpr
+ yield pixels[offset:offset+vpr]
+ else:
+ row = array(fmt)
+ # There's no easier way to set the length of an array
+ row.extend(pixels[0:row_len])
+ offset = y * vpr + xstart * self.planes
+ end_offset = (y+1) * vpr
+ skip = self.planes * xstep
+ for i in range(self.planes):
+ row[i::self.planes] = \
+ pixels[offset+i:end_offset:skip]
+ yield row
+
+def write_chunk(outfile, tag, data=b''):
+ """
+ Write a PNG chunk to the output file, including length and
+ checksum.
+ """
+
+ # http://www.w3.org/TR/PNG/#5Chunk-layout
+ outfile.write(struct.pack("!I", len(data)))
+ outfile.write(tag)
+ outfile.write(data)
+ checksum = zlib.crc32(tag)
+ checksum = zlib.crc32(data, checksum)
+ checksum &= 2**32-1
+ outfile.write(struct.pack("!I", checksum))
+
+def write_chunks(out, chunks):
+ """Create a PNG file by writing out the chunks."""
+
+ out.write(_signature)
+ for chunk in chunks:
+ write_chunk(out, *chunk)
+
+def filter_scanline(type, line, fo, prev=None):
+ """Apply a scanline filter to a scanline. `type` specifies the
+ filter type (0 to 4); `line` specifies the current (unfiltered)
+ scanline as a sequence of bytes; `prev` specifies the previous
+ (unfiltered) scanline as a sequence of bytes. `fo` specifies the
+ filter offset; normally this is size of a pixel in bytes (the number
+ of bytes per sample times the number of channels), but when this is
+ < 1 (for bit depths < 8) then the filter offset is 1.
+ """
+
+ assert 0 <= type < 5
+
+ # The output array. Which, pathetically, we extend one-byte at a
+ # time (fortunately this is linear).
+ out = array('B', [type])
+
+ def sub():
+ ai = -fo
+ for x in line:
+ if ai >= 0:
+ x = (x - line[ai]) & 0xff
+ out.append(x)
+ ai += 1
+ def up():
+ for i,x in enumerate(line):
+ x = (x - prev[i]) & 0xff
+ out.append(x)
+ def average():
+ ai = -fo
+ for i,x in enumerate(line):
+ if ai >= 0:
+ x = (x - ((line[ai] + prev[i]) >> 1)) & 0xff
+ else:
+ x = (x - (prev[i] >> 1)) & 0xff
+ out.append(x)
+ ai += 1
+ def paeth():
+ # http://www.w3.org/TR/PNG/#9Filter-type-4-Paeth
+ ai = -fo # also used for ci
+ for i,x in enumerate(line):
+ a = 0
+ b = prev[i]
+ c = 0
+
+ if ai >= 0:
+ a = line[ai]
+ c = prev[ai]
+ p = a + b - c
+ pa = abs(p - a)
+ pb = abs(p - b)
+ pc = abs(p - c)
+ if pa <= pb and pa <= pc:
+ Pr = a
+ elif pb <= pc:
+ Pr = b
+ else:
+ Pr = c
+
+ x = (x - Pr) & 0xff
+ out.append(x)
+ ai += 1
+
+ if not prev:
+ # We're on the first line. Some of the filters can be reduced
+ # to simpler cases which makes handling the line "off the top"
+ # of the image simpler. "up" becomes "none"; "paeth" becomes
+ # "left" (non-trivial, but true). "average" needs to be handled
+ # specially.
+ if type == 2: # "up"
+ type = 0
+ elif type == 3:
+ prev = [0]*len(line)
+ elif type == 4: # "paeth"
+ type = 1
+ if type == 0:
+ out.extend(line)
+ elif type == 1:
+ sub()
+ elif type == 2:
+ up()
+ elif type == 3:
+ average()
+ else: # type == 4
+ paeth()
+ return out
+
+
+# Regex for decoding mode string
+RegexModeDecode = re.compile("(LA?|RGBA?);?([0-9]*)", flags=re.IGNORECASE)
+
+def from_array(a, mode=None, info={}):
+ """Create a PNG :class:`Image` object from a 2- or 3-dimensional
+ array. One application of this function is easy PIL-style saving:
+ ``png.from_array(pixels, 'L').save('foo.png')``.
+
+ Unless they are specified using the *info* parameter, the PNG's
+ height and width are taken from the array size. For a 3 dimensional
+ array the first axis is the height; the second axis is the width;
+ and the third axis is the channel number. Thus an RGB image that is
+ 16 pixels high and 8 wide will use an array that is 16x8x3. For 2
+ dimensional arrays the first axis is the height, but the second axis
+ is ``width*channels``, so an RGB image that is 16 pixels high and 8
+ wide will use a 2-dimensional array that is 16x24 (each row will be
+ 8*3 = 24 sample values).
+
+ *mode* is a string that specifies the image colour format in a
+ PIL-style mode. It can be:
+
+ ``'L'``
+ greyscale (1 channel)
+ ``'LA'``
+ greyscale with alpha (2 channel)
+ ``'RGB'``
+ colour image (3 channel)
+ ``'RGBA'``
+ colour image with alpha (4 channel)
+
+ The mode string can also specify the bit depth (overriding how this
+ function normally derives the bit depth, see below). Appending
+ ``';16'`` to the mode will cause the PNG to be 16 bits per channel;
+ any decimal from 1 to 16 can be used to specify the bit depth.
+
+ When a 2-dimensional array is used *mode* determines how many
+ channels the image has, and so allows the width to be derived from
+ the second array dimension.
+
+ The array is expected to be a ``numpy`` array, but it can be any
+ suitable Python sequence. For example, a list of lists can be used:
+ ``png.from_array([[0, 255, 0], [255, 0, 255]], 'L')``. The exact
+ rules are: ``len(a)`` gives the first dimension, height;
+ ``len(a[0])`` gives the second dimension; ``len(a[0][0])`` gives the
+ third dimension, unless an exception is raised in which case a
+ 2-dimensional array is assumed. It's slightly more complicated than
+ that because an iterator of rows can be used, and it all still
+ works. Using an iterator allows data to be streamed efficiently.
+
+ The bit depth of the PNG is normally taken from the array element's
+ datatype (but if *mode* specifies a bitdepth then that is used
+ instead). The array element's datatype is determined in a way which
+ is supposed to work both for ``numpy`` arrays and for Python
+ ``array.array`` objects. A 1 byte datatype will give a bit depth of
+ 8, a 2 byte datatype will give a bit depth of 16. If the datatype
+ does not have an implicit size, for example it is a plain Python
+ list of lists, as above, then a default of 8 is used.
+
+ The *info* parameter is a dictionary that can be used to specify
+ metadata (in the same style as the arguments to the
+ :class:`png.Writer` class). For this function the keys that are
+ useful are:
+
+ height
+ overrides the height derived from the array dimensions and allows
+ *a* to be an iterable.
+ width
+ overrides the width derived from the array dimensions.
+ bitdepth
+ overrides the bit depth derived from the element datatype (but
+ must match *mode* if that also specifies a bit depth).
+
+ Generally anything specified in the
+ *info* dictionary will override any implicit choices that this
+ function would otherwise make, but must match any explicit ones.
+ For example, if the *info* dictionary has a ``greyscale`` key then
+ this must be true when mode is ``'L'`` or ``'LA'`` and false when
+ mode is ``'RGB'`` or ``'RGBA'``.
+ """
+
+ # We abuse the *info* parameter by modifying it. Take a copy here.
+ # (Also typechecks *info* to some extent).
+ info = dict(info)
+
+ # Syntax check mode string.
+ match = RegexModeDecode.match(mode)
+ if not match:
+ raise Error("mode string should be 'RGB' or 'L;16' or similar.")
+
+ mode, bitdepth = match.groups()
+ alpha = 'A' in mode
+ if bitdepth:
+ bitdepth = int(bitdepth)
+
+ # Colour format.
+ if 'greyscale' in info:
+ if bool(info['greyscale']) != ('L' in mode):
+ raise Error("info['greyscale'] should match mode.")
+ info['greyscale'] = 'L' in mode
+
+ if 'alpha' in info:
+ if bool(info['alpha']) != alpha:
+ raise Error("info['alpha'] should match mode.")
+ info['alpha'] = alpha
+
+ # Get bitdepth from *mode* if possible.
+ if bitdepth:
+ if info.get("bitdepth") and bitdepth != info['bitdepth']:
+ raise Error("bitdepth (%d) should match bitdepth of info (%d)." %
+ (bitdepth, info['bitdepth']))
+ info['bitdepth'] = bitdepth
+
+ # Fill in and/or check entries in *info*.
+ # Dimensions.
+ if 'size' in info:
+ assert len(info["size"]) == 2
+
+ # Check width, height, size all match where used.
+ for dimension,axis in [('width', 0), ('height', 1)]:
+ if dimension in info:
+ if info[dimension] != info['size'][axis]:
+ raise Error(
+ "info[%r] should match info['size'][%r]." %
+ (dimension, axis))
+ info['width'],info['height'] = info['size']
+
+ if 'height' not in info:
+ try:
+ info['height'] = len(a)
+ except TypeError:
+ raise Error("len(a) does not work, supply info['height'] instead.")
+
+ planes = len(mode)
+ if 'planes' in info:
+ if info['planes'] != planes:
+ raise Error("info['planes'] should match mode.")
+
+ # In order to work out whether we the array is 2D or 3D we need its
+ # first row, which requires that we take a copy of its iterator.
+ # We may also need the first row to derive width and bitdepth.
+ a,t = itertools.tee(a)
+ row = next(t)
+ del t
+ try:
+ row[0][0]
+ threed = True
+ testelement = row[0]
+ except (IndexError, TypeError):
+ threed = False
+ testelement = row
+ if 'width' not in info:
+ if threed:
+ width = len(row)
+ else:
+ width = len(row) // planes
+ info['width'] = width
+
+ if threed:
+ # Flatten the threed rows
+ a = (itertools.chain.from_iterable(x) for x in a)
+
+ if 'bitdepth' not in info:
+ try:
+ dtype = testelement.dtype
+ # goto the "else:" clause. Sorry.
+ except AttributeError:
+ try:
+ # Try a Python array.array.
+ bitdepth = 8 * testelement.itemsize
+ except AttributeError:
+ # We can't determine it from the array element's
+ # datatype, use a default of 8.
+ bitdepth = 8
+ else:
+ # If we got here without exception, we now assume that
+ # the array is a numpy array.
+ if dtype.kind == 'b':
+ bitdepth = 1
+ else:
+ bitdepth = 8 * dtype.itemsize
+ info['bitdepth'] = bitdepth
+
+ for thing in ["width", "height", "bitdepth", "greyscale", "alpha"]:
+ assert thing in info
+
+ return Image(a, info)
+
+# So that refugee's from PIL feel more at home. Not documented.
+fromarray = from_array
+
+class Image:
+ """A PNG image. You can create an :class:`Image` object from
+ an array of pixels by calling :meth:`png.from_array`. It can be
+ saved to disk with the :meth:`save` method.
+ """
+
+ def __init__(self, rows, info):
+ """
+ .. note ::
+
+ The constructor is not public. Please do not call it.
+ """
+
+ self.rows = rows
+ self.info = info
+
+ def save(self, file):
+ """Save the image to *file*. If *file* looks like an open file
+ descriptor then it is used, otherwise it is treated as a
+ filename and a fresh file is opened.
+
+ In general, you can only call this method once; after it has
+ been called the first time and the PNG image has been saved, the
+ source data will have been streamed, and cannot be streamed
+ again.
+ """
+
+ w = Writer(**self.info)
+
+ try:
+ file.write
+ def close(): pass
+ except AttributeError:
+ file = open(file, 'wb')
+ def close(): file.close()
+
+ try:
+ w.write(file, self.rows)
+ finally:
+ close()
+
+class _readable:
+ """
+ A simple file-like interface for strings and arrays.
+ """
+
+ def __init__(self, buf):
+ self.buf = buf
+ self.offset = 0
+
+ def read(self, n):
+ r = self.buf[self.offset:self.offset+n]
+ if isarray(r):
+ r = r.tostring()
+ self.offset += n
+ return r
+
+try:
+ str(b'dummy', 'ascii')
+except TypeError:
+ as_str = str
+else:
+ def as_str(x):
+ return str(x, 'ascii')
+
+class Reader:
+ """
+ PNG decoder in pure Python.
+ """
+
+ def __init__(self, _guess=None, **kw):
+ """
+ Create a PNG decoder object.
+
+ The constructor expects exactly one keyword argument. If you
+ supply a positional argument instead, it will guess the input
+ type. You can choose among the following keyword arguments:
+
+ filename
+ Name of input file (a PNG file).
+ file
+ A file-like object (object with a read() method).
+ bytes
+ ``array`` or ``string`` with PNG data.
+
+ """
+ if ((_guess is not None and len(kw) != 0) or
+ (_guess is None and len(kw) != 1)):
+ raise TypeError("Reader() takes exactly 1 argument")
+
+ # Will be the first 8 bytes, later on. See validate_signature.
+ self.signature = None
+ self.transparent = None
+ # A pair of (len,type) if a chunk has been read but its data and
+ # checksum have not (in other words the file position is just
+ # past the 4 bytes that specify the chunk type). See preamble
+ # method for how this is used.
+ self.atchunk = None
+
+ if _guess is not None:
+ if isarray(_guess):
+ kw["bytes"] = _guess
+ elif isinstance(_guess, str):
+ kw["filename"] = _guess
+ elif hasattr(_guess, 'read'):
+ kw["file"] = _guess
+
+ if "filename" in kw:
+ self.file = open(kw["filename"], "rb")
+ elif "file" in kw:
+ self.file = kw["file"]
+ elif "bytes" in kw:
+ self.file = _readable(kw["bytes"])
+ else:
+ raise TypeError("expecting filename, file or bytes array")
+
+
+ def chunk(self, seek=None, lenient=False):
+ """
+ Read the next PNG chunk from the input file; returns a
+ (*type*, *data*) tuple. *type* is the chunk's type as a
+ byte string (all PNG chunk types are 4 bytes long).
+ *data* is the chunk's data content, as a byte string.
+
+ If the optional `seek` argument is
+ specified then it will keep reading chunks until it either runs
+ out of file or finds the type specified by the argument. Note
+ that in general the order of chunks in PNGs is unspecified, so
+ using `seek` can cause you to miss chunks.
+
+ If the optional `lenient` argument evaluates to `True`,
+ checksum failures will raise warnings rather than exceptions.
+ """
+
+ self.validate_signature()
+
+ while True:
+ # http://www.w3.org/TR/PNG/#5Chunk-layout
+ if not self.atchunk:
+ self.atchunk = self.chunklentype()
+ length, type = self.atchunk
+ self.atchunk = None
+ data = self.file.read(length)
+ if len(data) != length:
+ raise ChunkError('Chunk %s too short for required %i octets.'
+ % (type, length))
+ checksum = self.file.read(4)
+ if len(checksum) != 4:
+ raise ChunkError('Chunk %s too short for checksum.' % type)
+ if seek and type != seek:
+ continue
+ verify = zlib.crc32(type)
+ verify = zlib.crc32(data, verify)
+ # Whether the output from zlib.crc32 is signed or not varies
+ # according to hideous implementation details, see
+ # http://bugs.python.org/issue1202 .
+ # We coerce it to be positive here (in a way which works on
+ # Python 2.3 and older).
+ verify &= 2**32 - 1
+ verify = struct.pack('!I', verify)
+ if checksum != verify:
+ (a, ) = struct.unpack('!I', checksum)
+ (b, ) = struct.unpack('!I', verify)
+ message = "Checksum error in %s chunk: 0x%08X != 0x%08X." % (type, a, b)
+ if lenient:
+ warnings.warn(message, RuntimeWarning)
+ else:
+ raise ChunkError(message)
+ return type, data
+
+ def chunks(self):
+ """Return an iterator that will yield each chunk as a
+ (*chunktype*, *content*) pair.
+ """
+
+ while True:
+ t,v = self.chunk()
+ yield t,v
+ if t == b'IEND':
+ break
+
+ def undo_filter(self, filter_type, scanline, previous):
+ """Undo the filter for a scanline. `scanline` is a sequence of
+ bytes that does not include the initial filter type byte.
+ `previous` is decoded previous scanline (for straightlaced
+ images this is the previous pixel row, but for interlaced
+ images, it is the previous scanline in the reduced image, which
+ in general is not the previous pixel row in the final image).
+ When there is no previous scanline (the first row of a
+ straightlaced image, or the first row in one of the passes in an
+ interlaced image), then this argument should be ``None``.
+
+ The scanline will have the effects of filtering removed, and the
+ result will be returned as a fresh sequence of bytes.
+ """
+
+ # :todo: Would it be better to update scanline in place?
+ # Yes, with the Cython extension making the undo_filter fast,
+ # updating scanline inplace makes the code 3 times faster
+ # (reading 50 images of 800x800 went from 40s to 16s)
+ result = scanline
+
+ if filter_type == 0:
+ return result
+
+ if filter_type not in (1,2,3,4):
+ raise FormatError('Invalid PNG Filter Type.'
+ ' See http://www.w3.org/TR/2003/REC-PNG-20031110/#9Filters .')
+
+ # Filter unit. The stride from one pixel to the corresponding
+ # byte from the previous pixel. Normally this is the pixel
+ # size in bytes, but when this is smaller than 1, the previous
+ # byte is used instead.
+ fu = max(1, self.psize)
+
+ # For the first line of a pass, synthesize a dummy previous
+ # line. An alternative approach would be to observe that on the
+ # first line 'up' is the same as 'null', 'paeth' is the same
+ # as 'sub', with only 'average' requiring any special case.
+ if not previous:
+ previous = array('B', [0]*len(scanline))
+
+ def sub():
+ """Undo sub filter."""
+
+ ai = 0
+ # Loop starts at index fu. Observe that the initial part
+ # of the result is already filled in correctly with
+ # scanline.
+ for i in range(fu, len(result)):
+ x = scanline[i]
+ a = result[ai]
+ result[i] = (x + a) & 0xff
+ ai += 1
+
+ def up():
+ """Undo up filter."""
+
+ for i in range(len(result)):
+ x = scanline[i]
+ b = previous[i]
+ result[i] = (x + b) & 0xff
+
+ def average():
+ """Undo average filter."""
+
+ ai = -fu
+ for i in range(len(result)):
+ x = scanline[i]
+ if ai < 0:
+ a = 0
+ else:
+ a = result[ai]
+ b = previous[i]
+ result[i] = (x + ((a + b) >> 1)) & 0xff
+ ai += 1
+
+ def paeth():
+ """Undo Paeth filter."""
+
+ # Also used for ci.
+ ai = -fu
+ for i in range(len(result)):
+ x = scanline[i]
+ if ai < 0:
+ a = c = 0
+ else:
+ a = result[ai]
+ c = previous[ai]
+ b = previous[i]
+ p = a + b - c
+ pa = abs(p - a)
+ pb = abs(p - b)
+ pc = abs(p - c)
+ if pa <= pb and pa <= pc:
+ pr = a
+ elif pb <= pc:
+ pr = b
+ else:
+ pr = c
+ result[i] = (x + pr) & 0xff
+ ai += 1
+
+ # Call appropriate filter algorithm. Note that 0 has already
+ # been dealt with.
+ (None,
+ pngfilters.undo_filter_sub,
+ pngfilters.undo_filter_up,
+ pngfilters.undo_filter_average,
+ pngfilters.undo_filter_paeth)[filter_type](fu, scanline, previous, result)
+ return result
+
+ def deinterlace(self, raw):
+ """
+ Read raw pixel data, undo filters, deinterlace, and flatten.
+ Return in flat row flat pixel format.
+ """
+
+ # Values per row (of the target image)
+ vpr = self.width * self.planes
+
+ # Make a result array, and make it big enough. Interleaving
+ # writes to the output array randomly (well, not quite), so the
+ # entire output array must be in memory.
+ fmt = 'BH'[self.bitdepth > 8]
+ a = array(fmt, [0]*vpr*self.height)
+ source_offset = 0
+
+ for xstart, ystart, xstep, ystep in _adam7:
+ if xstart >= self.width:
+ continue
+ # The previous (reconstructed) scanline. None at the
+ # beginning of a pass to indicate that there is no previous
+ # line.
+ recon = None
+ # Pixels per row (reduced pass image)
+ ppr = int(math.ceil((self.width-xstart)/float(xstep)))
+ # Row size in bytes for this pass.
+ row_size = int(math.ceil(self.psize * ppr))
+ for y in range(ystart, self.height, ystep):
+ filter_type = raw[source_offset]
+ source_offset += 1
+ scanline = raw[source_offset:source_offset+row_size]
+ source_offset += row_size
+ recon = self.undo_filter(filter_type, scanline, recon)
+ # Convert so that there is one element per pixel value
+ flat = self.serialtoflat(recon, ppr)
+ if xstep == 1:
+ assert xstart == 0
+ offset = y * vpr
+ a[offset:offset+vpr] = flat
+ else:
+ offset = y * vpr + xstart * self.planes
+ end_offset = (y+1) * vpr
+ skip = self.planes * xstep
+ for i in range(self.planes):
+ a[offset+i:end_offset:skip] = \
+ flat[i::self.planes]
+ return a
+
+ def iterboxed(self, rows):
+ """Iterator that yields each scanline in boxed row flat pixel
+ format. `rows` should be an iterator that yields the bytes of
+ each row in turn.
+ """
+
+ def asvalues(raw):
+ """Convert a row of raw bytes into a flat row. Result will
+ be a freshly allocated object, not shared with
+ argument.
+ """
+
+ if self.bitdepth == 8:
+ return array('B', raw)
+ if self.bitdepth == 16:
+ raw = tostring(raw)
+ return array('H', struct.unpack('!%dH' % (len(raw)//2), raw))
+ assert self.bitdepth < 8
+ width = self.width
+ # Samples per byte
+ spb = 8//self.bitdepth
+ out = array('B')
+ mask = 2**self.bitdepth - 1
+ shifts = [self.bitdepth * i
+ for i in reversed(list(range(spb)))]
+ for o in raw:
+ out.extend([mask&(o>>i) for i in shifts])
+ return out[:width]
+
+ return map(asvalues, rows)
+
+ def serialtoflat(self, bytes, width=None):
+ """Convert serial format (byte stream) pixel data to flat row
+ flat pixel.
+ """
+
+ if self.bitdepth == 8:
+ return bytes
+ if self.bitdepth == 16:
+ bytes = tostring(bytes)
+ return array('H',
+ struct.unpack('!%dH' % (len(bytes)//2), bytes))
+ assert self.bitdepth < 8
+ if width is None:
+ width = self.width
+ # Samples per byte
+ spb = 8//self.bitdepth
+ out = array('B')
+ mask = 2**self.bitdepth - 1
+ shifts = list(map(self.bitdepth.__mul__, reversed(list(range(spb)))))
+ l = width
+ for o in bytes:
+ out.extend([(mask&(o>>s)) for s in shifts][:l])
+ l -= spb
+ if l <= 0:
+ l = width
+ return out
+
+ def iterstraight(self, raw):
+ """Iterator that undoes the effect of filtering, and yields
+ each row in serialised format (as a sequence of bytes).
+ Assumes input is straightlaced. `raw` should be an iterable
+ that yields the raw bytes in chunks of arbitrary size.
+ """
+
+ # length of row, in bytes
+ rb = self.row_bytes
+ a = array('B')
+ # The previous (reconstructed) scanline. None indicates first
+ # line of image.
+ recon = None
+ for some in raw:
+ a.extend(some)
+ while len(a) >= rb + 1:
+ filter_type = a[0]
+ scanline = a[1:rb+1]
+ del a[:rb+1]
+ recon = self.undo_filter(filter_type, scanline, recon)
+ yield recon
+ if len(a) != 0:
+ # :file:format We get here with a file format error:
+ # when the available bytes (after decompressing) do not
+ # pack into exact rows.
+ raise FormatError(
+ 'Wrong size for decompressed IDAT chunk.')
+ assert len(a) == 0
+
+ def validate_signature(self):
+ """If signature (header) has not been read then read and
+ validate it; otherwise do nothing.
+ """
+
+ if self.signature:
+ return
+ self.signature = self.file.read(8)
+ if self.signature != _signature:
+ raise FormatError("PNG file has invalid signature.")
+
+ def preamble(self, lenient=False):
+ """
+ Extract the image metadata by reading the initial part of
+ the PNG file up to the start of the ``IDAT`` chunk. All the
+ chunks that precede the ``IDAT`` chunk are read and either
+ processed for metadata or discarded.
+
+ If the optional `lenient` argument evaluates to `True`, checksum
+ failures will raise warnings rather than exceptions.
+ """
+
+ self.validate_signature()
+
+ while True:
+ if not self.atchunk:
+ self.atchunk = self.chunklentype()
+ if self.atchunk is None:
+ raise FormatError(
+ 'This PNG file has no IDAT chunks.')
+ if self.atchunk[1] == b'IDAT':
+ return
+ self.process_chunk(lenient=lenient)
+
+ def chunklentype(self):
+ """Reads just enough of the input to determine the next
+ chunk's length and type, returned as a (*length*, *type*) pair
+ where *type* is a string. If there are no more chunks, ``None``
+ is returned.
+ """
+
+ x = self.file.read(8)
+ if not x:
+ return None
+ if len(x) != 8:
+ raise FormatError(
+ 'End of file whilst reading chunk length and type.')
+ length,type = struct.unpack('!I4s', x)
+ if length > 2**31-1:
+ raise FormatError('Chunk %s is too large: %d.' % (type,length))
+ return length,type
+
+ def process_chunk(self, lenient=False):
+ """Process the next chunk and its data. This only processes the
+ following chunk types, all others are ignored: ``IHDR``,
+ ``PLTE``, ``bKGD``, ``tRNS``, ``gAMA``, ``sBIT``, ``pHYs``.
+
+ If the optional `lenient` argument evaluates to `True`,
+ checksum failures will raise warnings rather than exceptions.
+ """
+
+ type, data = self.chunk(lenient=lenient)
+ method = '_process_' + as_str(type)
+ m = getattr(self, method, None)
+ if m:
+ m(data)
+
+ def _process_IHDR(self, data):
+ # http://www.w3.org/TR/PNG/#11IHDR
+ if len(data) != 13:
+ raise FormatError('IHDR chunk has incorrect length.')
+ (self.width, self.height, self.bitdepth, self.color_type,
+ self.compression, self.filter,
+ self.interlace) = struct.unpack("!2I5B", data)
+
+ check_bitdepth_colortype(self.bitdepth, self.color_type)
+
+ if self.compression != 0:
+ raise Error("unknown compression method %d" % self.compression)
+ if self.filter != 0:
+ raise FormatError("Unknown filter method %d,"
+ " see http://www.w3.org/TR/2003/REC-PNG-20031110/#9Filters ."
+ % self.filter)
+ if self.interlace not in (0,1):
+ raise FormatError("Unknown interlace method %d,"
+ " see http://www.w3.org/TR/2003/REC-PNG-20031110/#8InterlaceMethods ."
+ % self.interlace)
+
+ # Derived values
+ # http://www.w3.org/TR/PNG/#6Colour-values
+ colormap = bool(self.color_type & 1)
+ greyscale = not (self.color_type & 2)
+ alpha = bool(self.color_type & 4)
+ color_planes = (3,1)[greyscale or colormap]
+ planes = color_planes + alpha
+
+ self.colormap = colormap
+ self.greyscale = greyscale
+ self.alpha = alpha
+ self.color_planes = color_planes
+ self.planes = planes
+ self.psize = float(self.bitdepth)/float(8) * planes
+ if int(self.psize) == self.psize:
+ self.psize = int(self.psize)
+ self.row_bytes = int(math.ceil(self.width * self.psize))
+ # Stores PLTE chunk if present, and is used to check
+ # chunk ordering constraints.
+ self.plte = None
+ # Stores tRNS chunk if present, and is used to check chunk
+ # ordering constraints.
+ self.trns = None
+ # Stores sbit chunk if present.
+ self.sbit = None
+
+ def _process_PLTE(self, data):
+ # http://www.w3.org/TR/PNG/#11PLTE
+ if self.plte:
+ warnings.warn("Multiple PLTE chunks present.")
+ self.plte = data
+ if len(data) % 3 != 0:
+ raise FormatError(
+ "PLTE chunk's length should be a multiple of 3.")
+ if len(data) > (2**self.bitdepth)*3:
+ raise FormatError("PLTE chunk is too long.")
+ if len(data) == 0:
+ raise FormatError("Empty PLTE is not allowed.")
+
+ def _process_bKGD(self, data):
+ try:
+ if self.colormap:
+ if not self.plte:
+ warnings.warn(
+ "PLTE chunk is required before bKGD chunk.")
+ self.background = struct.unpack('B', data)
+ else:
+ self.background = struct.unpack("!%dH" % self.color_planes,
+ data)
+ except struct.error:
+ raise FormatError("bKGD chunk has incorrect length.")
+
+ def _process_tRNS(self, data):
+ # http://www.w3.org/TR/PNG/#11tRNS
+ self.trns = data
+ if self.colormap:
+ if not self.plte:
+ warnings.warn("PLTE chunk is required before tRNS chunk.")
+ else:
+ if len(data) > len(self.plte)/3:
+ # Was warning, but promoted to Error as it
+ # would otherwise cause pain later on.
+ raise FormatError("tRNS chunk is too long.")
+ else:
+ if self.alpha:
+ raise FormatError(
+ "tRNS chunk is not valid with colour type %d." %
+ self.color_type)
+ try:
+ self.transparent = \
+ struct.unpack("!%dH" % self.color_planes, data)
+ except struct.error:
+ raise FormatError("tRNS chunk has incorrect length.")
+
+ def _process_gAMA(self, data):
+ try:
+ self.gamma = struct.unpack("!L", data)[0] / 100000.0
+ except struct.error:
+ raise FormatError("gAMA chunk has incorrect length.")
+
+ def _process_sBIT(self, data):
+ self.sbit = data
+ if (self.colormap and len(data) != 3 or
+ not self.colormap and len(data) != self.planes):
+ raise FormatError("sBIT chunk has incorrect length.")
+
+ def _process_pHYs(self, data):
+ # http://www.w3.org/TR/PNG/#11pHYs
+ self.phys = data
+ fmt = "!LLB"
+ if len(data) != struct.calcsize(fmt):
+ raise FormatError("pHYs chunk has incorrect length.")
+ self.x_pixels_per_unit, self.y_pixels_per_unit, unit = struct.unpack(fmt,data)
+ self.unit_is_meter = bool(unit)
+
+ def read(self, lenient=False):
+ """
+ Read the PNG file and decode it. Returns (`width`, `height`,
+ `pixels`, `metadata`).
+
+ May use excessive memory.
+
+ `pixels` are returned in boxed row flat pixel format.
+
+ If the optional `lenient` argument evaluates to True,
+ checksum failures will raise warnings rather than exceptions.
+ """
+
+ def iteridat():
+ """Iterator that yields all the ``IDAT`` chunks as strings."""
+ while True:
+ try:
+ type, data = self.chunk(lenient=lenient)
+ except ValueError as e:
+ raise ChunkError(e.args[0])
+ if type == b'IEND':
+ # http://www.w3.org/TR/PNG/#11IEND
+ break
+ if type != b'IDAT':
+ continue
+ # type == b'IDAT'
+ # http://www.w3.org/TR/PNG/#11IDAT
+ if self.colormap and not self.plte:
+ warnings.warn("PLTE chunk is required before IDAT chunk")
+ yield data
+
+ def iterdecomp(idat):
+ """Iterator that yields decompressed strings. `idat` should
+ be an iterator that yields the ``IDAT`` chunk data.
+ """
+
+ # Currently, with no max_length parameter to decompress,
+ # this routine will do one yield per IDAT chunk: Not very
+ # incremental.
+ d = zlib.decompressobj()
+ # Each IDAT chunk is passed to the decompressor, then any
+ # remaining state is decompressed out.
+ for data in idat:
+ # :todo: add a max_length argument here to limit output
+ # size.
+ yield array('B', d.decompress(data))
+ yield array('B', d.flush())
+
+ self.preamble(lenient=lenient)
+ raw = iterdecomp(iteridat())
+
+ if self.interlace:
+ raw = array('B', itertools.chain(*raw))
+ arraycode = 'BH'[self.bitdepth>8]
+ # Like :meth:`group` but producing an array.array object for
+ # each row.
+ pixels = map(lambda *row: array(arraycode, row),
+ *[iter(self.deinterlace(raw))]*self.width*self.planes)
+ else:
+ pixels = self.iterboxed(self.iterstraight(raw))
+ meta = dict()
+ for attr in 'greyscale alpha planes bitdepth interlace'.split():
+ meta[attr] = getattr(self, attr)
+ meta['size'] = (self.width, self.height)
+ for attr in 'gamma transparent background'.split():
+ a = getattr(self, attr, None)
+ if a is not None:
+ meta[attr] = a
+ if self.plte:
+ meta['palette'] = self.palette()
+ return self.width, self.height, pixels, meta
+
+
+ def read_flat(self):
+ """
+ Read a PNG file and decode it into flat row flat pixel format.
+ Returns (*width*, *height*, *pixels*, *metadata*).
+
+ May use excessive memory.
+
+ `pixels` are returned in flat row flat pixel format.
+
+ See also the :meth:`read` method which returns pixels in the
+ more stream-friendly boxed row flat pixel format.
+ """
+
+ x, y, pixel, meta = self.read()
+ arraycode = 'BH'[meta['bitdepth']>8]
+ pixel = array(arraycode, itertools.chain(*pixel))
+ return x, y, pixel, meta
+
+ def palette(self, alpha='natural'):
+ """Returns a palette that is a sequence of 3-tuples or 4-tuples,
+ synthesizing it from the ``PLTE`` and ``tRNS`` chunks. These
+ chunks should have already been processed (for example, by
+ calling the :meth:`preamble` method). All the tuples are the
+ same size: 3-tuples if there is no ``tRNS`` chunk, 4-tuples when
+ there is a ``tRNS`` chunk. Assumes that the image is colour type
+ 3 and therefore a ``PLTE`` chunk is required.
+
+ If the `alpha` argument is ``'force'`` then an alpha channel is
+ always added, forcing the result to be a sequence of 4-tuples.
+ """
+
+ if not self.plte:
+ raise FormatError(
+ "Required PLTE chunk is missing in colour type 3 image.")
+ plte = group(array('B', self.plte), 3)
+ if self.trns or alpha == 'force':
+ trns = array('B', self.trns or [])
+ trns.extend([255]*(len(plte)-len(trns)))
+ plte = list(map(operator.add, plte, group(trns, 1)))
+ return plte
+
+ def asDirect(self):
+ """Returns the image data as a direct representation of an
+ ``x * y * planes`` array. This method is intended to remove the
+ need for callers to deal with palettes and transparency
+ themselves. Images with a palette (colour type 3)
+ are converted to RGB or RGBA; images with transparency (a
+ ``tRNS`` chunk) are converted to LA or RGBA as appropriate.
+ When returned in this format the pixel values represent the
+ colour value directly without needing to refer to palettes or
+ transparency information.
+
+ Like the :meth:`read` method this method returns a 4-tuple:
+
+ (*width*, *height*, *pixels*, *meta*)
+
+ This method normally returns pixel values with the bit depth
+ they have in the source image, but when the source PNG has an
+ ``sBIT`` chunk it is inspected and can reduce the bit depth of
+ the result pixels; pixel values will be reduced according to
+ the bit depth specified in the ``sBIT`` chunk (PNG nerds should
+ note a single result bit depth is used for all channels; the
+ maximum of the ones specified in the ``sBIT`` chunk. An RGB565
+ image will be rescaled to 6-bit RGB666).
+
+ The *meta* dictionary that is returned reflects the `direct`
+ format and not the original source image. For example, an RGB
+ source image with a ``tRNS`` chunk to represent a transparent
+ colour, will have ``planes=3`` and ``alpha=False`` for the
+ source image, but the *meta* dictionary returned by this method
+ will have ``planes=4`` and ``alpha=True`` because an alpha
+ channel is synthesized and added.
+
+ *pixels* is the pixel data in boxed row flat pixel format (just
+ like the :meth:`read` method).
+
+ All the other aspects of the image data are not changed.
+ """
+
+ self.preamble()
+
+ # Simple case, no conversion necessary.
+ if not self.colormap and not self.trns and not self.sbit:
+ return self.read()
+
+ x,y,pixels,meta = self.read()
+
+ if self.colormap:
+ meta['colormap'] = False
+ meta['alpha'] = bool(self.trns)
+ meta['bitdepth'] = 8
+ meta['planes'] = 3 + bool(self.trns)
+ plte = self.palette()
+ def iterpal(pixels):
+ for row in pixels:
+ row = [plte[x] for x in row]
+ yield array('B', itertools.chain(*row))
+ pixels = iterpal(pixels)
+ elif self.trns:
+ # It would be nice if there was some reasonable way
+ # of doing this without generating a whole load of
+ # intermediate tuples. But tuples does seem like the
+ # easiest way, with no other way clearly much simpler or
+ # much faster. (Actually, the L to LA conversion could
+ # perhaps go faster (all those 1-tuples!), but I still
+ # wonder whether the code proliferation is worth it)
+ it = self.transparent
+ maxval = 2**meta['bitdepth']-1
+ planes = meta['planes']
+ meta['alpha'] = True
+ meta['planes'] += 1
+ typecode = 'BH'[meta['bitdepth']>8]
+ def itertrns(pixels):
+ for row in pixels:
+ # For each row we group it into pixels, then form a
+ # characterisation vector that says whether each
+ # pixel is opaque or not. Then we convert
+ # True/False to 0/maxval (by multiplication),
+ # and add it as the extra channel.
+ row = group(row, planes)
+ opa = map(it.__ne__, row)
+ opa = map(maxval.__mul__, opa)
+ opa = list(zip(opa)) # convert to 1-tuples
+ yield array(typecode,
+ itertools.chain(*map(operator.add, row, opa)))
+ pixels = itertrns(pixels)
+ targetbitdepth = None
+ if self.sbit:
+ sbit = struct.unpack('%dB' % len(self.sbit), self.sbit)
+ targetbitdepth = max(sbit)
+ if targetbitdepth > meta['bitdepth']:
+ raise Error('sBIT chunk %r exceeds bitdepth %d' %
+ (sbit,self.bitdepth))
+ if min(sbit) <= 0:
+ raise Error('sBIT chunk %r has a 0-entry' % sbit)
+ if targetbitdepth == meta['bitdepth']:
+ targetbitdepth = None
+ if targetbitdepth:
+ shift = meta['bitdepth'] - targetbitdepth
+ meta['bitdepth'] = targetbitdepth
+ def itershift(pixels):
+ for row in pixels:
+ yield [p >> shift for p in row]
+ pixels = itershift(pixels)
+ return x,y,pixels,meta
+
+ def asFloat(self, maxval=1.0):
+ """Return image pixels as per :meth:`asDirect` method, but scale
+ all pixel values to be floating point values between 0.0 and
+ *maxval*.
+ """
+
+ x,y,pixels,info = self.asDirect()
+ sourcemaxval = 2**info['bitdepth']-1
+ del info['bitdepth']
+ info['maxval'] = float(maxval)
+ factor = float(maxval)/float(sourcemaxval)
+ def iterfloat():
+ for row in pixels:
+ yield [factor * p for p in row]
+ return x,y,iterfloat(),info
+
+ def _as_rescale(self, get, targetbitdepth):
+ """Helper used by :meth:`asRGB8` and :meth:`asRGBA8`."""
+
+ width,height,pixels,meta = get()
+ maxval = 2**meta['bitdepth'] - 1
+ targetmaxval = 2**targetbitdepth - 1
+ factor = float(targetmaxval) / float(maxval)
+ meta['bitdepth'] = targetbitdepth
+ def iterscale():
+ for row in pixels:
+ yield [int(round(x*factor)) for x in row]
+ if maxval == targetmaxval:
+ return width, height, pixels, meta
+ else:
+ return width, height, iterscale(), meta
+
+ def asRGB8(self):
+ """Return the image data as an RGB pixels with 8-bits per
+ sample. This is like the :meth:`asRGB` method except that
+ this method additionally rescales the values so that they
+ are all between 0 and 255 (8-bit). In the case where the
+ source image has a bit depth < 8 the transformation preserves
+ all the information; where the source image has bit depth
+ > 8, then rescaling to 8-bit values loses precision. No
+ dithering is performed. Like :meth:`asRGB`, an alpha channel
+ in the source image will raise an exception.
+
+ This function returns a 4-tuple:
+ (*width*, *height*, *pixels*, *metadata*).
+ *width*, *height*, *metadata* are as per the
+ :meth:`read` method.
+
+ *pixels* is the pixel data in boxed row flat pixel format.
+ """
+
+ return self._as_rescale(self.asRGB, 8)
+
+ def asRGBA8(self):
+ """Return the image data as RGBA pixels with 8-bits per
+ sample. This method is similar to :meth:`asRGB8` and
+ :meth:`asRGBA`: The result pixels have an alpha channel, *and*
+ values are rescaled to the range 0 to 255. The alpha channel is
+ synthesized if necessary (with a small speed penalty).
+ """
+
+ return self._as_rescale(self.asRGBA, 8)
+
+ def asRGB(self):
+ """Return image as RGB pixels. RGB colour images are passed
+ through unchanged; greyscales are expanded into RGB
+ triplets (there is a small speed overhead for doing this).
+
+ An alpha channel in the source image will raise an
+ exception.
+
+ The return values are as for the :meth:`read` method
+ except that the *metadata* reflect the returned pixels, not the
+ source image. In particular, for this method
+ ``metadata['greyscale']`` will be ``False``.
+ """
+
+ width,height,pixels,meta = self.asDirect()
+ if meta['alpha']:
+ raise Error("will not convert image with alpha channel to RGB")
+ if not meta['greyscale']:
+ return width,height,pixels,meta
+ meta['greyscale'] = False
+ typecode = 'BH'[meta['bitdepth'] > 8]
+ def iterrgb():
+ for row in pixels:
+ a = array(typecode, [0]) * 3 * width
+ for i in range(3):
+ a[i::3] = row
+ yield a
+ return width,height,iterrgb(),meta
+
+ def asRGBA(self):
+ """Return image as RGBA pixels. Greyscales are expanded into
+ RGB triplets; an alpha channel is synthesized if necessary.
+ The return values are as for the :meth:`read` method
+ except that the *metadata* reflect the returned pixels, not the
+ source image. In particular, for this method
+ ``metadata['greyscale']`` will be ``False``, and
+ ``metadata['alpha']`` will be ``True``.
+ """
+
+ width,height,pixels,meta = self.asDirect()
+ if meta['alpha'] and not meta['greyscale']:
+ return width,height,pixels,meta
+ typecode = 'BH'[meta['bitdepth'] > 8]
+ maxval = 2**meta['bitdepth'] - 1
+ maxbuffer = struct.pack('=' + typecode, maxval) * 4 * width
+ def newarray():
+ return array(typecode, maxbuffer)
+
+ if meta['alpha'] and meta['greyscale']:
+ # LA to RGBA
+ def convert():
+ for row in pixels:
+ # Create a fresh target row, then copy L channel
+ # into first three target channels, and A channel
+ # into fourth channel.
+ a = newarray()
+ pngfilters.convert_la_to_rgba(row, a)
+ yield a
+ elif meta['greyscale']:
+ # L to RGBA
+ def convert():
+ for row in pixels:
+ a = newarray()
+ pngfilters.convert_l_to_rgba(row, a)
+ yield a
+ else:
+ assert not meta['alpha'] and not meta['greyscale']
+ # RGB to RGBA
+ def convert():
+ for row in pixels:
+ a = newarray()
+ pngfilters.convert_rgb_to_rgba(row, a)
+ yield a
+ meta['alpha'] = True
+ meta['greyscale'] = False
+ return width,height,convert(),meta
+
+def check_bitdepth_colortype(bitdepth, colortype):
+ """Check that `bitdepth` and `colortype` are both valid,
+ and specified in a valid combination. Returns if valid,
+ raise an Exception if not valid.
+ """
+
+ if bitdepth not in (1,2,4,8,16):
+ raise FormatError("invalid bit depth %d" % bitdepth)
+ if colortype not in (0,2,3,4,6):
+ raise FormatError("invalid colour type %d" % colortype)
+ # Check indexed (palettized) images have 8 or fewer bits
+ # per pixel; check only indexed or greyscale images have
+ # fewer than 8 bits per pixel.
+ if colortype & 1 and bitdepth > 8:
+ raise FormatError(
+ "Indexed images (colour type %d) cannot"
+ " have bitdepth > 8 (bit depth %d)."
+ " See http://www.w3.org/TR/2003/REC-PNG-20031110/#table111 ."
+ % (bitdepth, colortype))
+ if bitdepth < 8 and colortype not in (0,3):
+ raise FormatError("Illegal combination of bit depth (%d)"
+ " and colour type (%d)."
+ " See http://www.w3.org/TR/2003/REC-PNG-20031110/#table111 ."
+ % (bitdepth, colortype))
+
+def isinteger(x):
+ try:
+ return int(x) == x
+ except (TypeError, ValueError):
+ return False
+
+
+# === Support for users without Cython ===
+
+try:
+ pngfilters
+except NameError:
+ class pngfilters(object):
+ def undo_filter_sub(filter_unit, scanline, previous, result):
+ """Undo sub filter."""
+
+ ai = 0
+ # Loops starts at index fu. Observe that the initial part
+ # of the result is already filled in correctly with
+ # scanline.
+ for i in range(filter_unit, len(result)):
+ x = scanline[i]
+ a = result[ai]
+ result[i] = (x + a) & 0xff
+ ai += 1
+ undo_filter_sub = staticmethod(undo_filter_sub)
+
+ def undo_filter_up(filter_unit, scanline, previous, result):
+ """Undo up filter."""
+
+ for i in range(len(result)):
+ x = scanline[i]
+ b = previous[i]
+ result[i] = (x + b) & 0xff
+ undo_filter_up = staticmethod(undo_filter_up)
+
+ def undo_filter_average(filter_unit, scanline, previous, result):
+ """Undo up filter."""
+
+ ai = -filter_unit
+ for i in range(len(result)):
+ x = scanline[i]
+ if ai < 0:
+ a = 0
+ else:
+ a = result[ai]
+ b = previous[i]
+ result[i] = (x + ((a + b) >> 1)) & 0xff
+ ai += 1
+ undo_filter_average = staticmethod(undo_filter_average)
+
+ def undo_filter_paeth(filter_unit, scanline, previous, result):
+ """Undo Paeth filter."""
+
+ # Also used for ci.
+ ai = -filter_unit
+ for i in range(len(result)):
+ x = scanline[i]
+ if ai < 0:
+ a = c = 0
+ else:
+ a = result[ai]
+ c = previous[ai]
+ b = previous[i]
+ p = a + b - c
+ pa = abs(p - a)
+ pb = abs(p - b)
+ pc = abs(p - c)
+ if pa <= pb and pa <= pc:
+ pr = a
+ elif pb <= pc:
+ pr = b
+ else:
+ pr = c
+ result[i] = (x + pr) & 0xff
+ ai += 1
+ undo_filter_paeth = staticmethod(undo_filter_paeth)
+
+ def convert_la_to_rgba(row, result):
+ for i in range(3):
+ result[i::4] = row[0::2]
+ result[3::4] = row[1::2]
+ convert_la_to_rgba = staticmethod(convert_la_to_rgba)
+
+ def convert_l_to_rgba(row, result):
+ """Convert a grayscale image to RGBA. This method assumes
+ the alpha channel in result is already correctly
+ initialized.
+ """
+ for i in range(3):
+ result[i::4] = row
+ convert_l_to_rgba = staticmethod(convert_l_to_rgba)
+
+ def convert_rgb_to_rgba(row, result):
+ """Convert an RGB image to RGBA. This method assumes the
+ alpha channel in result is already correctly initialized.
+ """
+ for i in range(3):
+ result[i::4] = row[i::3]
+ convert_rgb_to_rgba = staticmethod(convert_rgb_to_rgba)
+
+
+# === Command Line Support ===
+
+def read_pam_header(infile):
+ """
+ Read (the rest of a) PAM header. `infile` should be positioned
+ immediately after the initial 'P7' line (at the beginning of the
+ second line). Returns are as for `read_pnm_header`.
+ """
+
+ # Unlike PBM, PGM, and PPM, we can read the header a line at a time.
+ header = dict()
+ while True:
+ l = infile.readline().strip()
+ if l == b'ENDHDR':
+ break
+ if not l:
+ raise EOFError('PAM ended prematurely')
+ if l[0] == b'#':
+ continue
+ l = l.split(None, 1)
+ if l[0] not in header:
+ header[l[0]] = l[1]
+ else:
+ header[l[0]] += b' ' + l[1]
+
+ required = [b'WIDTH', b'HEIGHT', b'DEPTH', b'MAXVAL']
+ WIDTH,HEIGHT,DEPTH,MAXVAL = required
+ present = [x for x in required if x in header]
+ if len(present) != len(required):
+ raise Error('PAM file must specify WIDTH, HEIGHT, DEPTH, and MAXVAL')
+ width = int(header[WIDTH])
+ height = int(header[HEIGHT])
+ depth = int(header[DEPTH])
+ maxval = int(header[MAXVAL])
+ if (width <= 0 or
+ height <= 0 or
+ depth <= 0 or
+ maxval <= 0):
+ raise Error(
+ 'WIDTH, HEIGHT, DEPTH, MAXVAL must all be positive integers')
+ return 'P7', width, height, depth, maxval
+
+def read_pnm_header(infile, supported=(b'P5', b'P6')):
+ """
+ Read a PNM header, returning (format,width,height,depth,maxval).
+ `width` and `height` are in pixels. `depth` is the number of
+ channels in the image; for PBM and PGM it is synthesized as 1, for
+ PPM as 3; for PAM images it is read from the header. `maxval` is
+ synthesized (as 1) for PBM images.
+ """
+
+ # Generally, see http://netpbm.sourceforge.net/doc/ppm.html
+ # and http://netpbm.sourceforge.net/doc/pam.html
+
+ # Technically 'P7' must be followed by a newline, so by using
+ # rstrip() we are being liberal in what we accept. I think this
+ # is acceptable.
+ type = infile.read(3).rstrip()
+ if type not in supported:
+ raise NotImplementedError('file format %s not supported' % type)
+ if type == b'P7':
+ # PAM header parsing is completely different.
+ return read_pam_header(infile)
+ # Expected number of tokens in header (3 for P4, 4 for P6)
+ expected = 4
+ pbm = (b'P1', b'P4')
+ if type in pbm:
+ expected = 3
+ header = [type]
+
+ # We have to read the rest of the header byte by byte because the
+ # final whitespace character (immediately following the MAXVAL in
+ # the case of P6) may not be a newline. Of course all PNM files in
+ # the wild use a newline at this point, so it's tempting to use
+ # readline; but it would be wrong.
+ def getc():
+ c = infile.read(1)
+ if not c:
+ raise Error('premature EOF reading PNM header')
+ return c
+
+ c = getc()
+ while True:
+ # Skip whitespace that precedes a token.
+ while c.isspace():
+ c = getc()
+ # Skip comments.
+ while c == '#':
+ while c not in b'\n\r':
+ c = getc()
+ if not c.isdigit():
+ raise Error('unexpected character %s found in header' % c)
+ # According to the specification it is legal to have comments
+ # that appear in the middle of a token.
+ # This is bonkers; I've never seen it; and it's a bit awkward to
+ # code good lexers in Python (no goto). So we break on such
+ # cases.
+ token = b''
+ while c.isdigit():
+ token += c
+ c = getc()
+ # Slight hack. All "tokens" are decimal integers, so convert
+ # them here.
+ header.append(int(token))
+ if len(header) == expected:
+ break
+ # Skip comments (again)
+ while c == '#':
+ while c not in '\n\r':
+ c = getc()
+ if not c.isspace():
+ raise Error('expected header to end with whitespace, not %s' % c)
+
+ if type in pbm:
+ # synthesize a MAXVAL
+ header.append(1)
+ depth = (1,3)[type == b'P6']
+ return header[0], header[1], header[2], depth, header[3]
+
+def write_pnm(file, width, height, pixels, meta):
+ """Write a Netpbm PNM/PAM file.
+ """
+
+ bitdepth = meta['bitdepth']
+ maxval = 2**bitdepth - 1
+ # Rudely, the number of image planes can be used to determine
+ # whether we are L (PGM), LA (PAM), RGB (PPM), or RGBA (PAM).
+ planes = meta['planes']
+ # Can be an assert as long as we assume that pixels and meta came
+ # from a PNG file.
+ assert planes in (1,2,3,4)
+ if planes in (1,3):
+ if 1 == planes:
+ # PGM
+ # Could generate PBM if maxval is 1, but we don't (for one
+ # thing, we'd have to convert the data, not just blat it
+ # out).
+ fmt = 'P5'
+ else:
+ # PPM
+ fmt = 'P6'
+ header = '%s %d %d %d\n' % (fmt, width, height, maxval)
+ if planes in (2,4):
+ # PAM
+ # See http://netpbm.sourceforge.net/doc/pam.html
+ if 2 == planes:
+ tupltype = 'GRAYSCALE_ALPHA'
+ else:
+ tupltype = 'RGB_ALPHA'
+ header = ('P7\nWIDTH %d\nHEIGHT %d\nDEPTH %d\nMAXVAL %d\n'
+ 'TUPLTYPE %s\nENDHDR\n' %
+ (width, height, planes, maxval, tupltype))
+ file.write(header.encode('ascii'))
+ # Values per row
+ vpr = planes * width
+ # struct format
+ fmt = '>%d' % vpr
+ if maxval > 0xff:
+ fmt = fmt + 'H'
+ else:
+ fmt = fmt + 'B'
+ for row in pixels:
+ file.write(struct.pack(fmt, *row))
+ file.flush()
+
+def color_triple(color):
+ """
+ Convert a command line colour value to a RGB triple of integers.
+ FIXME: Somewhere we need support for greyscale backgrounds etc.
+ """
+ if color.startswith('#') and len(color) == 4:
+ return (int(color[1], 16),
+ int(color[2], 16),
+ int(color[3], 16))
+ if color.startswith('#') and len(color) == 7:
+ return (int(color[1:3], 16),
+ int(color[3:5], 16),
+ int(color[5:7], 16))
+ elif color.startswith('#') and len(color) == 13:
+ return (int(color[1:5], 16),
+ int(color[5:9], 16),
+ int(color[9:13], 16))
+
+def _add_common_options(parser):
+ """Call *parser.add_option* for each of the options that are
+ common between this PNG--PNM conversion tool and the gen
+ tool.
+ """
+ parser.add_option("-i", "--interlace",
+ default=False, action="store_true",
+ help="create an interlaced PNG file (Adam7)")
+ parser.add_option("-t", "--transparent",
+ action="store", type="string", metavar="#RRGGBB",
+ help="mark the specified colour as transparent")
+ parser.add_option("-b", "--background",
+ action="store", type="string", metavar="#RRGGBB",
+ help="save the specified background colour")
+ parser.add_option("-g", "--gamma",
+ action="store", type="float", metavar="value",
+ help="save the specified gamma value")
+ parser.add_option("-c", "--compression",
+ action="store", type="int", metavar="level",
+ help="zlib compression level (0-9)")
+ return parser
+
+def _main(argv):
+ """
+ Run the PNG encoder with options from the command line.
+ """
+
+ # Parse command line arguments
+ from optparse import OptionParser
+ version = '%prog ' + __version__
+ parser = OptionParser(version=version)
+ parser.set_usage("%prog [options] [imagefile]")
+ parser.add_option('-r', '--read-png', default=False,
+ action='store_true',
+ help='Read PNG, write PNM')
+ parser.add_option("-a", "--alpha",
+ action="store", type="string", metavar="pgmfile",
+ help="alpha channel transparency (RGBA)")
+ _add_common_options(parser)
+
+ (options, args) = parser.parse_args(args=argv[1:])
+
+ # Convert options
+ if options.transparent is not None:
+ options.transparent = color_triple(options.transparent)
+ if options.background is not None:
+ options.background = color_triple(options.background)
+
+ # Prepare input and output files
+ if len(args) == 0:
+ infilename = '-'
+ infile = sys.stdin
+ elif len(args) == 1:
+ infilename = args[0]
+ infile = open(infilename, 'rb')
+ else:
+ parser.error("more than one input file")
+ outfile = sys.stdout
+ if sys.platform == "win32":
+ import msvcrt, os
+ msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
+
+ if options.read_png:
+ # Encode PNG to PPM
+ png = Reader(file=infile)
+ width,height,pixels,meta = png.asDirect()
+ write_pnm(outfile, width, height, pixels, meta)
+ else:
+ # Encode PNM to PNG
+ format, width, height, depth, maxval = \
+ read_pnm_header(infile, (b'P5',b'P6',b'P7'))
+ # When it comes to the variety of input formats, we do something
+ # rather rude. Observe that L, LA, RGB, RGBA are the 4 colour
+ # types supported by PNG and that they correspond to 1, 2, 3, 4
+ # channels respectively. So we use the number of channels in
+ # the source image to determine which one we have. We do not
+ # care about TUPLTYPE.
+ greyscale = depth <= 2
+ pamalpha = depth in (2,4)
+ supported = [2**x-1 for x in range(1,17)]
+ try:
+ mi = supported.index(maxval)
+ except ValueError:
+ raise NotImplementedError(
+ 'your maxval (%s) not in supported list %s' %
+ (maxval, str(supported)))
+ bitdepth = mi+1
+ writer = Writer(width, height,
+ greyscale=greyscale,
+ bitdepth=bitdepth,
+ interlace=options.interlace,
+ transparent=options.transparent,
+ background=options.background,
+ alpha=bool(pamalpha or options.alpha),
+ gamma=options.gamma,
+ compression=options.compression)
+ if options.alpha:
+ pgmfile = open(options.alpha, 'rb')
+ format, awidth, aheight, adepth, amaxval = \
+ read_pnm_header(pgmfile, 'P5')
+ if amaxval != '255':
+ raise NotImplementedError(
+ 'maxval %s not supported for alpha channel' % amaxval)
+ if (awidth, aheight) != (width, height):
+ raise ValueError("alpha channel image size mismatch"
+ " (%s has %sx%s but %s has %sx%s)"
+ % (infilename, width, height,
+ options.alpha, awidth, aheight))
+ writer.convert_ppm_and_pgm(infile, pgmfile, outfile)
+ else:
+ writer.convert_pnm(infile, outfile)
+
+
+if __name__ == '__main__':
+ try:
+ _main(sys.argv)
+ except Error as e:
+ print(e, file=sys.stderr)
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-24 10:56:25 +0000