losalamos.figures#

SVG and raster figure handling for export pipelines.

Provides classes for loading, manipulating, and exporting figures in SVG, PDF, PNG, and JPEG formats using Inkscape as the rendering backend.

Classes

`Figure`([name, alias])	Base class for figure objects.
`FigureSVG`([name, alias])	SVG figure with layer control and multi-format export.

class losalamos.figures.Figure(name='MyFig', alias='Fig')[source]#

Bases: DataSet

Base class for figure objects.

Extends DataSet with image utility methods for scaling, thumbnail generation, and format conversion.

load_data(file_data)[source]#

Load data from file.

Parameters:: file_data (str) – file path to data.

static scale_image(file_input, file_output, scale_factor, dpi=300)[source]#

Scale an image by a numerical factor while maintaining its original aspect ratio.

Parameters:

file_input (str) – Path to the source image file.
file_output (str) – Path where the scaled image will be saved.
scale_factor (float) – Multiplier for the image dimensions (e.g., 0.5 for half size).
dpi (int) – Resolution in dots per inch for the output file metadata. Default value = 300

Returns:

No value is returned.

Return type:

None

Note

The resizing process utilizes the Image.Resampling.LANCZOS filter to ensure high-quality downsampling or upsampling. The output is saved with a fixed quality compression of 95.

static make_thumbnail(file_input, file_output, size=(512, 512), figure_ratio=None, mode='crop', dpi=300, quality=85, background=(255, 255, 255))[source]#

Generate a lightweight JPEG thumbnail from an input image with resizing options.

Parameters:

file_input (str) – Path to the source image file.
file_output (str) – Path where the generated thumbnail will be saved.
size (tuple) – Target dimensions for the output image. Default value = (512, 512)
figure_ratio (tuple) – [optional] Aspect ratio used to calculate target height from width.
mode (str) – Resizing strategy, either crop to fill dimensions or fit to pad. Default value = crop
dpi (int) – Resolution in dots per inch for the output file. Default value = 300
quality (int) – JPEG compression quality from 1 to 100. Default value = 85
background (tuple) – RGB color used for padding when mode is fit. Default value = (255, 255, 255)

Returns:

No value is returned.

Return type:

None

Note

The function automatically converts non-compatible image modes to RGB to ensure JPEG compatibility. If figure_ratio is provided as (width, height), it overrides the height specified in the size parameter.

static image_to_jpeg(file_input, file_output, quality=95, dpi=300)[source]#

Convert an image file to JPEG format with specified quality and resolution.

Parameters:

file_input (str) – Path to the input image file.
file_output (str) – Path where the output JPEG will be saved.
quality (int) – Compression quality from 1 to 100. Default value = 95
dpi (int) – Resolution in dots per inch. Default value = 300

Returns:

None

Return type:

NoneType

class losalamos.figures.FigureSVG(name='MySVG', alias='SVG')[source]#

Bases: Figure

SVG figure with layer control and multi-format export.

Loads an Inkscape SVG file and exposes methods to manipulate layer visibility and export the drawing to SVG, PDF, PNG, or JPEG via Inkscape subprocess calls.

Parameters:

name (str) – Internal object name. Default value = MySVG
alias (str) – Short display alias. Default value = SVG

Note

All export methods (to_svg, to_pdf, to_image) operate on a temporary copy of the source file, leaving the original untouched.

Warning

Requires inkscape to be installed and available in the system PATH.

load_data(file_data)[source]#

Load and parse SVG XML data from a file path into the object instance.

Parameters:: file_data (str) – The file system path pointing to the source SVG data.
Returns:: No value is returned.
Return type:: None

Important

This method converts the input path to an absolute path and utilizes an etree.XMLParser with huge_tree enabled to handle large datasets. It populates the tree and data attributes before triggering an internal update call.

save()[source]#

Serializes the current XML tree and writes it to the local file system.

Returns:: Always returns None
Return type:: None

export(folder, filename, data_suffix=None)[source]#

Saves the current SVG data to a specific directory with an optional filename suffix.

Parameters:

folder (str) – The destination directory path
filename (str) – The base name of the output file
data_suffix (str) – [optional] An additional string appended to the filename

Returns:

Always returns None

Return type:

None

Note

This method temporarily overrides the internal file_data path to execute the save operation before restoring the original path.

hide_layer(label='frames')[source]#

Modifies the style attribute of a specific layer to make it invisible.

Parameters:: label (str) – The Inkscape label of the layer to hide. Default value = frames
Returns:: Always returns None
Return type:: None

hide_layers(labels)[source]#

Hide multiple layers based on a list of provided labels.

Parameters:: labels (list) – A list of layer labels to be hidden.
Returns:: None
Return type:: NoneType

show_layer(label='frames')[source]#

Modifies the style attribute of a specific layer to make it visible.

Parameters:: label (str) – The Inkscape label of the layer to display. Default value = frames
Returns:: Always returns None
Return type:: None

show_layers(labels, inclusive=True)[source]#

Show specified layers and optionally hide all others.

Parameters:

labels (list) – A list of layer labels to be made visible.
inclusive (bool) – Determines if other layers stay visible or are hidden. Default value = True

Returns:

None

Return type:

NoneType

Note

If inclusive is set to True, the specified layers are made visible without affecting others. If False, the method performs a “show only” operation by hiding any layer not present in the labels list.

get_layers()[source]#

Return a dictionary of top-level Inkscape layers indexed by their label.

Returns:: Dictionary mapping layer labels to lxml Elements
Return type:: dict[str, etree.Element]

Note

Only <g> elements that are direct children of the root <svg> element and have inkscape:groupmode=”layer” are considered.

get_layers_labels()[source]#: Return the list of layers labels

set_page_opacity(opacity=1.0)[source]#

Set the Inkscape page background opacity.

Parameters:: opacity (float) – Opacity value in range [0.0, 1.0] (1=opaque)

set_page_color(color='#ffffff')[source]#

Set the Inkscape page background color.

Parameters:: color (str) – Hex color string (e.g. ‘#ffffff’)

set_element_color(element, fill=None, stroke=None)[source]#

Set fill and/or stroke color of an SVG element.

Parameters:

element – lxml SVG element
fill – Fill color (e.g. ‘#00ff00’) or None
stroke – Stroke color or None

get_layer_elements(label, drawable_only=True)[source]#

Return drawable SVG elements from a layer, indexed by element ID.

Parameters:

label – Inkscape layer label
drawable_only – Exclude non-drawable tags (image, defs, etc.)

Returns:

dict[str, dict]

to_image(file_output=None, dpi=300, crop_id=None, hide_layers=None, show_layers=None, show_inclusive=True, to_jpeg=False, remove_png=True)[source]#

Export the current drawing as an image file, optionally adjusting layers and format.

Parameters:

file_output (str or pathlib.Path) – [optional] The destination path for the exported image. If None, it defaults to the source file name.
dpi (int) – Dots per inch for the export resolution. Default value = 300
crop_id (str) – [optional] The specific object ID to crop instead of the whole page.
hide_layers (list) – [optional] List of layer labels to set to hidden before export.
show_layers (list) – [optional] List of layer labels to set to visible before export.
show_inclusive (bool) – Whether to show layers inclusively when using show_layers. Default value = True
to_jpeg (bool) – Convert the final output from PNG to JPEG format. Default value = False
remove_png (bool) – Delete the intermediate PNG file if to_jpeg is True. Default value = True

Returns:

The path to the generated image file.

Return type:

pathlib.Path

Warning

This method requires inkscape to be installed and available in the system PATH.

Note

The method modifies layer visibility before export based on the provided labels. It saves the current state of the drawing to disk before calling Inkscape via a subprocess to perform the rendering.

to_pdf(file_output=None, crop_id=None, hide_layers=None, show_layers=None, show_inclusive=True)[source]#

Export the current drawing as a PDF file.

This method uses a two-stage vector export pipeline when crop_id is provided:

original.svg
-> temporary cropped svg -> final pdf

This approach preserves SVG clipping semantics more reliably than direct PDF export from Inkscape.

Parameters:

file_output (str or pathlib.Path) – [optional] Destination PDF path.
crop_id (str) – [optional] Object ID used for cropping/export.
hide_layers (list) – [optional] List of layer labels to hide.
show_layers (list) – [optional] List of layer labels to show.
show_inclusive (bool) – Whether show_layers should act inclusively.

Returns:

Path to generated PDF file.

Return type:

pathlib.Path

Warning

Requires inkscape available in system PATH.

to_svg(file_output=None, crop_id=None, hide_layers=None, show_layers=None, show_inclusive=True)[source]#

Export the current drawing as an SVG file.

Parameters:

file_output (str or pathlib.Path) – [optional] Destination SVG path. Defaults to the source file name.
crop_id (str) – [optional] Object ID to crop the export to.
hide_layers (list) – [optional] List of layer labels to hide before export.
show_layers (list) – [optional] List of layer labels to show before export.
show_inclusive (bool) – Whether to show layers inclusively. Default value = True

Returns:

Path to the generated SVG file.

Return type:

pathlib.Path

Raises:

FileExistsError – If file_output resolves to the same path as the source file.

Warning

This method requires inkscape to be installed and available in the system PATH.