SVG viewBox y coordenadas en Python

Respuesta rápida: Para controlar coordenadas SVG en Python, cargue o cree un SVGDocument y defina width, height y viewBox en la raíz SVG con set_attribute(). width y height definen el tamaño visible de salida. viewBox elige qué rectángulo de coordenadas se muestra, y SVG escala ese sistema de coordenadas hacia arriba o hacia abajo para llenar el viewport.

from aspose.svg import SVGDocument

with SVGDocument() as document:
    svg = document.root_element
    svg.set_attribute("width", "300")
    svg.set_attribute("height", "150")
    svg.set_attribute("viewBox", "0 0 100 50")
    document.save("viewbox.svg")

En este artículo aprenderá a:

• establecer width, height y viewBox en la raíz SVG;
• entender cómo las coordenadas SVG se asignan al viewport visible;
• crear salida SVG escalable con un sistema de coordenadas estable;
• evitar gráficos generados recortados, estirados o redimensionados de forma inesperada.

La forma más sencilla de entender viewBox es separar el dibujo del lugar donde se muestra. El lienzo SVG es el espacio de coordenadas donde se colocan las formas. El viewport es el área visible de salida, normalmente definida por width y height. El viewBox dice: “muestra este rectángulo del lienzo SVG dentro del viewport y escala ese rectángulo para llenar el viewport”.

El atributo viewBox tiene cuatro valores: min-x, min-y, width y height. Por ejemplo, viewBox="0 0 100 50" significa: empieza a mirar en la coordenada (0, 0), muestra 100 unidades de coordenadas en horizontal y 50 unidades en vertical. Si el viewport es 300x150, ese sistema de coordenadas 100x50 se amplía tres veces para llenar el área visible. El tamaño renderizado también puede ser 600x300 o cualquier otro tamaño proporcional, y las mismas coordenadas se escalarán de nuevo para ajustarse.

Conceptos básicos de viewBox

Atributo	Ejemplo	Significado
width	300	Ancho visible de salida, por ejemplo 300 píxeles de pantalla o unidades CSS
height	150	Alto visible de salida
viewBox	0 0 100 50	Rectángulo de coordenadas que se escala para llenar el viewport
preserveAspectRatio	xMidYMid meet	Cómo se alinea y escala la gráfica cuando las proporciones no coinciden

Un sistema de coordenadas de usuario es simplemente el sistema de coordenadas que usan sus formas después de aplicar viewBox. Si un rectángulo tiene x="10" y width="80", esos valores se miden en unidades del viewBox, no directamente en píxeles de pantalla. Con width="300" height="150" viewBox="0 0 100 50", SVG escala el sistema de coordenadas de usuario hacia arriba: una unidad del viewBox se convierte en 3 unidades renderizadas en ambas direcciones. Si el viewBox fuera mayor que el viewport, el mismo mecanismo reduciría el dibujo.

Cómo definir SVG viewBox en Python

Use este flujo cuando un gráfico SVG generado necesite coordenadas predecibles y un área visible clara:

1. Cree o cargue un SVGDocument.
2. Obtenga la raíz SVG desde document.root_element.
3. Defina atributos de la raíz como width, height y viewBox con set_attribute().
4. Agregue o actualice formas con coordenadas que estén dentro del rectángulo viewBox.
5. Guarde el SVG con document.save() y compruebe que ninguna parte del gráfico esté recortada.

Ampliar gráficos SVG con un viewBox más pequeño

Un patrón común es mantener coordenadas de dibujo simples mientras se renderiza una imagen más grande. El siguiente ejemplo usa un viewport 300x150 con un viewBox 100x50 y luego dibuja un rectángulo en coordenadas del viewBox. El rectángulo se define como 80x30 unidades de coordenadas, pero aparece como 240x90 unidades renderizadas porque el viewport es tres veces mayor que el viewBox en ambas direcciones.

import os
from aspose.svg import SVGDocument

SVG_NS = "http://www.w3.org/2000/svg"

output_folder = "output/"
output_path = os.path.join(output_folder, "svg-viewbox-fixed.svg")
os.makedirs(output_folder, exist_ok=True)

with SVGDocument() as document:
    svg = document.root_element
    svg.set_attribute("width", "300")
    svg.set_attribute("height", "150")
    svg.set_attribute("viewBox", "0 0 100 50")

    rect = document.create_element_ns(SVG_NS, "rect")
    rect.set_attribute("x", "10")
    rect.set_attribute("y", "10")
    rect.set_attribute("width", "80")
    rect.set_attribute("height", "30")
    rect.set_attribute("rx", "4")
    rect.set_attribute("fill", "#2e86de")
    svg.append_child(rect)

    document.save(output_path)

La salida mantiene las proporciones del rectángulo porque la relación del viewport 300:150 coincide con la relación del viewBox 100:50. SVG amplía el sistema de coordenadas de usuario por el mismo factor en los ejes x e y, de modo que el rectángulo se ve más grande en pantalla pero conserva sus proporciones. En la práctica, esto permite diseñar un icono, gráfico o diagrama con números pequeños y cómodos, y renderizarlo a mayor tamaño sin reescribir cada coordenada.

La ilustración compara el mismo rectángulo dentro del mismo viewport renderizado 300x150. La parte (a) usa viewBox="0 0 300 150", por lo que una unidad de coordenadas corresponde a una unidad renderizada y el rectángulo 80x30 permanece pequeño. La parte (b) usa viewBox="0 0 100 50", por lo que SVG amplía tres veces el sistema de coordenadas más pequeño para llenar el mismo viewport. El rectángulo usa los mismos valores de código, pero aparece mucho más grande.

Desplazar el área visible de coordenadas

Los dos primeros valores de viewBox pueden ser negativos o distintos de cero. No mueven una sola forma. Mueven la ventana visible de coordenadas sobre el lienzo SVG. Esto es útil cuando los gráficos generados usan coordenadas alrededor de un punto central o cuando necesita espacio alrededor de una forma cuyas coordenadas cruzan cero.

En el siguiente ejemplo, viewBox="-60 -60 120 120" hace que la coordenada (0, 0) aparezca en el centro del viewport cuadrado. El área visible empieza en x=-60, y=-60, y se extiende 120 unidades hacia la derecha y 120 unidades hacia abajo.

import os
from aspose.svg import SVGDocument

namespace_uri = "http://www.w3.org/2000/svg"

output_folder = "output/"
output_path = os.path.join(output_folder, "svg-viewbox-shifted.svg")
os.makedirs(output_folder, exist_ok=True)

with SVGDocument() as document:
    svg = document.root_element
    svg.set_attribute("width", "240")
    svg.set_attribute("height", "240")
    svg.set_attribute("viewBox", "-60 -60 120 120")

    x_axis = document.create_element_ns(namespace_uri, "line")
    x_axis.set_attribute("x1", "-50")
    x_axis.set_attribute("y1", "0")
    x_axis.set_attribute("x2", "50")
    x_axis.set_attribute("y2", "0")
    x_axis.set_attribute("stroke", "#0071aa")
    x_axis.set_attribute("stroke-width", "3")
    svg.append_child(x_axis)

    marker = document.create_element_ns(namespace_uri, "circle")
    marker.set_attribute("cx", "0")
    marker.set_attribute("cy", "0")
    marker.set_attribute("r", "25")
    marker.set_attribute("fill", "#00aaaa")
    marker.set_attribute("stroke", "#006863")
    marker.set_attribute("stroke-width", "5")
    svg.append_child(marker)

    document.save(output_path)

Aquí el centro del área visible es la coordenada (0, 0). El eje horizontal va de x=-50 a x=50, y el círculo está centrado exactamente en el origen. Este patrón es útil para iconos, marcadores, diagramas polares y símbolos generados que son más fáciles de calcular alrededor de un centro.

La ilustración compara dos formas de mostrar un círculo cuyo centro está en la coordenada (0, 0). La parte (a) usa viewBox="0 0 240 240", por lo que (0, 0) queda en la esquina superior izquierda y gran parte del círculo se recorta fuera del viewport. La parte (b) usa viewBox="-60 -60 120 120", por lo que el área visible de coordenadas empieza en (-60, -60) y termina en (60, 60). Así (0, 0) queda en el centro del viewport y el círculo completo se ve.

Errores comunes y soluciones

Problema	Por qué ocurre	Solución
El SVG aparece vacío	Todos los elementos visibles están fuera del rectángulo de coordenadas definido por viewBox. Por ejemplo, un círculo con cx="200" no es visible en viewBox="0 0 100 100".	Mueva los elementos dentro del rango del viewBox o aumente width, height, min-x y min-y del viewBox para que queden dentro del área visible de coordenadas.
El gráfico se recorta	El elemento está solo parcialmente dentro del viewBox. SVG muestra la parte que cae dentro del rectángulo visible de coordenadas y oculta el resto.	Amplíe el viewBox o desplácelo con min-x y min-y para que toda la forma quepa en el área visible.
El gráfico se ve más grande de lo esperado	El ancho y alto del viewBox son menores que el viewport, lo que crea un efecto de acercamiento.	Use un viewBox mayor o reduzca los valores renderizados de width y height.
El gráfico se ve más pequeño de lo esperado	El ancho y alto del viewBox son mayores que el viewport, lo que crea un efecto de alejamiento.	Use un viewBox menor o aumente los valores renderizados de width y height.
La salida se ve estirada	La proporción del viewport no coincide con la proporción del viewBox. Por ejemplo, 300x150 y 100x100 tienen proporciones distintas.	Use proporciones coincidentes o defina preserveAspectRatio de forma intencional.
Las coordenadas resultan difíciles de manejar	El viewBox no coincide con la forma en que piensa el dibujo.	Elija un sistema de coordenadas cómodo, como 0 0 100 100 para iconos o coordenadas de negativas a positivas para formas simétricas.
El contorno se corta en el borde	La forma cabe, pero el trazo se dibuja mitad dentro y mitad fuera del límite de la forma. Un círculo tocando el borde del viewBox puede perder parte de su contorno.	Deje margen adicional dentro del viewBox o aleje la forma del borde al menos la mitad de stroke-width.

FAQ

¿Qué significa SVG viewBox?

viewBox define qué área rectangular de coordenadas del lienzo SVG debe mostrarse dentro del viewport SVG. En viewBox="0 0 100 50", el área visible empieza en (0, 0) e incluye 100 unidades de ancho y 50 unidades de alto. SVG escala después esa área 100x50 hacia arriba o hacia abajo para llenar el viewport renderizado.

¿Cuál es la diferencia entre viewport y viewBox?

El viewport es el área visible de salida definida por width y height. El viewBox es el rectángulo de coordenadas que se asigna a esa área visible. Para una explicación SVG más profunda, consulte SVG Coordinate Systems and Units y SVG viewBox.

¿width y height cambian las coordenadas SVG?

No. width y height controlan el tamaño del viewport renderizado. El viewBox controla el área de coordenadas usada por formas, texto y rutas. Un círculo con cx="50" sigue usando la coordenada 50, aunque el SVG se renderice con 100 píxeles o 1000 píxeles de ancho.

¿Por qué un viewBox más pequeño hace que el gráfico SVG se vea más grande?

Un viewBox más pequeño muestra un área de coordenadas menor y la ajusta al mismo viewport. Por ejemplo, ajustar viewBox="0 0 50 50" en un viewport 200x200 hace que cada unidad de coordenadas ocupe más espacio renderizado que ajustar viewBox="0 0 200 200" en el mismo viewport.

¿Por qué un viewBox más grande hace que el gráfico SVG se vea más pequeño?

Un viewBox más grande muestra más espacio de coordenadas dentro del mismo viewport. El renderizador tiene que ajustar más área de lienzo al mismo tamaño visible, por lo que cada unidad de coordenadas ocupa menos espacio renderizado y el gráfico parece menor.

¿Los valores de viewBox pueden ser negativos?

Sí. Los valores negativos de min-x o min-y son útiles cuando se dibuja alrededor de un punto central o cuando el gráfico necesita margen visible alrededor de coordenadas cercanas a cero.

Artículos relacionados

• Dibujar formas SVG en Python muestra cómo colocar formas visibles dentro de un sistema de coordenadas.
• Dibujar texto SVG en Python explica cómo funcionan las coordenadas y líneas base del texto en etiquetas SVG generadas.
• Crear iconos SVG en Python usa un viewBox compacto para gráficos de iconos generados.
• Convertir SVG a PNG en Python explica por qué valores de viewport ausentes o incorrectos pueden afectar la salida raster.