---
name: pdf_add_image
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def pdf_add_image(doc, image, x, y, width, height, keep_aspect) -> PDFDoc"
description: "Añade una imagen PNG o JPEG al documento PDF desde un path de archivo o bytes. Calcula automaticamente la dimension faltante si solo se especifica width o height para mantener la relacion de aspecto."
tags: [pdf, image, embed, builder, infra]
uses_functions: []
uses_types: [pdf_doc_py_infra]
returns: [pdf_doc_py_infra]
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: doc
    desc: "PDFDoc con pagina activa"
  - name: image
    desc: "path absoluto o relativo a la imagen (str) o bytes del contenido de la imagen"
  - name: x
    desc: "posicion X en mm desde el borde izquierdo; None usa posicion actual del cursor"
  - name: y
    desc: "posicion Y en mm desde el borde superior; None usa posicion actual del cursor"
  - name: width
    desc: "ancho de la imagen en mm; None calcula desde height o usa ancho disponible"
  - name: height
    desc: "alto de la imagen en mm; None calcula desde width para mantener ratio"
  - name: keep_aspect
    desc: "si True fpdf2 calcula automaticamente la dimension faltante"
output: "PDFDoc con la imagen embebida en la pagina activa"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/pdf_add_image.py"
---

## Ejemplo

```python
# Imagen desde path con ancho fijo (height automatico)
doc = pdf_add_image(doc, "assets/logo.png", x=15, y=10, width=40)

# Imagen desde bytes
with open("chart.png", "rb") as f:
    img_bytes = f.read()
doc = pdf_add_image(doc, img_bytes, width=120)

# Imagen en posicion actual del cursor
doc = pdf_add_image(doc, "diagrama.png", width=fpdf_doc.fpdf.epw)
```

## Notas

Soporta PNG y JPEG nativamente en fpdf2. Para bytes, usa `io.BytesIO` como wrapper. fpdf2 gestiona automaticamente la relacion de aspecto cuando solo se especifica una dimension (fpdf calcula la otra si `h=0`). El cursor se mueve 5mm debajo de la imagen tras insertarla. Para SVG necesitaria `fpdf2[svg]` como extra opcional.