Struct ImageElem

pub struct ImageElem {
    pub source: Derived<DataSource, Bytes>,
    /* private fields */
}

A raster or vector graphic.

You can wrap the image in a [figure] to give it a number and caption.

Like most elements, images are block-level by default and thus do not integrate themselves into adjacent paragraphs. To force an image to become inline, put it into a [box].

Example

#figure(
  image("molecular.jpg", width: 80%),
  caption: [
    A step in the molecular testing
    pipeline of our lab.
  ],
)

Fields

source: Derived<DataSource, Bytes>

Implementations

impl ImageElem

pub fn new(source: Derived<DataSource, Bytes>) -> Self

Create a new instance of the element.

pub fn with_format(self, format: Smart<ImageFormat>) -> Self

Builder-style setter for the format field.

pub fn with_width(self, width: Smart<Rel<Length>>) -> Self

Builder-style setter for the width field.

pub fn with_height(self, height: Sizing) -> Self

Builder-style setter for the height field.

pub fn with_alt(self, alt: Option<EcoString>) -> Self

Builder-style setter for the alt field.

pub fn with_fit(self, fit: ImageFit) -> Self

Builder-style setter for the fit field.

pub fn with_scaling(self, scaling: Smart<ImageScaling>) -> Self

Builder-style setter for the scaling field.

pub fn with_icc(self, icc: Smart<Derived<DataSource, Bytes>>) -> Self

Builder-style setter for the icc field.

pub fn push_format(&mut self, format: Smart<ImageFormat>)

Setter for the format field.

pub fn push_width(&mut self, width: Smart<Rel<Length>>)

Setter for the width field.

pub fn push_height(&mut self, height: Sizing)

Setter for the height field.

pub fn push_alt(&mut self, alt: Option<EcoString>)

Setter for the alt field.

pub fn push_fit(&mut self, fit: ImageFit)

Setter for the fit field.

pub fn push_scaling(&mut self, scaling: Smart<ImageScaling>)

Setter for the scaling field.

pub fn push_icc(&mut self, icc: Smart<Derived<DataSource, Bytes>>)

Setter for the icc field.

pub fn format(&self, styles: StyleChain<'_>) -> Smart<ImageFormat>

The image’s format.

By default, the format is detected automatically. Typically, you thus only need to specify this when providing raw bytes as the source (even then, Typst will try to figure out the format automatically, but that’s not always possible).

Supported formats are {"png"}, {"jpg"}, {"gif"}, {"svg"} as well as raw pixel data. Embedding PDFs as images is not currently supported.

When providing raw pixel data as the source, you must specify a dictionary with the following keys as the format:

• encoding (str): The encoding of the pixel data. One of:
  • {"rgb8"} (three 8-bit channels: red, green, blue)
  • {"rgba8"} (four 8-bit channels: red, green, blue, alpha)
  • {"luma8"} (one 8-bit channel)
  • {"lumaa8"} (two 8-bit channels: luma and alpha)
• width ([int]): The pixel width of the image.
• height ([int]): The pixel height of the image.

The pixel width multiplied by the height multiplied by the channel count for the specified encoding must then match the source data.

#image(
  read(
    "tetrahedron.svg",
    encoding: none,
  ),
  format: "svg",
  width: 2cm,
)

#image(
  bytes(range(16).map(x => x * 16)),
  format: (
    encoding: "luma8",
    width: 4,
    height: 4,
  ),
  width: 2cm,
)

pub fn width(&self, styles: StyleChain<'_>) -> Smart<Rel<Length>>

The width of the image.

pub fn height(&self, styles: StyleChain<'_>) -> Sizing

The height of the image.

pub fn alt(&self, styles: StyleChain<'_>) -> Option<EcoString>

A text describing the image.

pub fn fit(&self, styles: StyleChain<'_>) -> ImageFit

How the image should adjust itself to a given area (the area is defined by the width and height fields). Note that fit doesn’t visually change anything if the area’s aspect ratio is the same as the image’s one.

#set page(width: 300pt, height: 50pt, margin: 10pt)
#image("tiger.jpg", width: 100%, fit: "cover")
#image("tiger.jpg", width: 100%, fit: "contain")
#image("tiger.jpg", width: 100%, fit: "stretch")

pub fn scaling(&self, styles: StyleChain<'_>) -> Smart<ImageScaling>

A hint to viewers how they should scale the image.

When set to {auto}, the default is left up to the viewer. For PNG export, Typst will default to smooth scaling, like most PDF and SVG viewers.

Note: The exact look may differ across PDF viewers.

pub fn icc<'a>( &'a self, styles: StyleChain<'a>, ) -> &'a Smart<Derived<DataSource, Bytes>>

An ICC profile for the image.

ICC profiles define how to interpret the colors in an image. When set to {auto}, Typst will try to extract an ICC profile from the image.

pub fn format_in(styles: StyleChain<'_>) -> Smart<ImageFormat>

Access the format field in the given style chain.

pub fn width_in(styles: StyleChain<'_>) -> Smart<Rel<Length>>

Access the width field in the given style chain.

pub fn height_in(styles: StyleChain<'_>) -> Sizing

Access the height field in the given style chain.

pub fn alt_in(styles: StyleChain<'_>) -> Option<EcoString>

Access the alt field in the given style chain.

pub fn fit_in(styles: StyleChain<'_>) -> ImageFit

Access the fit field in the given style chain.

pub fn scaling_in(styles: StyleChain<'_>) -> Smart<ImageScaling>

Access the scaling field in the given style chain.

pub fn icc_in(styles: StyleChain<'_>) -> &Smart<Derived<DataSource, Bytes>>

Access the icc field in the given style chain.

pub fn set_format(format: Smart<ImageFormat>) -> Property

Create a style property for the format field.

pub fn set_width(width: Smart<Rel<Length>>) -> Property

Create a style property for the width field.

pub fn set_height(height: Sizing) -> Property

Create a style property for the height field.

pub fn set_alt(alt: Option<EcoString>) -> Property

Create a style property for the alt field.

pub fn set_fit(fit: ImageFit) -> Property

Create a style property for the fit field.

pub fn set_scaling(scaling: Smart<ImageScaling>) -> Property

Create a style property for the scaling field.

pub fn set_icc(icc: Smart<Derived<DataSource, Bytes>>) -> Property

Create a style property for the icc field.

impl ImageElem

pub fn decode( span: Span, data: Readable, format: Option<Smart<ImageFormat>>, width: Option<Smart<Rel<Length>>>, height: Option<Sizing>, alt: Option<Option<EcoString>>, fit: Option<ImageFit>, scaling: Option<Smart<ImageScaling>>, ) -> StrResult<Content>

Decode a raster or vector graphic from bytes or a string.

Trait Implementations

impl Capable for ImageElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for ImageElem

fn clone(&self) -> ImageElem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for ImageElem

fn construct(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Content>

Construct an element from the arguments.

impl Debug for ImageElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Fields for ImageElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

fn field(&self, id: u8) -> Result<Value, FieldAccessError>

Get the field with the given field ID.

fn field_with_styles( &self, id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for ImageElem

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for ImageElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for ImageElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl NativeScope for ImageElem

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl PartialEq for ImageElem

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for ImageElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for ImageElem

fn set(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Styles>

Parse relevant arguments into style properties for this element.