Images

Image formats and texture handling

Supported formats

Supported conversion inputs include BMP, TGA, TIFF, WebP, GIF, PNM, HDR, DDS, ICO, QOI and EXR, in addition to JPG/PNG. Unsupported codecs, missing files and corrupt input images are errors. Animation is reduced to the decoded image/frame.

Reference or copy source textures

--images auto keeps original image references when output and input are in the same folder and the image needs no conversion. It copies images otherwise. --images keep explicitly references original files using relative, escaped URIs, even across folders; --images copy explicitly copies images. Sources are never modified. Conversion always writes a new image in the output folder, even with --images keep.

When to convert

--convert-images auto does not convert JPG/JPEG or PNG; all other source formats require conversion. --convert-images true converts every referenced image. --convert-images false forbids conversion: encountering a non-JPG/PNG image is an error and aborts the import. Both --convert-images=false and --convert-images false are accepted.

Output format, quality and transparency

Conversion defaults to --image-format jpg --image-quality 95. PNG conversion is lossless and keeps alpha; quality only applies to JPEG. JPEG composites transparent pixels onto white and reports this explicitly. Choosing a format does not itself force conversion of already-supported files: use --convert-images true for that.

Examples

objtools import mesh.obj --images keep -o elsewhere/mesh.gltf
objtools import mesh.obj --convert-images true --image-format jpg --image-quality 95
objtools import mesh.obj --convert-images true --image-format png

Image memory use

Conversion decodes one image at a time with the image library's allocation limits (default 512 MiB); its memory usage depends on image dimensions, separately from the bounded geometry pipeline. Unconverted JPG/PNG images use header checks and byte copies, without decoding all pixels.

Conversion · Documentation home