# psd-tools

 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov c45be40 2012-11-03 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov c45be40 2012-11-03 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov c45be40 2012-11-03 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov c45be40 2012-11-03 Mikhail Korobov 40b0497 2012-11-06 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 40b0497 2012-11-06 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov c45be40 2012-11-03 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 40b0497 2012-11-06 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov d7d748b 2012-11-07 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 85930f6 2012-11-05 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 40b0497 2012-11-06 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov d19dca4 2012-11-04 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 97f226b 2012-10-16 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 8efc29a 2012-10-30 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov d19dca4 2012-11-04 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov d6a88a1 2012-11-05 Mikhail Korobov 0b3bda3 2012-10-14 Ivan Ivanov d66c76c 2012-11-05 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov d6a88a1 2012-11-05 Mikhail Korobov 9d6daa0 2012-11-06 Mikhail Korobov d6a88a1 2012-11-05 Mikhail Korobov 0b3bda3 2012-10-14 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov 0e9711b 2012-11-01 Mikhail Korobov 322997a 2012-10-27 Mikhail Korobov e05665f 2012-10-31 Mikhail Korobov d19dca4 2012-11-04   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 psd-tools ========= psd-tools is a package for reading Adobe Photoshop PSD files (as described in specification_) to Python data structures. .. _specification: https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/PhotoshopFileFormats.htm Installation ------------ :: pip install psd-tools There are also optional dependencies: * docopt_ for command-line interface:: pip install docopt * PIL_ (or Pillow_) for accessing PSD image and layer data as PIL images:: pip install Pillow * Pymaging_ and packbits_ for accessing PSD image and layer data as pymaging.Image:: pip install packbits (Pymaging installation instructions_ are available in pymaging docs). .. note:: In order to extract images from 32bit PSD files PIL/Pillow must be built with LITTLECMS support. .. _docopt: https://github.com/docopt/docopt .. _PIL: http://www.pythonware.com/products/pil/ .. _Pillow: https://github.com/python-imaging/Pillow .. _packbits: http://pypi.python.org/pypi/packbits/ .. _Pymaging: https://github.com/ojii/pymaging .. _Pymaging installation instructions: http://pymaging.readthedocs.org/en/latest/usr/installation.html Usage ----- Load an image:: >>> from psd_tools import PSDImage >>> psd = PSDImage.load('my_image.psd') Read image header:: >>> psd.header PsdHeader(number_of_channels=3, height=200, width=100, depth=8, color_mode=RGB) Access its layers:: >>> psd.layers [, , ] Work with a layer group:: >>> group2 = psd.layers[0] >>> group2.name Group 2 >>> group2.visible True >>> group2.closed False >>> group2.opacity 255 >>> from psd_tools.constants import BlendMode >>> group2.blend_mode == BlendMode.NORMAL True >>> group2.layers [] Work with a layer:: >>> layer = group2.layers[0] >>> layer.name Shape 2 >>> layer.bbox BBox(x1=40, y1=72, x2=83, y2=134) >>> layer.bbox.width, layer.bbox.height (43, 62) >>> layer.visible, layer.opacity, layer.blend_mode (True, 255, u'norm') >>> layer.as_PIL() Export a single layer:: >>> layer_image = layer.as_PIL() >>> layer_image.save('layer.png') Export the merged image:: >>> merged_image = psd.as_PIL() >>> merged_image.save('my_image.png') The same using Pymaging_:: >>> merged_image = psd.as_pymaging() >>> merged_image.save_to_path('my_image.png') >>> layer_image = layer.as_pymaging() >>> layer_image.save_to_path('layer.png') Why yet another PSD reader? --------------------------- There are existing PSD readers for Python: * psdparse_; * pypsd_; * there is a PSD reader in PIL_ library; * it is possible to write Python plugins for GIMP_. PSD reader in PIL is incomplete and contributing to PIL is complicated because of the slow release process, but the main issue with PIL for me is that PIL doesn't have an API for layer groups. GIMP is cool, but it is a huge dependency, its PSD parser is not perfect and it is not easy to use GIMP Python plugin from *your* code. I also considered contributing to pypsd or psdparse, but they are GPL and I was not totally satisfied with the interface and the code (they are really fine, that's me having specific style requirements). So I finally decided to roll out yet another implementation that should be MIT-licensed, systematically based on the specification_ (it turns out the specs are incomplete and sometimes incorrect though); parser should be implemented as a set of functions; the package should have tests and support both Python 2.x and Python 3.x. .. _GIMP: http://www.gimp.org/ .. _psdparse: https://github.com/jerem/psdparse .. _pypsd: https://code.google.com/p/pypsd Design overview --------------- The process of handling a PSD file is split into 3 stages: 1) "Reading": the file is read and parsed to low-level data structures that closely match the specification. No user-accessible images are constructed; image resources blocks and additional layer information are extracted but not parsed (they remain just keys with a binary data). The goal is to extract all information from a PSD file. 2) "Decoding": image resource blocks and additional layer information blocks are parsed to a more detailed data structures (that are still based on a specification). There are a lot of PSD data types and the library currently doesn't handle them all, but it should be easy to add the parsing code for the missing PSD data structures if needed. After (1) and (2) we have an in-memory data structure that closely resembles PSD file; it should be fairly complete but very low-level and not easy to use. So there is a third stage: 3) "User-facing API": PSD image is converted to an user-friendly object that supports layer groups, exporting data as PIL.Image or pymaging.Image, etc. Stage separation also means user-facing API may be opinionated: if somebody doesn't like it then it should possible to build an another API based on lower-level decoded PSD file. psd-tools tries not to throw away information from the original PSD file; even if the library can't parse some info, this info will be likely available somewhere as raw bytes (open a bug if this is not the case). This should make it possible to modify and write PSD files (currently not implemented; contributions are welcome). Features -------- Supported: * reading of RGB and RGBA images; * 8bit, 16bit and 32bit channels; * all PSD compression methods are supported (not only the most common RAW and RLE); * image ICC profile is taken into account; * most important (imho) 23 image resource types and 12 tagged block types are decoded; * there is an optional Cython extension to make the parsing fast. Not implemented: * reading of CMYK, Duotone, LAB, etc. images; * many image resource types and tagged blocks are not decoded (they are attached to the result as raw bytes); * this library can't blend layers together: it is possible to export a single layer and to export a final image, but it is not possible to render e.g. layer group; * the decoding of Descriptor structures is very basic; * the writing of PSD images is not implemented; * only 8bit images can be converted to pymaging.Image. If you need some of unimplemented features then please fire an issue or implement it yourself (pull requests are welcome in this case). Contributing ------------ Development happens at github and bitbucket: * https://github.com/kmike/psd-tools * https://bitbucket.org/kmike/psd-tools The main issue tracker is at github: https://github.com/kmike/psd-tools/issues Feel free to submit ideas, bugs, pull requests (git or hg) or regular patches. In case of bugs it would be helpful to provide a small PSD file demonstrating the issue; this file may be added to a test suite. .. note:: Unfortunately I don't have a license for Adobe Photoshop and use GIMP for testing; PNG screenshots may be necessary in cases where GIMP fails. In order to run tests, install tox _ and type :: tox from the source checkout. The license is MIT. Acknowledgments --------------- Thanks to all guys who write PSD parsers: I learned a lot about PSD file structure from the source code of psdparse_, GIMP_, libpsd_ and psdparse C library_; special thanks to Paint.NET PSD Plugin_ authors for deciphering the "32bit layer + zip-with-prediction compression" case. .. _libpsd: http://sourceforge.net/projects/libpsd/ .. _psdparse C library: http://telegraphics.com.au/svn/psdparse/trunk/ .. _Paint.NET PSD Plugin: http://psdplugin.codeplex.com/