Annotation (pyobs.images.processors.annotation)

Circle

Draw a circle on an image, optionally interpreting the center in WCS coordinates.

This processor uses Pillow to render a circle on a pyobs.images.Image. The center coordinates (x, y) and the radius can be provided as numbers or strings that are resolved by pyobs.utils.image.PillowHelper. If wcs=True, the center coordinates are interpreted in world coordinates (e.g., sky coordinates) and converted to pixel coordinates using the image’s WCS, if available.

Parameters:

x (float | str) – X coordinate of the circle center. May be a numeric pixel position or a string that PillowHelper can resolve (e.g., a symbolic/relative specification). If wcs=True, interpreted as a world-coordinate value.
y (float | str) – Y coordinate of the circle center. Same rules as for x.
radius (float) – Circle radius. Resolved via PillowHelper to a pixel value.
fill (float | int | tuple[float | int, float | int, float | int] | None) – Fill color for the circle interior. Can be a single-channel value (grayscale) or a 3-tuple (RGB). If None, the interior is not filled. Default: None.
outline (float | int | tuple[float | int, float | int, float | int] | None) – Outline color for the circle boundary. Same type rules as fill. If None, no outline is drawn. Default: None.
width (int) – Outline line width in pixels. Default: 1.
wcs (bool) – If True, interpret x and y as world coordinates and convert to pixel coordinates using the image’s WCS. Default: False.
kwargs – Additional keyword arguments forwarded to pyobs.images.processor.ImageProcessor.

Behavior

Converts the input image to a Pillow image using pyobs.utils.image.PillowHelper.
Resolves x, y via PillowHelper.position(image, x, y, wcs) and radius via PillowHelper.value(image, radius).
Converts fill and outline to Pillow-compatible color values via PillowHelper.color(...).
Draws the circle using PIL.ImageDraw.Draw.circle([x, y], radius, fill=..., outline=..., width=...).
Converts the result back to a pyobs.images.Image with PillowHelper.to_image(image, im).
If both fill and outline are None, the rendered output will be unchanged.

Input/Output

Input: pyobs.images.Image
Output: pyobs.images.Image (copied) with the circle drawn onto the pixel data.

Configuration (YAML)

Draw a red outlined circle:

class: pyobs.images.processors.misc.Circle
x: 100
y: 150
radius: 50
outline: [255, 0, 0]
width: 3

Fill a green circle with no outline:

class: pyobs.images.processors.misc.Circle
x: 200
y: 300
radius: 30
fill: [0, 255, 0]
outline: null

Use WCS for the center (requires valid WCS in the image header):

class: pyobs.images.processors.misc.Circle
x: "10:00:00"     # example world-coordinate string resolvable by PillowHelper
y: "+20:00:00"
radius: 20
wcs: true
outline: [255, 255, 0]

Notes

Coordinate and value resolution depend on PillowHelper; supported string formats and semantics are defined there. If a value cannot be resolved, an exception may be raised.
When wcs=True, only x and y are interpreted in world coordinates; radius is resolved to a pixel value (no angular conversion is applied).
Color values typically use 0–255 per channel for 8-bit images; PillowHelper handles mapping for different dtypes/layouts.

Crosshair

Draw a crosshair (circle plus orthogonal lines) on an image, optionally using WCS coordinates.

This processor uses Pillow to render a crosshair symbol on a pyobs.images.Image. The crosshair consists of a circular outline of the given radius centered at (x, y) and horizontal/vertical lines crossing the center, each extending to the circle’s radius. The center coordinates may be specified in pixel space or, if wcs=True, interpreted as world coordinates and transformed to pixels via the image’s WCS.

Parameters:

x (float) – X coordinate of the crosshair center. If wcs=True, interpreted as a world-coordinate value and converted to pixel coordinates.
y (float) – Y coordinate of the crosshair center. Same rules as for x.
radius (float) – Crosshair radius in pixels. Determines both the circle size and the half-length of the crosshair lines.
color (float | int | tuple[float | int, float | int, float | int] | None) – Color used for the circle outline and the crosshair lines. Can be a single-channel value (grayscale) or a 3-tuple (RGB). If None, the library’s default color is used. Default: None.
wcs (bool) – If True, interpret x and y as world coordinates and convert them to pixel coordinates using the image’s WCS. Default: False.
kwargs – Additional keyword arguments forwarded to pyobs.images.processor.ImageProcessor.

Behavior

Converts the input to a Pillow image via pyobs.utils.image.PillowHelper.from_image.
Resolves the center position with PillowHelper.position(image, x, y, wcs) and the color with PillowHelper.color(color).
Draws: - A circle centered at (x, y) with radius radius and outline color. - A horizontal line from x - radius to x + radius at y. - A vertical line from y - radius to y + radius at x.
The line width is set to int(radius / 10.0).
Converts the Pillow image back to a pyobs.images.Image via PillowHelper.to_image(image, im).

Input/Output

Input: pyobs.images.Image
Output: pyobs.images.Image (copied) with the crosshair drawn onto the pixel data.

Configuration (YAML)

Pixel coordinates:

class: pyobs.images.processors.misc.Crosshair
x: 250
y: 300
radius: 40
color: [255, 255, 0]   # yellow

WCS coordinates for the center (requires valid WCS in the image):

class: pyobs.images.processors.misc.Crosshair
x: 150.1234          # example RA/longitude-like value resolvable by PillowHelper
y: -20.5678          # example Dec/latitude-like value resolvable by PillowHelper
radius: 25
color: [0, 255, 0]
wcs: true

Notes

When wcs=True, only x and y are interpreted in world coordinates; radius is treated as a pixel length.
Color representation and supported coordinate/value formats depend on pyobs.utils.image.PillowHelper.
The line width scales with radius and is not independently configurable.

Text

Draw text on an image at a specified position, optionally using WCS coordinates and header-based formatting.

This processor uses Pillow to render text onto a pyobs.images.Image. The text string may include Python str.format placeholders that are filled from the image’s FITS header. The position can be given in pixel coordinates or, if wcs=True, interpreted as world coordinates and converted to pixels using the image’s WCS, if available.

Parameters:

x (float) – X coordinate for the text anchor position. If wcs=True, interpreted as a world-coordinate value and converted to pixel coordinates.
y (float) – Y coordinate for the text anchor position. Same rules as for x.
text (str) – The text to render. Supports Python format fields referencing header keys, e.g., "{OBJECT} {FILTER}".
font (str) – Optional path to a TrueType font file. If provided, the font is loaded via PIL.ImageFont.truetype(font, font_size). Default: None.
font_size (float) – Font size in points for the TrueType font; if no font is provided, the size may be applied via Pillow’s draw.text where supported. Default: 10.
fill (float | int | tuple[float | int, float | int, float | int] | None) – Text fill color. Can be a single-channel value (grayscale) or a 3-tuple (RGB). If None, Pillow’s default color is used. Default: None.
anchor (str) – Text anchor alignment (e.g., "la", "mm"). See Pillow’s documentation for valid values and semantics. Default: None.
spacing (int) – Number of pixels between lines when text contains newlines. Default: 4.
align (str) – Multiline text alignment; one of "left", "center", "right". Default: "left".
direction (str) – Text direction; e.g., "ltr" (left-to-right), "rtl" (right-to-left), or "ttb" (top-to-bottom), if supported by Pillow. Default: None.
wcs (bool) – If True, interpret x and y as world coordinates and convert to pixel coordinates using the image’s WCS. Default: False.
kwargs – Additional keyword arguments forwarded to pyobs.images.processor.ImageProcessor.

Behavior

Converts the input image to a Pillow image via pyobs.utils.image.PillowHelper.from_image.
Resolves the position with PillowHelper.position(image, x, y, wcs) and the fill color with PillowHelper.color(fill).
Attempts to format text using self._text.format(**image.header); if a placeholder key is missing, falls back to the original self._text without formatting.
If font was provided, loads a TrueType font with the specified font_size; otherwise, uses Pillow’s default font. The call to draw.text includes the configured parameters (fill, font, anchor, spacing, align, direction, font_size).
Converts the Pillow image back to a pyobs.images.Image with PillowHelper.to_image(image, im).

Input/Output

Input: pyobs.images.Image
Output: pyobs.images.Image (copied) with the text drawn onto the pixel data.

Configuration (YAML)

Draw static text in pixel coordinates:

class: pyobs.images.processors.misc.Text
x: 50
y: 40
text: "Hello, world!"
fill: [255, 255, 255]   # white
align: "left"

Use FITS header fields in the text:

class: pyobs.images.processors.misc.Text
x: 10
y: 20
text: "{OBJECT}  {FILTER}  exp={EXPTIME}s"
fill: [255, 255, 0]     # yellow

Specify a TrueType font and size:

class: pyobs.images.processors.misc.Text
x: 100
y: 100
text: "Center"
font: "/usr/share/fonts/truetype/DejaVuSans.ttf"
font_size: 14
anchor: "mm"            # center the text at (x, y)

Use WCS coordinates for placement (requires valid WCS):

class: pyobs.images.processors.misc.Text
x: 150.1234
y: -20.5678
text: "{OBJECT}"
wcs: true
fill: [0, 255, 0]

Notes

Header-based formatting uses Python’s str.format mechanism with image.header as the source of values. Missing keys are ignored and the unformatted text is used.
Color representation and supported value formats depend on pyobs.utils.image.PillowHelper.
The anchor option controls how the text is positioned relative to (x, y); refer to Pillow’s documentation for the available anchor codes.
If no font is provided, Pillow’s default font is used. When a TrueType font is specified, font_size sets the size at loading time; some Pillow versions may also support a font_size parameter to draw.text.