Image import and cropping#

Purpose and concepts#

image defines external picture material; add determines size, crop and fit. A crop box uses normalized 0–1 image coordinates. Cropping occurs before fitting to size.

Minimal complete example#

Run this file directly with laymesh validate or laymesh render; it contains its own canvas and required definitions.

1# Minimal complete example: image2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

# Minimal complete example: image
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

1# Minimal complete example: image2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

# Minimal complete example: image
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

Dependencies

examples/assets/photo.png
examples/manual/image.lay

Parameters and default behavior#

Unitless geometry uses the canvas unit; unitless type and stroke sizes use pt. Explicit call parameters override inherited/theme defaults. The linked interface reference lists accepted types, choices and defaults per parameter.

Composition#

Place a full image and a detail from the same definition. contain keeps all content, cover fills the box and clips overflow, and stretch changes aspect ratio. One size dimension plus auto preserves the cropped aspect.

7picture = image(src="../assets/sample.png")8first = page.add(picture,size=(53 mm, auto), target=page.top_left, offset=(7 mm, 26 mm))9page.add(picture,size=(44 mm, auto), crop=box(offset=(0.4, 0), size=(0.6, 1)),10         target=first.top_right, offset=(9 mm, 0 mm))

picture = image(src="../assets/sample.png")
first = page.add(picture,size=(53 mm, auto), target=page.top_left, offset=(7 mm, 26 mm))
page.add(picture,size=(44 mm, auto), crop=box(offset=(0.4, 0), size=(0.6, 1)),
         target=first.top_right, offset=(9 mm, 0 mm))

1# Gallery: images / crop2page = canvas(name="Independent crop", size=(120 mm, 80 mm), background="#f7f9fc")3font = "DejaVu Sans"4heading = text(content="Independent crop", font_family=font, font_size=14 pt, color="#203864")5page.add(heading, target=page.top_left, offset=(7 mm, 5 mm))6# BEGIN DEMO7picture = image(src="../assets/sample.png")8first = page.add(picture,size=(53 mm, auto), target=page.top_left, offset=(7 mm, 26 mm))9page.add(picture,size=(44 mm, auto), crop=box(offset=(0.4, 0), size=(0.6, 1)),10         target=first.top_right, offset=(9 mm, 0 mm))11# END DEMO

# Gallery: images / crop
page = canvas(name="Independent crop", size=(120 mm, 80 mm), background="#f7f9fc")
font = "DejaVu Sans"
heading = text(content="Independent crop", font_family=font, font_size=14 pt, color="#203864")
page.add(heading, target=page.top_left, offset=(7 mm, 5 mm))
# BEGIN DEMO
picture = image(src="../assets/sample.png")
first = page.add(picture,size=(53 mm, auto), target=page.top_left, offset=(7 mm, 26 mm))
page.add(picture,size=(44 mm, auto), crop=box(offset=(0.4, 0), size=(0.6, 1)),
         target=first.top_right, offset=(9 mm, 0 mm))
# END DEMO

Dependencies

examples/gallery/assets/sample.png
examples/gallery/images/crop.lay

Common errors and limits#

SVG input is allowlisted, and SVG crop is unsupported. TIFF accepts single-page unsigned 8/16-bit grayscale or RGB, with optional alpha; multipage, signed and floating-point TIFF are unsupported. GIF and animated WebP use the first frame; 16-bit intensities are not stretched. Pictures provide bounds without pixel-derived path or ink.

Individual functions#

image#

Define reusable image material from a local file. add controls size, crop and contain/cover/stretch fitting; paths resolve relative to the defining file. Accepts PNG, JPEG, BMP, WebP, GIF, ICO, PNM, TGA, safe SVG, and single-page unsigned 8/16-bit grayscale/RGB TIFF with optional alpha. GIF and animated WebP use the first frame; 16-bit intensities are not stretched.

Returns: material

Required inputs: src.

Minimal complete source · Composition source · All parameters

Detailed behavior and further examples#

Parameters#

Parameter	Purpose	Default or requirement
`src`	Image path	Required
`fit`	Image frame fit	contain / cover / stretch
`crop`	Source crop	Optional

Common usage#

Supported inputs are PNG, JPEG, BMP, WebP, GIF, ICO, PNM (PBM/PGM/PPM/PAM), TGA, safe SVG, and single-page unsigned 8/16-bit grayscale or RGB TIFF with optional alpha. GIF and animated WebP use the first frame; ICO uses the decoder-selected primary image. crop selects source content; contain preserves the full image, cover fills and crops, and stretch scales each dimension independently. Instances remain independent.

Complete parameters and rules

Text and fonts · Resource paths · Mathematical formulas · Shapes and paths · Fills, gradients and outlines

Alpha and 16-bit intensity#

Transparent and partially transparent pixels survive image import, image paint and cropping when supported by the source format. Associated TIFF alpha is made straight before color conversion. Intermediate PNGs and crops retain 16-bit depth, including a 16-bit ICC conversion path. Display and 8-bit exports quantize the full intensity range without per-image contrast stretching. Alpha composites with underlying shapes in SVG, PNG and PDF.