ImageUtil
Loads images from a classpath resource, a URL or a local file through one
predictable API, then offers common view-shaping helpers (scaled, circular,
rounded ImageViews) and lightweight pure-Java pixel processing
(grayscale, node snapshots) — all on the native platform, no extra deps.
Carga imágenes desde un recurso del classpath, una URL o un archivo local a
través de una sola API predecible, y luego ofrece ayudantes comunes de modelado
de vistas (ImageViews escaladas, circulares, redondeadas) y
procesamiento de píxeles ligero en Java puro (escala de grises, capturas de
nodos) — todo en la plataforma nativa, sin dependencias extra.
Smart location resolutionResolución inteligente de ubicaciones
The loader is deliberately forgiving: a location containing a URI scheme
(https://, file:) is used verbatim; anything else
is first resolved against the classpath, then handed to JavaFX as a
fallback. So "/img/logo.png", a remote URL, and a local file
path all work through the same call.
El loader es deliberadamente tolerante: una ubicación que contiene un esquema
de URI (https://, file:) se usa tal cual; cualquier
otra cosa se resuelve primero contra el classpath y luego se entrega a JavaFX
como alternativa. Así "/img/logo.png", una URL remota y una ruta de
archivo local funcionan todas con la misma llamada.
Quick startInicio rápido
Image logo = ImageUtil.load("/img/logo.png"); // classpath
Image remote = ImageUtil.load("https://example.com/a.png"); // URL
Image opt = ImageUtil.loadOrNull("/img/maybe.png"); // null if missing
ImageView avatar = ImageUtil.circularView(logo, 40); // 80×80 circle
ImageView card = ImageUtil.roundedView(logo, 200, 120, 16);
ImageView gray = ImageUtil.view(ImageUtil.toGrayscale(logo));LoadingCarga
Loads from classpath / URL / file. Throws IllegalArgumentException if the location is null/blank or the image can't be loaded.Carga desde classpath / URL / archivo. Lanza IllegalArgumentException si la ubicación es null/en blanco o la imagen no se puede cargar.
Rescales at load time (more memory-efficient than loading full size then scaling). Pass 0 for a dimension to infer it from the other while preserving ratio.Reescala al momento de la carga (más eficiente en memoria que cargar a tamaño completo y luego escalar). Pasa 0 en una dimensión para inferirla de la otra preservando la proporción.
Loads a classpath resource relative to anchor — handy for images packaged next to a specific class. Throws if the resource is missing/unreadable.Carga un recurso del classpath relativo a anchor — útil para imágenes empaquetadas junto a una clase específica. Lanza excepción si el recurso falta o no se puede leer.
Returns null instead of throwing when the image is missing/unreadable — for optional decorations where absence is fine.Devuelve null en vez de lanzar excepción cuando la imagen falta o no se puede leer — para decoraciones opcionales donde la ausencia está bien.
View shapingModelado de vistas
| MethodMétodo | ResultResultado |
|---|---|
view(image) | An ImageView with smoothing on.Un ImageView con suavizado activado. |
view(image, fitW, fitH) | Scaled to fit the box, aspect ratio preserved.Escalado para encajar en la caja, preservando la proporción. |
circularView(image, radius) | Clipped to a centered circle — perfect for avatars. radius must be positive.Recortado a un círculo centrado — perfecto para avatares. radius debe ser positivo. |
roundedView(image, w, h, arc) | Rounded-rectangle clip; w/h positive, arc clamped to ≥ 0.Recorte de rectángulo redondeado; w/h positivos, arc acotado a ≥ 0. |
Pixel processingProcesamiento de píxeles
A grayscale copy using standard luminance weights (0.299/0.587/0.114), leaving the original untouched. If the image can't be read, source is returned as-is.Una copia en escala de grises usando pesos de luminancia estándar (0.299/0.587/0.114), dejando intacto el original. Si la imagen no se puede leer, se devuelve source tal cual.
Renders any node to an image with a transparent background. Must run on the JavaFX Application Thread.Renderiza cualquier nodo a una imagen con fondo transparente. Debe ejecutarse en el JavaFX Application Thread.
Use load for required assets (fail fast on a typo) and loadOrNull for optional ones. toGrayscale on small or unreadable images returns the source unchanged rather than failing.Usa load para recursos obligatorios (falla rápido ante un error de tipeo) y loadOrNull para los opcionales. toGrayscale sobre imágenes pequeñas o ilegibles devuelve el origen sin cambios en vez de fallar.
RecommendationsRecomendaciones
Prefer the rescaling load(...) overload for large images you'll display small — it saves memory versus scaling an ImageView.Prefiere la sobrecarga de load(...) con reescalado para imágenes grandes que mostrarás en pequeño — ahorra memoria frente a escalar un ImageView.
Note: Message.loadIcon delegates here, so icon loading benefits from the same flexible resolution.Nota: Message.loadIcon delega aquí, así que la carga de iconos se beneficia de la misma resolución flexible.