FLM Feature flm.feature.graphics

Provides the \includegraphics macro and a simple graphics resource provider. The GraphicsResource data class carries image metadata (URL, dimensions, srcset), while FeatureSimplePathGraphicsResourceProvider resolves graphics paths by passing them through unchanged as source URLs.

class flm.feature.graphics.GraphicsResource(src_url, *, srcset=None, graphics_type=None, dpi=None, pixel_dimensions=None, physical_dimensions=None, source_info=None)

Bases: object

Collects information about a graphics resource, i.e., an external image.

Attributes:

src_url

A string containing the path or full URL at which the graphics resource should be found. This is the path or URL that should be included in the rendered output.

This path might differ from the path the original graphics source was found, if you’re using the FLM routines as part of a processing pipeline that produces FLM output along with e.g. optimized graphics (e.g., if you’re producing a page on a website).

graphics_type

One of ‘raster’ or ‘vector’.

dpi

The dots per inch (or pixels per inch) resolution of the source image.

This property is only used if the graphics_type is ‘raster’.

pixel_dimensions

A tuple (width_px, height_px) storing the pixel dimensions of the raster source image.

This property is only used if the graphics_type is ‘raster’.

physical_dimensions

A tuple (width_pt, height_pt) storing the dimensions at which the image is meant to be produced on a physical display. A dimension of 1 pt is defined to be 1/72 in, i.e., 72pt = 1in.

This property is used both for ‘raster’ and ‘vector’ graphics types. For ‘raster’ graphics types, this property can normally be deduced from the ‘pixel_dimensions’ and the ‘dpi’ attributes.

In case the image actually has different dpi resolutions along the X and Y directions, the physical_dimensions can incorporate this difference while the ‘dpi’ field might be unreliable or incomplete. In such a case, the relation is physical_dimensions = ( pixel_dimensions[0]*72/x_dpi, pixel_dimensions[1]*72/y_dpi )

srcset

Possible alternative source URL to retrieve the final image resource (URLs to be included in rendered result), meant for use in <img srcset=… >.

This attribute is a LIST of DICTs of the form [ { 'source': <source-url-1>, 'pixel_density': <pixel_density-1> }, { 'source': <source-url-2>, 'pixel_density': <pixel-density-2> }, ... ]. The <pixel-density> should be a number (integer or floating point), e.g., 2 for a pixel density of 2x. For a source item, you may omit the ‘pixel_density’, in which case browsers will interpret this the same way as ‘pixel_density’: 1.

See also: The <srcset> HTML tag.

source_info

This attribute can be set to a dictionary to store any additional information about where this graphics resource was resolved/found.

This attribute is not set or used by the core FLM routines. By default, this attribute is None.

asdict()

class flm.feature.graphics.SimpleIncludeGraphicsMacro(macroname, **kwargs)

Bases: FLMMacroSpecBase

Spec info for the \includegraphics macro.

Parses an optional [options] argument and a mandatory {graphics_path} argument. At render time, delegates to a graphics_resource_provider feature to resolve the path into a GraphicsResource, then calls fragment_renderer.render_graphics_block().

is_block_level: bool | None = True

If this flag is set to True, then elements of this type are always parsed as separate block-level elements (e.g., a section heading, an enumeration list, etc.)

If this flag is None, then the spec does not commit as to whether the node produces a block-level or inline-level element. It is strongly recommended you then manually set the flm_is_block_level attribute on the node object to True or False, since the default implementation of finalize_node() won’t be able to do it.

allowed_in_standalone_mode: bool = False

Can’t allow this macro in standalone mode; rendering this macro requires a graphics resource provider, which in turn must be provided by a document.

get_flm_doc()

postprocess_parsed_node(node)

render(node, render_context)

recompose_pure_latex(node, recomposer)

class flm.feature.graphics.FeatureSimplePathGraphicsResourceProvider

Bases: Feature

Default graphics resource provider that resolves graphics paths by using them directly as source URLs. Subclass this feature and override the RenderManager to provide custom resolution logic such as srcset generation or physical dimension lookup.

feature_name: str | None = 'graphics_resource_provider'

A name that should uniquely identify this feature.

feature_title: str | None = 'Include external graphics'

Descriptive name or title for this feature.

class RenderManager(feature_document_manager, render_context, **kwargs)

Bases: FeatureRenderManagerBase

get_graphics_resource(graphics_path, resource_info)

flm.feature.graphics.FeatureClass = <class 'flm.feature.graphics.FeatureSimplePathGraphicsResourceProvider'>

Default graphics resource provider that resolves graphics paths by using them directly as source URLs. Subclass this feature and override the RenderManager to provide custom resolution logic such as srcset generation or physical dimension lookup.