psd-tools

https://psd-tools.readthedocs.io/en/latest
Admin
psd-tools is a Python package for reading and writing Adobe Photoshop PSD files, supporting raw...
Tokens:377,079
Snippets:2,801
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install psd-tools with pip

Source: https://psd-tools.readthedocs.io/en/latest/index.html

Basic installation command for the psd-tools package using pip.

```bash
pip install psd-tools

```

--------------------------------

### Install system dependencies for testing

Source: https://psd-tools.readthedocs.io/en/latest/contributing.html

Install required system packages for building PIL/Pillow with LittleCMS support on Ubuntu.

```bash
apt-get install liblcms2-dev libjpeg-dev libfreetype6-dev zlib1g-dev

```

--------------------------------

### Example usage of smart_object.open()

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/smart_object.html

Shows how to open a smart object's file content using a context manager. The example reads all data from the opened file.

```python
with layer.smart_object.open() as f:
    data = f.read()
```

--------------------------------

### Install psd-tools composite extra using uv

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.composite.html

Alternative installation command using uv instead of pip. Installs the same composite extra with aggdraw and scipy dependencies.

```bash
uv sync --extra composite

```

--------------------------------

### Composite usage examples

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/composite.html

Shows how to open a PSD file and composite it with default settings, custom backdrop, force re-rendering, and a layer filter. These examples are from the docstring and demonstrate common usage patterns.

```python
>>> from psd_tools import PSDImage
>>> psd = PSDImage.open('example.psd')
>>> color, shape, alpha = composite(psd)
>>> # Apply custom backdrop
>>> color, shape, alpha = composite(psd, color=(1.0, 0.0, 0.0), alpha=1.0)
>>> # Force re-render vector layers
>>> color, shape, alpha = composite(psd, force=True)
>>> # Composite only visible layers
>>> color, shape, alpha = composite(psd, layer_filter=lambda l: l.visible)
```

--------------------------------

### Install psd-tools with composite extra

Source: https://psd-tools.readthedocs.io/en/latest/migration.html

Install psd-tools with the composite extra to enable advanced compositing features like vector masks, gradients, patterns, and effects.

```bash
pip install 'psd-tools[composite]'

```

--------------------------------

### Install psd-tools and composite dependencies separately

Source: https://psd-tools.readthedocs.io/en/latest/migration.html

Alternatively, install psd-tools and the required composite dependencies (aggdraw, scipy) separately.

```bash
pip install psd-tools aggdraw scipy

```

--------------------------------

### PSDImage class docstring example

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/psd_image.html

Example usage from the PSDImage class docstring showing how to open a PSD file, composite it, and iterate layers.

```python
from psd_tools import PSDImage

psdimage = PSDImage.open('example.psd')
image = psdimage.composite()

for layer in psdimage:
    layer_image = layer.composite()
```

--------------------------------

### Module docstring with usage example

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/image_resources.html

The module docstring includes a usage example showing how to retrieve version info using the Resource enum and the get_data method. It also lists the resource IDs that are plain bytes.

```python
from psd_tools.constants import Resource

version_info = psd.image_resources.get_data(Resource.VERSION_INFO)
```

```python
Resource.OBSOLETE1: 1000
Resource.MAC_PRINT_MANAGER_INFO: 1001
Resource.MAC_PAGE_FORMAT_INFO: 1002
Resource.OBSOLETE2: 1003
Resource.DISPLAY_INFO_OBSOLETE: 1007
Resource.BORDER_INFO: 1009
Resource.DUOTONE_IMAGE_INFO: 1018
Resource.EFFECTIVE_BW: 1019
Resource.OBSOLETE3: 1020
Resource.EPS_OPTIONS: 1021
Resource.QUICK_MASK_INFO: 1022
Resource.OBSOLETE4: 1023
Resource.WORKING_PATH: 1025
Resource.OBSOLETE5: 1027
Resource.IPTC_NAA: 1028
Resource.IMAGE_MODE_RAW: 1029
Resource.JPEG_QUALITY: 1030
Resource.URL: 1035
Resource.COLOR_SAMPLERS_RESOURCE_OBSOLETE: 1038
Resource.ICC_PROFILE: 1039
Resource.SPOT_HALFTONE: 1043
Resource.JUMP_TO_XPEP: 1052
Resource.EXIF_DATA_1: 1058
Resource.EXIF_DATA_3: 1059
Resource.XMP_METADATA: 1060
Resource.CAPTION_DIGEST: 1061
Resource.ALTERNATE_DUOTONE_COLORS: 1066
Resource.ALTERNATE_SPOT_COLORS: 1067
Resource.HDR_TONING_INFO: 1070
Resource.PRINT_INFO_CS2: 1071
Resource.COLOR_SAMPLERS_RESOURCE: 1073
Resource.DISPLAY_INFO: 1077
Resource.MAC_NSPRINTINFO: 1084
Resource.WINDOWS_DEVMODE: 1085
Resource.PATH_INFO_N: 2000-2999
Resource.PLUGIN_RESOURCES_N: 4000-4999
Resource.IMAGE_READY_VARIABLES: 7000
Resource.IMAGE_READY_DATA_SETS: 7001
Resource.IMAGE_READY_DEFAULT_SELECTED_STATE: 7002
Resource.IMAGE_READY_7_ROLLOVER_EXPANDED_STATE: 7003
Resource.IMAGE_READY_ROLLOVER_EXPANDED_STATE: 7004
Resource.IMAGE_READY_SAVE_LAYER_SETTINGS: 7005
Resource.IMAGE_READY_VERSION: 7006
Resource.LIGHTROOM_WORKFLOW: 8000
```

--------------------------------

### get_data method docstring example

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/tagged_blocks.html

Example from the get_data method docstring showing the equivalent code for retrieving data from tagged blocks.

```python
if key in tagged_blocks:
    value = tagged_blocks[key].data
```

--------------------------------

### Module docstring example usage

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/psd_image.html

Example usage from the module docstring showing how to open a PSD file, access properties, iterate layers, modify layers, composite, and save.

```python
from psd_tools import PSDImage

# Open a PSD file
psd = PSDImage.open('document.psd')

# Access document properties
print(f"Size: {psd.width}x{psd.height}")
print(f"Color mode: {psd.color_mode}")

# Iterate through layers
for layer in psd:
    print(f"{layer.name}: {layer.kind}")

# Access layers by index
layer = psd[0]  # First layer

# Modify layers
layer.visible = False
layer.opacity = 128

# Composite to image
image = psd.composite()
image.save('output.png')

# Save changes
psd.save('modified.psd')
```

--------------------------------

### gray_to_rgb function with docstring example

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/color_convert.html

Expands a grayscale value to an achromatic RGB triple. Takes a luminance in [0,1] and returns a 3-tuple with the same value for all channels. Includes a doctest example.

```python
def gray_to_rgb(gray: float) -> tuple[float, float, float]:
    """Expand a grayscale value to an achromatic RGB triple.

    Args:
        gray: Luminance in [0.0, 1.0].

    Returns:
        3-tuple ``(gray, gray, gray)``.

    Examples:
        >>> gray_to_rgb(0.5)
        (0.5, 0.5, 0.5)
    """
    return (gray, gray, gray)
```

--------------------------------

### Install psd-tools with composite extra

Source: https://psd-tools.readthedocs.io/en/latest/index.html

Installs optional dependencies (aggdraw, scipy) for advanced layer compositing features such as vector shape rendering, gradient/pattern fills, and layer effects.

```bash
pip install psd-tools[composite]

```

--------------------------------

### TypeLayer example: print text and engine_dict

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/layers.html

Example from the TypeLayer docstring showing how to access text and styling information. It checks the layer kind and prints the text and the 'StyleRun' entry from the engine_dict.

```python
        if layer.kind == 'type':
            print(layer.text)
            print(layer.engine_dict['StyleRun'])
```

--------------------------------

### Example usage of multiply and screen blend functions

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/blend.html

Shows how to import and apply the multiply and screen blend functions from psd_tools.composite.blend on normalized float32 arrays. The example creates backdrop and source colors, applies multiply, and notes the resulting array.

```python
import numpy as np
from psd_tools.composite.blend import multiply, screen

# Create backdrop and source colors (normalized)
backdrop = np.array([0.5, 0.3, 0.8], dtype=np.float32)
source = np.array([0.7, 0.6, 0.2], dtype=np.float32)

# Apply blend mode
result = multiply(backdrop, source)
# Result: [0.35, 0.18, 0.16]
```

--------------------------------

### Tokenizer usage example in class docstring

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/engine_data.html

Shows how to use the Tokenizer class to iterate over tokens in engine data. The example is from the Tokenizer class docstring and demonstrates creating a tokenizer and printing each token with its type.

```python
tokenizer = Tokenizer(data)
for token, token_type in tokenizer:
    print('%s: %r' % (token_type.name, token))
```

--------------------------------

### Module docstring with example usage of compress and decompress

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/compression.html

The module docstring includes an example showing how to compress and decompress raw channel data using psd_tools.compression.compress and decompress with Compression.RLE. It demonstrates the required parameters: data, compression, width, height, depth, and version.

```python
from psd_tools.compression import compress, decompress
from psd_tools.constants import Compression

# Compress raw channel data
compressed = compress(
    data=raw_pixels,
    compression=Compression.RLE,
    width=100,
    height=100,
    depth=8,
    version=1
)

# Decompress back to raw data
raw_pixels = decompress(
    data=compressed,
    compression=Compression.RLE,
    width=100,
    height=100,
    depth=8,
    version=1
)
```

--------------------------------

### Line.line_start

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/shape.html

Property that returns the line start descriptor.

```APIDOC
## Line.line_start

### Description
Returns the line start descriptor.

### Property
`line_start`

### Return Type
`Descriptor`

### Returns
- **Descriptor** - The line start descriptor.

```

--------------------------------

### Install optional compositing dependencies with pip

Source: https://psd-tools.readthedocs.io/en/latest/usage.html

Installs psd-tools[composite] to enable advanced compositing features such as vector strokes, gradient and pattern fills, and layer effects. Basic compositing works without these dependencies using cached previews or simple pixel-based operations.

```bash
pip install psd-tools[composite]
```

--------------------------------

### Convert RGB to Lab with rgb_to_lab

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.color_convert.html

Shows example calls to rgb_to_lab, each wrapped in tuple(round(v, 4) for v in ...) to round results. The examples convert white and neutral grey, returning (100.0, 0.0, 0.0) and (53.389, 0.0, 0.0) respectively.

```python
>>> tuple(round(v, 4) for v in rgb_to_lab(1.0, 1.0, 1.0))
(100.0, 0.0, 0.0)
>>> tuple(round(v, 4) for v in rgb_to_lab(0.5, 0.5, 0.5))
(53.389, 0.0, 0.0)
```

--------------------------------

### Install documentation dependencies

Source: https://psd-tools.readthedocs.io/en/latest/contributing.html

Use uv to sync the project with documentation dependencies.

```bash
uv sync --group docs

```

--------------------------------

### TaggedBlocks class docstring example

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/tagged_blocks.html

Example from the TaggedBlocks class docstring showing how to iterate over tagged block keys and get data using the Tag.TYPE_TOOL_OBJECT_SETTING constant.

```python
from psd_tools.constants import Tag

# Iterate over fields
for key in tagged_blocks:
    print(key)

# Get a field
value = tagged_blocks.get_data(Tag.TYPE_TOOL_OBJECT_SETTING)
```

--------------------------------

### NumPy array API

Source: https://psd-tools.readthedocs.io/en/latest/migration.html

Introduced in v1.9, this example shows how to get NumPy arrays from a PSD image and a layer.

```python
image = psd.numpy()
layer_image = layer.numpy()

```

--------------------------------

### Install psd-tools with development dependencies

Source: https://psd-tools.readthedocs.io/en/latest/contributing.html

Use uv to sync the project with development dependencies and the composite extra.

```bash
uv sync --group dev --extra composite

```

--------------------------------

### Create a FileHeader instance

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.psd.header.html

Shows how to instantiate FileHeader with the required parameters: channels, height, width, depth, and color_mode. The example uses ColorMode.GRAYSCALE.

```python
from psd_tools.psd.header import FileHeader
from psd_tools.constants import ColorMode

header = FileHeader(channels=2, height=359, width=400, depth=8,
                    color_mode=ColorMode.GRAYSCALE)

```

--------------------------------

### Module source code for psd_tools.composite.effects

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/effects.html

The full source code of the psd_tools.composite.effects module as displayed on the page. It includes the module docstring, imports, constants, and the start of the implementation. Effects rendering requires scipy; install with 'pip install psd-tools[composite]'.

```python
# mypy: disable-error-code="assignment"
"""
Layer effects rendering.

This module implements rendering for Photoshop layer effects (also known as
layer styles). Effects are non-destructive visual enhancements applied to layers
such as strokes, shadows, glows, and overlays.

**Note**: Effects rendering requires scipy. Install it with::

    pip install 'psd-tools[composite]'

Currently supported effects:

- **Stroke**: Outline around layer shape or pixels
  - Supports solid color, gradient, and pattern fills
  - Position: inside, outside, or centered
  - Limited compared to Photoshop's full implementation

Partially supported or limited effects:

- Drop shadow, inner shadow, outer glow, inner glow
- These may render but with reduced accuracy

The main function :py:func:`draw_stroke_effect` handles stroke rendering by:

1. Extracting the layer's alpha channel or shape mask
2. Placing the stroke relative to that shape according to its size and position
3. Filling the stroke region with the specified paint (solid color, gradient, pattern)
4. Returning the rendered stroke as a NumPy array

:py:func:`draw_stroke_effect_split` is the same stroke with its coverage
divided at the layer's boundary, which is what the compositor takes: the two
sides of that boundary are composited differently. Compositing is the only
caller that needs the division, so the undivided spelling above stays.

Implementation notes:

- Effects are image-based rather than vector-based, which may differ from Photoshop
- A shape layer's stroke follows its path interior but traces the stored coverage
  at the path's edge
- Some effect parameters may not be fully supported
- Complex effect combinations may not render identically to Photoshop

Example usage (internal)::

    from psd_tools.composite.effects import draw_stroke_effect

    # Called during layer compositing
    viewport = (0, 0, 100, 100)  # Region to render
    shape = layer_alpha_channel    # NumPy array
    desc = stroke_descriptor       # Effect parameters

    color, alpha = draw_stroke_effect(viewport, shape, desc, psd)

The effects system integrates with the main compositing pipeline and is
automatically applied when rendering layers that have effects enabled.
"""

import logging
import math
from typing import TYPE_CHECKING

import numpy as np

from psd_tools.api.utils import AllocBudget, check_pixel_size
from psd_tools.composite import paint
from psd_tools.composite._compat import HAS_SCIPY
from psd_tools.composite.utils import divide
from psd_tools.psd.descriptor import Descriptor
from psd_tools.terminology import Enum, Key

if TYPE_CHECKING:
    from psd_tools.api.protocols import PSDProtocol

logger = logging.getLogger(__name__)

# Where each style puts its band, in multiples of the stroke's nominal size,
# measured from the layer's edge and positive outward. One table because the
# outer limit is also how far the stroke reaches past the layer, which is the
# canvas :py:func:`stroke_bbox` has to reserve for it: stating the two apart
# would let a change to one shave the outside of every stroke of that style,
# or reserve canvas nobody draws on.
#
# Only the inset style stays within the layer. It still gets the fixed pixel
# stroke_bbox() adds on top, which is not room for the stroke but room for the
# edge it is measured from.
_BANDS: dict[bytes, tuple[float, float]] = {
    Enum.OutsetFrame: (0.0, 1.0),
    Enum.CenteredFrame: (-0.5, 0.5),
    Enum.InsetFrame: (-1.0, 0.0),
}
# A style no descriptor Photoshop wrote can hold is drawn, and measured, as an
# outset one -- the widest of the three, so nothing it draws is clipped by the
# canvas reserved for it, and the position Photoshop itself defaults to.
_UNRECOGNISED = _BANDS[Enum.OutsetFrame]

# The widest stroke Photoshop writes; a larger size can only be a forged one.
_MAX_STROKE_SIZE = 250.0

# What a stroke canvas costs per pixel at its peak: the signed-distance
# transients (an int64 offset grid pair, float64 planes) dwarf the float32
# canvas and colour planes, so a budget is checked against this, not 4 bytes.
_STROKE_BYTES = 64

# What each offset of the distance search's grid costs at its peak.
_GRID_BYTES = 48

# Below this fraction of active pixels within the region a bounding-box crop
# would cover, :py:func:`_nearest_boundary` skips the erosion and falls back
# to its per-offset loop (#895): a thin outline on a much bigger canvas has
# active pixels too sparse within that box for the erosion to pay for itself,
# while a filled shape's boundary band fills enough of it that it does.
_DENSE_EROSION_DENSITY = 0.15


def _enum(desc: Descriptor, key: bytes) -> bytes:
    """The enum ``key`` names, or ``b""`` if the descriptor does not carry one.

```

--------------------------------

### Get stroke source in psd_tools.composite.composite

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/composite.html

Starts the stroke source retrieval method. The signature indicates it returns a tuple of three numpy arrays, with an optional path parameter. The body is truncated in the source.

```python
    def _get_stroke(
        self, layer: Layer, path: np.ndarray | None = None
    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
        """Get stroke source.


```

--------------------------------

### psd-tools command line examples

Source: https://psd-tools.readthedocs.io/en/latest/usage.html

Shows the file content with `show`, exports the whole document as PNG with `export`, and exports a single layer by indexing the input file with `[0]`.

```bash
psd-tools show example.psd  # Show the file content
psd-tools export example.psd example.png  # Export as PNG
psd-tools export example.psd[0] example-0.png  # Export layer as PNG

```

--------------------------------

### Compositor initialization and layer application loop

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/composite.html

Shows how the Compositor is instantiated with viewport, backdrop, layer filter, and force options, then applies layers from a target group and finishes. The target group is the group itself if it is a GroupMixin and not as_layer, otherwise a list containing the group.

```python
    compositor = Compositor(
        viewport,
        backdrop_color,
        backdrop_alpha,
        layer_filter,
        force,
        document_backdrop=lambda: _document_backdrop(_psd, viewport),
        widen=_widen_fn,
        color_mode=_psd.color_mode,
    )
    target_group = group if isinstance(group, GroupMixin) and not as_layer else [group]
    for layer in target_group:  # type: ignore
        compositor.apply(layer)  # type: ignore[arg-type]
    return compositor.finish()
```

--------------------------------

### Convert layer to PIL image with topil

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/layers.html

Get a PIL Image of the layer. Optionally specify a channel (e.g., 0 for 'R' channel in RGB) and whether to apply ICC profile conversion to sRGB. Returns None if the layer has no pixels. Note that not all PSD image modes are supported in PIL; for example, CMYK mode cannot include alpha channel, and deep layers come back with 8 bits per channel.

```python
from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)
```

--------------------------------

### Compositor __init__ method

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/composite/composite.html

Initializes the compositor with viewport, color, alpha, and optional parameters. Sets up internal state including cache, color mode, and document backdrop. Includes assertions to validate input shapes.

```python
    def __init__(
        self,
        viewport: tuple[int, int, int, int],
        color: np.ndarray,
        alpha: np.ndarray,
        layer_filter: Callable[[Layer], bool] | None = None,
        force: bool = False,
        adjustment_isolated: bool = False,
        document_backdrop: Callable[[], tuple[np.ndarray, np.ndarray] | None]
        | None = None,
        widen: _Widen = _widen,
        color_mode: ColorMode | None = None,
        cache: _PassCache | None = None,
    ):
        self._viewport = viewport
        self._layer_filter = layer_filter
        self._force = force
        self._mask_repeats: dict[int, bool] = {}
        # How a one-channel array becomes this compositor's width. Carried
        # rather than derived because the four sites that need it below are
        # inside this class, which holds no document handle (#722, #749).
        self._widen = widen
        # The document's colour mode, for the blend functions that need to know
        # what their operands' channels are and not just how many there are.
        # Carried for the same reason as ``widen``: ``_apply_source()`` holds no
        # document handle either. None means "no document to ask", and leaves
        # the width to decide alone (#746).
        self._color_mode = color_mode
        # Shared with every sub-compositor this one builds, so a group's
        # contents are measured once per composite pass rather than once per
        # enclosing group. A compositor built without one starts a pass of its
        # own, which is what the public entry points and the tests do.
        self._cache: _PassCache = _PassCache() if cache is None else cache
        self._adjustment_isolated = adjustment_isolated
        # What Knockout.DEEP knocks out to. Inherited by pass-through
        # sub-compositors and reset at every isolation boundary, so deep
        # knockout escapes pass-through groups but stops at an isolated one.
        # None means "this compositor's own initial backdrop".
        #
        # Resolved lazily: it decodes the Background layer, and the vast
        # majority of documents never contain a deep knockout at all.
        self._document_backdrop_fn = document_backdrop
        self._document_backdrop_resolved = False
        self._document_backdrop: tuple[np.ndarray, np.ndarray] | None = None

        # Preconditions rather than documentation: the whole point of fixing
        # the channel count is that nothing downstream has to re-check it.
        assert color.ndim == 3, "backdrop color must be a (h, w, c) canvas"
        assert color.shape[:2] == (self.height, self.width), (
            "backdrop color %r does not cover viewport %r"
            % (color.shape, self._viewport)
        )
        assert alpha.shape == (self.height, self.width, 1), (
            "backdrop alpha %r must be single-channel over viewport %r"
            % (alpha.shape, self._viewport)
        )

        self._alpha_0 = alpha
        self._color_0 = color
        # The channel count is fixed for this compositor's lifetime; every
        # canvas it hands to or takes from the blend equations is this wide.
        self._channels = color.shape[2]

        self._shape_g = np.zeros((self.height, self.width, 1), dtype=np.float32)
        self._alpha_g = np.zeros((self.height, self.width, 1), dtype=np.float32)
        self._color = self._color_0
        self._alpha = self._alpha_0
```

--------------------------------

### Example: Creating a PSD with background color

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/psd_image.html

Shows how to create a new PSD image with a white background using the color parameter. The background_color property returns the color set at creation.

```python
psd = PSDImage.new('RGB', (640, 480), color=1.0)
psd.save('output.psd')  # White background, 3 channels (no alpha)
```

--------------------------------

### Build documentation with Makefile

Source: https://psd-tools.readthedocs.io/en/latest/contributing.html

Build the documentation using the Makefile. The default build does not report dead cross-references; only sphinx-build -n does.

```bash
make docs

```

--------------------------------

### Read and write PSD file with psd_tools.psd.PSD

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.psd.html

Example from the PSD class documentation showing how to read a PSD file from an input file and write it to an output file using the low-level PSD class.

```python
from psd_tools.psd import PSD

with open(input_file, 'rb') as f:
    psd = PSD.read(f)

with open(output_file, 'wb') as f:
    psd.write(f)

```

--------------------------------

### cmyk_to_rgb() examples

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.color_convert.html

Shows converting normalized CMYK values to RGB. The first example converts no ink to white (1.0, 1.0, 1.0), the second converts full black to black (0.0, 0.0, 0.0).

```python
>>> cmyk_to_rgb(0.0, 0.0, 0.0, 0.0)
(1.0, 1.0, 1.0)
>>> cmyk_to_rgb(0.0, 0.0, 0.0, 1.0)
(0.0, 0.0, 0.0)
```

--------------------------------

### Imports and registry setup

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/image_resources.html

The module imports necessary libraries and defines a registry for resource types. It maps several resource IDs to their corresponding data classes, such as Color, DescriptorBlock, and StringElement.

```python
import io
import logging
from typing import IO, Any, TypeVar

from attrs import define, field, astuple

from psd_tools.constants import PrintScaleStyle, Resource, AlphaChannelMode
from psd_tools.psd.base import (
    BaseElement,
    ByteElement,
    DictElement,
    IntegerElement,
    ListElement,
    NumericElement,
    ShortIntegerElement,
    StringElement,
    ValueElement,
)
from psd_tools.psd.color import Color
from psd_tools.psd.descriptor import DescriptorBlock
from psd_tools.psd.bin_utils import (
    read_exact,
    is_readable,
    read_fmt,
    read_length_block,
    read_pascal_string,
    read_unicode_string,
    trimmed_repr,
    write_bytes,
    write_fmt,
    write_length_block,
    write_pascal_string,
    write_unicode_string,
)
from psd_tools.registry import new_registry
from psd_tools.psd.parse_limits import ParseLimitError
from psd_tools.validators import in_
from psd_tools.version import __version__

logger = logging.getLogger(__name__)

T_ImageResources = TypeVar("T_ImageResources", bound="ImageResources")
T_ImageResource = TypeVar("T_ImageResource", bound="ImageResource")

TYPES, register = new_registry()

TYPES.update(
    {
        Resource.BACKGROUND_COLOR: Color,
        Resource.LAYER_COMPS: DescriptorBlock,
        Resource.MEASUREMENT_SCALE: DescriptorBlock,
        Resource.SHEET_DISCLOSURE: DescriptorBlock,
        Resource.TIMELINE_INFO: DescriptorBlock,
        Resource.ONION_SKINS: DescriptorBlock,
        Resource.COUNT_INFO: DescriptorBlock,
        Resource.PRINT_INFO_CS5: DescriptorBlock,
        Resource.PRINT_STYLE: DescriptorBlock,
        Resource.PATH_SELECTION_STATE: DescriptorBlock,
        Resource.ORIGIN_PATH_INFO: DescriptorBlock,
        Resource.AUTO_SAVE_FILE_PATH: StringElement,
        Resource.AUTO_SAVE_FORMAT: StringElement,
        Resource.WORKFLOW_URL: StringElement,
    }
)
```

--------------------------------

### gray_to_cmyk function with docstring examples

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/color_convert.html

Converts a grayscale value to CMYK using only the K (black) channel. White maps to no ink, black maps to full key. Includes doctest examples for white and black.

```python
def gray_to_cmyk(gray: float) -> tuple[float, float, float, float]:
    """Convert a grayscale value to CMYK using only the K (black) channel.

    White (1.0) maps to no ink ``(0, 0, 0, 0)``.
    Black (0.0) maps to full key ``(0, 0, 0, 1)``.

    Args:
        gray: Luminance in [0.0, 1.0] where 1.0 is white.

    Returns:
        4-tuple ``(0.0, 0.0, 0.0, 1.0 - gray)``.

    Examples:
        >>> gray_to_cmyk(1.0)
        (0.0, 0.0, 0.0, 0.0)
        >>> gray_to_cmyk(0.0)
        (0.0, 0.0, 0.0, 1.0)
    """
    return (0.0, 0.0, 0.0, 1.0 - gray)
```

--------------------------------

### EngineData markup example in module docstring

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/psd/engine_data.html

Shows the EngineData markup language structure used in PSD files for text formatting data. The example is embedded in the module docstring and illustrates the nested dictionary and array syntax.

```engineData
<<
  /EngineDict
  <<
    /Editor
    <<
      /Text (˛ˇMake a change and save.)
    >>
  >>
  /Font
  <<
    /Name (˛ˇHelveticaNeue-Light)
    /FillColor
    <<
      /Type 1
      /Values [ 1.0 0.0 0.0 0.0 ]
    >>
    /StyleSheetSet [
    <<
      /Name (˛ˇNormal RGB)
    >>
    ]
  >>
>>
```

--------------------------------

### Get NumPy array of layer with numpy

Source: https://psd-tools.readthedocs.io/en/latest/_modules/psd_tools/api/layers.html

Get a NumPy array of the layer. Optionally specify a channel ('color', 'shape', 'alpha', or 'mask') and whether to use the real mask. Default is 'color+alpha'. Returns None if there is no pixel.

```python
return numpy_io.get_array(self, channel, real_mask=real_mask)
```

--------------------------------

### topil

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.api.layers.html

Get PIL Image of the layer.

```APIDOC
## topil

### Description
Get PIL Image of the layer.

### Method
topil

### Signature
topil(channel: int | None = None, apply_icc: bool = True) -> Image | None

### Parameters
- **channel** (int) - Optional - Which channel to return; e.g., 0 for 'R' channel in RGB image. See `ChannelID`. When None, the method returns all the channels supported by PIL modes.
- **apply_icc** (bool) - Optional - Whether to apply ICC profile conversion to sRGB. Default is True.

### Returns
- **PIL.Image.Image | None** - The PIL Image, or None if the layer has no pixels.

### Example
```python
from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)
```

### Notes
- Not all PSD image modes are supported in PIL. For example, 'CMYK' mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.
- PIL has no 16- or 32-bit RGB, CMYK or LAB mode, so a deep layer comes back with 8 bits per channel. Use `numpy()` for the stored precision.
```

--------------------------------

### gray_to_rgb() example

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.color_convert.html

Shows expanding a grayscale value to an achromatic RGB triple.

```python
>>> gray_to_rgb(0.5)
(0.5, 0.5, 0.5)
```

--------------------------------

### Open and composite a PSD file

Source: https://psd-tools.readthedocs.io/en/latest/index.html

Basic usage example: open a PSD file, composite it to an image, save as PNG, and iterate over layers to print and composite each layer.

```python
from psd_tools import PSDImage

psd = PSDImage.open('example.psd')
psd.composite().save('example.png')

for layer in psd:
    print(layer)
    image = layer.composite()

```

--------------------------------

### numpy

Source: https://psd-tools.readthedocs.io/en/latest/reference/psd_tools.api.layers.html

Get NumPy array of the layer.

```APIDOC
## numpy

### Description
Get NumPy array of the layer.

### Method
numpy

### Signature
numpy(channel: str | None = None, real_mask: bool = True) -> ndarray | None

### Parameters
- **channel** (str) - Optional - Which channel to return, can be 'color', 'shape', 'alpha', or 'mask'. Default is 'color+alpha'.
- **real_mask** (bool) - Optional - Whether to return the real mask. Default is True.

### Returns
- **numpy.ndarray | None** - The pixel data as a NumPy array, or None if there is no pixel.
```
Tokens:
Raw