🛠 Guía de Uso de Yimago

Esta sección explica cómo integrar Yimago en tus proyectos de Python 3.14+ y cómo aprovechar el procesamiento encadenado.

1. Instalación y Configuración

Para comenzar a usar la librería, asegúrate de tenerla instalada en tu entorno:

pip install yimago

2. Inicio Rápido con YImage

La clase YImage es el punto de entrada principal. Puedes cargar una imagen local o una desde la web pasando la URL directamente al constructor.

from yimago import YImage

# Carga local con modo debug activado
img = YImage("paisaje.png", debug_in=True)

# Carga desde URL
img_web = YImage("https://ejemplo.com/foto.jpg")

3. Procesamiento Encadenado (Method Chaining)

Yimago permite realizar múltiples operaciones en una sola línea de código, lo que mantiene el script limpio y legible.

YImage("entrada.png")
    .rotate_to(90)
    .grayscale()
    .resize_to(500, 500)
    .save("salida.jpg")

4. Detalles de los Métodos

Rotación (.rotate_to)

Gira la imagen los grados indicados. Internamente usa la expansión de lienzo para que no se pierdan las esquinas de la imagen.

img.rotate_to(180)

Redimensionamiento (.resize_to)

Ajusta la imagen a un ancho y alto específicos en píxeles usando el filtro de alta calidad LANCZOS.

img.resize_to(800, 600)

Conversión de Formatos (.convert_to)

Cambia la extensión del archivo actual. El sistema maneja automáticamente la eliminación de transparencias si el formato de destino no las soporta (como JPG).

img.convert_to("webp")

5. Clase YeanmitConverter

Si necesitas usar la lógica de conversión de forma aislada, puedes invocar al convertidor directamente. Este se encarga de crear el nuevo archivo en la misma ruta que el original si no se especifica una ruta de salida.

from yimago import YeanmitConverter

# Supongamos que ya tienes una instancia de YImage llamada 'mi_img'
YeanmitConverter.to_format(mi_img, "png")

6. Guardar configuraciones temporales

Si necesitas guardar una configuracion temporal para usarla después, puede usar .save_preset.

img = YImage("foto.png")

# Guardar configuración temporal (por defecto permanent=False)
img.save_preset("mi_filtro_rapido", {"rotate_to": 45, "grayscale": True})

7. Guardar configuraciones de largo plazo

Si necesitas guardar configuraciones entre archivos, puedes activar el permanent=True, en donde se creara un json en la carpeta de usuario.

img.save_preset("estilo_final", {
    "resize_to": [800, 600],
    "convert_to": "webp"
}, permanent=True)

8. Aplicar configuraciones

Para aplicar las configuraciones guardadas, puedes usar apply_preset. Se buscara tanto como en temporal como en configuraciones de largo plazo.

img.apply_preset("estilo_final").save("resultado_final.webp")

Y si olvidaste el nombre, puedes usar preset_list para ver una lista JSON de las configuraciones guardadas(temporales y de largo plazo).

print(img.preset_list())

9. Eliminar configuración

Cuando ya no necesites una configuración, puedes delete_preset.

img.delete_preset("mi_filtro_rapido")

10. Deshacer(undo)

Aveces nos arrepentimos de alguna modificación a la imagen, podemos usar undo para deshacer al ultimo cambio. Predeterminadamente, el maximo para deshacer son los ultimos 10 cambios.

img = YImage("foto.png")

# Realizamos cambios
img.grayscale().rotate_to(90)

# ¿No te gusta el resultado? Deshaz el último cambio (la rotación)
img.undo()

# Deshaz otro cambio (el paso a escala de grises)
img.undo()

---

Documentación para Yimago v0.1.1