XLOADIMAGE(1)

📦 version 4.1, in ubuntu questing, ubuntu resolute, ubuntu stonking

💅 xloadimage(1) — General Commands Manual 🦋

okay so bestie, we're in the xloadimage cinematic universe now — this page covers xloadimage, xsetbg and xview, and it's a lot, but it's also lowkey iconic. buckle up, we're going section by section and we're not skipping a single crumb 💖

✨ NAME ✨

xloadimage, xsetbg, xview — load images into an X11 window or onto the root window 🖼️✨

🌸 SYNOPSIS 🌸

xloadimage [global_options] {[image_options] image ...}
xloadimage [global_options] [image_options] stdin < image

🎀 DESCRIPTION 🎀

Xloadimage displays images in an X11 window, loads them onto the root window, or writes them into a file. Many image types are recognised — run the -supported option if you wanna see the whole list, no gatekeeping here 🫶

If the filename stdin or - is given, xloadimage will read the image from standard input if this capability is supported by the loader for that image type (and ngl, most types do support reading from stdin, slay).

If the destination display cannot support the number of colors in the image, the image will be dithered (monochrome destination) or have its colormap reduced (color destination), as appropriate. You can also force this yourself with the -halftone, -dither, and -colors options. it's giving "we'll handle it, but you can also be dramatic about it" 💅

A variety of image manipulations can be specified, including gamma correction, brightening, clipping, dithering, depth-reduction, rotation, and zooming. Most of these manipulations have simple implementations; speed was opted for above accuracy. (the vibes were prioritized, fr fr.)

If you are viewing a large image in a window, the initial window will be at most 90% of the size of the display — unless the window manager does not correctly handle window size requests, or if you've used the -fullscreen option 🙈 You may move the image around in the window by dragging with the first mouse button. The cursor will indicate which directions you may drag, if any. You may exit the window by typing 'q' or '^C' when the keyboard focus is on the window. main character exit energy 👑

If more than one image file is specified on the command line, each image will be shown in order — except if -merge or -goto are being used 👀

A wide variety of common image manipulations can be done by mixing and matching the available options. See the section entitled HINTS FOR GOOD IMAGE DISPLAYS for some ideas 🌈

The -dump option causes an image to be written to a file rather than displayed after processing. This allows you to read an image, perform a number of processing operations on it, and save the resultant image. This also allows translation from any of the recognised image types into any of the formats that support dumping. it's giving glow-up pipeline ✨

Xsetbg is equivalent to xloadimage -onroot -quiet and xview is equivalent to xloadimage -view -verbose. same girl, different outfit 💅

🧚 RESOURCE CLASS 🧚

Xloadimage uses the resource class name Xloadimage for window managers which need this resource set. This name changed in version 2.00 and 2.01; some previous versions used the name XLoadImage (which was difficult to predict) or xloadimage (which conflicted with class naming conventions). messy era, but we moved on 🫶

👑 GLOBAL OPTIONS 👑

The following options affect the global operation of xloadimage. They may be specified anywhere on the command line. Additionally the -global option can be used to force an image option to apply to all images. obsessed with the flexibility honestly.

  • -border color — This sets the background portion of the window which is not covered by any images to be color. ✨
  • -configuration — Displays the image path, image suffixes, and supported filters which will be used when looking for and reading images. These are loaded from ~/.xloadimagerc and optionally from a systemwide file (normally /usr/lib/xloadimagerc). This replaces the -path option. 🎀
  • -default — Use the default root weave as the image. This option forces -onroot. If -default is used alone, it is the same as xsetroot with no arguments. If used in conjunction with -tile this option can be used to place images on the default root weave (see EXAMPLES below). 🌸
  • -debug — Talk to the X server in synchronous mode. This is useful for debugging. If an X error is seen while in this mode, a core will be dumped. 💀 (yes bestie, a whole core. be careful.)
  • -display display_name — X11 display name to send the image(s) to. 🖥️
  • -dump image_type[,option[=value]] dump_file — Rather than displaying the loaded and processed image, dump it into an image file of the specified type. For a list of image types that can be dumped, use the -supported option. Some image types have options that affect the format of the file that's created. See DUMP OPTIONS below. An image can be dumped in any supported dump format regardless of the original image type, so image file type translation is possible using this option. ✨
  • -fit — Force image to use the default visual and colormap. This is useful if you do not want technicolor effects when the colormap focus is inside the image window, but it may reduce the quality of the displayed image. This is on by default if -onroot or -windowid is specified. 💅
  • -fork — Fork xloadimage. This causes xloadimage to disassociate itself from the shell. This option automatically turns on -quiet. 🦋
  • -fullscreen — Use the entire screen to display images. If combined with -onroot, the image will be zoomed to fill the entire rootwindow. 🔥
  • -geometry WxH[{+-X}{+-}Y] — This sets the size of the window onto which the images are loaded to a different value than the size of the image. When viewing an image in a window, this can be used to reduce the size of the destination window. When loading an image onto the root window, this option controls the size of the pixmap which will be loaded onto the root. If the size is smaller than that of the display, the image will be replicated. 🌈
  • -goto image_name — Forces the next image to be displayed to be the image named image_name. This is useful for generating looped slideshows. If more than one image of the same name as the target exists on the argument list, the first in the argument list is used. 🎠
  • -help [option ...] — Give information on an option or list of options. If no option is given, a simple interactive help facility is invoked. 🫶
  • -identify — Identify the supplied images rather than display them. 🔍
  • -install — Forcibly install the image's colormap when the window is focused. This violates ICCCM standards and only exists to allow operation with naive window managers. Use this option only if your window manager does not install colormaps properly. > bestie, this one is a rule-breaker. it's literally built to break the rules. use with caution 💀
  • -list — List the images which are along the image path. 📋
  • -onroot — Load image(s) onto the root window instead of viewing in a window. This option automatically sets the -fit option. This is the opposite of -view. XSetbg has this option set by default. 👑
  • -path — Displays miscellaneous information about the program configuration. This option is obsolete and has been replaced by -configuration. (it's giving retired, but still showing up to the function 🙈)
  • -pixmap — Force the use of a pixmap as backing-store. This is provided for servers where backing-store is broken (such as some versions of the AIXWindows server). It may improve scrolling performance on servers which provide backing-store. 🧚
  • -private — Force the use of a private colormap. Normally colors are allocated shared unless there are not enough colors available. 💜
  • -quiet — Forces xloadimage and xview to be quiet. This is the default for xsetbg, but the others like to whistle. 🤫
  • -supported — List the supported image types. ⭐
  • -type type_name — Forces xloadimage to try to load the image as a particular file type rather than trying to guess. This often improves load performance noticeably. ⚡
  • -verbose — Causes xloadimage to be talkative, telling you what kind of image it's playing with and any special processing that it has to do. This is the default for xview and xloadimage. 🗣️
  • -version — Print the version number and patchlevel of this version of xloadimage. 🏷️
  • -view — View image(s) in a window. This is the opposite of -onroot and the default for xview and xloadimage. 🖼️
  • -visual visual_name — Force the use of a specific visual type to display an image. Normally xloadimage tries to pick the best available image for a particular image type. The available visual types are: DirectColor, TrueColor, PseudoColor, StaticColor, GrayScale, and StaticGray. Nonconflicting names may be abbreviated and case is ignored. 🌈
  • -windowid hex_window_id — Sets the background pixmap of a particular window ID. The argument must be in hexadecimal and must be preceded by "0x" (eg -windowid 0x40000b. This is intended for setting the background pixmap of some servers which use untagged virtual roots (eg HP-VUE), but can have other interesting applications. 👀

🎀 IMAGE OPTIONS 🎀

okay bestie so these are the ones that go right before an image. They're local, meaning they only apply to the image that comes after them. Not the whole squad. Just that one. 💅

  • -at X,Y — drops the image at these coordinates on the base image. And listen, if this is attached to the first image and you also said -onroot, then it lands at that spot on the display background instead. main character placement fr.
  • -background color — uses color as the background color instead of the default (which is usually white but honestly depends on the image type) when you're transferring a monochrome image onto a color display.
  • -brighten percentage — a percentage multiplier for a color image's colormap. More than 100 brightens, less than 100 darkens. glow up or fade out, your call ✨
  • -center — centers the image on the base image you loaded. If it's an option to the first image and you specified -onroot, it centers on the display background. symmetric queen.
  • -clip X,Y,W,H — clips the image before loading it. X and Y are the upper-left corner of the clip area, W and H are the extents. If W or H is zero, that gets read as "the rest of the image." no notes.
  • -colors n — sets the max number of colors used in the image. Basically a way to forcibly reduce the depth of an image. force it, bestie.
  • -delay secs — auto-advances to the next image after secs seconds. If you're trying to build a slideshow with multiple images, you probably wanna pair this with the -global switch. 🎞️
  • -dither — dithers a color image to monochrome using a Floyd-Steinberg dithering algorithm. This already happens by default when you're viewing color images on a monochrome display. It's slower than -halftone and it messes with image accuracy, but ngl it usually looks so much better.
  • -foreground color — uses color as the foreground color instead of black when transferring a monochrome image to a color display. Bonus: you can also use this to invert the foreground and background colors of a monochrome image. 🔄
  • -gamma display_gamma — sets the gamma correction for the display. Default is 1.0, and a typical display needs 2.0 to 2.5.
  • -global — forces the following option to apply to all images instead of just one specific image. Local image options will temporarily override anything set with -global. it's giving "for everyone, but the individual still eats first" 🫶
  • -gray — converts an image to grayscale. Super useful when you're displaying colorful images on servers with limited color capability. It can also convert a bitmap image into a grayscale image, though the resulting image will be smaller than the original. The optional spelling -grey also works, for the international besties. 🩶
  • -halftone — forces halftone dithering of a color image when displaying on a monochrome display. Ignored on monochrome images. Heads up: this dithering algorithm blows an image up by sixteen times. If that's not the vibe, -dither won't blow the image up, but it takes longer to process and is less accurate.
  • -idelay secs — bestie this one is no longer supported because -global exists now. Same functionality, just use -delay. rip to a legend. 💀
  • -invert — inverts a monochrome image. It's shorthand for -foreground white -background black.
  • -merge — merges this image onto the base image after local processing. The base image counts as the first image specified, or the last image that wasn't preceded by -merge. Use it with -at and -clip and you can build up some genuinely complex images. This option is on by default for all images if -onroot or -windowid is specified. collab era.
  • -name image_name — forces the next argument to be treated as an image name. Lifesaver when your image is literally named -dither. 🙈
  • -newoptions — resets globally-specified options. clean slate, fresh start.
  • -normalize — normalises a color image.
  • -rotate degrees — rotates the image degrees clockwise. The number must be a multiple of 90. no freeform spinning sorry 🌀
  • -shrink — shrinks an image down so it fits on the display. Especially useful with servers that don't support window sizes bigger than the physical screen (eg DECWINDOWS servers).
  • -smooth — smooths a color image, which reduces blockiness after you zoom an image up. If you use it on a monochrome image, nothing happens. Heads up: this can take awhile, especially on large images. You can specify more than one -smooth option per image, which causes multiple iterations of the smoothing algorithm. layer it, bestie 🧖‍♀️
  • -tile — tiles this image (after any necessary merging or tiling) to create a fullscreen image. Usually used to build a big background image to merge other images onto. You can use -geometry to set the new image size to something other than -fullscreen.
  • -title title — changes the title of the image. Sets the title bar title if you're displaying in a window, or the NIFF file image title if you're dumping the image.
  • -xzoom percentage — zooms the X axis of an image by percentage. Above 100 expands, below 100 compresses, and a zero value just gets ignored. This one and its sibling -yzoom are great for fixing the aspect ratio of images you're about to display. 📐
  • -yzoom percentage — zooms the Y axis of an image by percentage. See -xzoom for the details.
  • -zoom percentage — zooms both the X and Y axes by percentage. See -xzoom for more info. And okay technically the percentage you actually zoom is the square of the number you supply, since it's zooming both axes, but the author opted for consistency over accuracy and honestly? respect. 💅

🌈 EXAMPLES 🌈

real scenarios, real commands, copy away bestie:

To load the rasterfile "my.image" onto the background and replicate it to fill the entire background:

xloadimage -onroot my.image

To center an image on the default root background:

xloadimage -default -tile my.image

If you're using a monochrome display and a color image, you'll probably wanna dither the image for a cleaner (and faster) display:

xloadimage -default -tile -dither my.image

To load a monochrome image "my.image" onto the background, using red as the foreground color, replicate the image, and overlay "another.image" onto it at coordinate (10,10):

xloadimage -foreground red my.image -at 10,10 another.image

To center the rectangular region from 10 to 110 along the X axis and from 10 to the height of the image along the Y axis:

xloadimage -center -clip 10,10,100,0 my.image

To double the size of an image:

xloadimage -zoom 200 my.image

To halve the size of an image:

xloadimage -zoom 50 my.image

To brighten a dark image:

xloadimage -brighten 150 my.image

To darken a bright image:

xloadimage -brighten 50 my.image

💖 HINTS FOR GOOD IMAGE DISPLAYS 💖

okay so this whole section is basically the author being a real one and teaching us the ✨aesthetics✨ of image display. let's get into it.

Since images come from a whole variety of sources, they may show up in a variety of aspect ratios that your display might not support. That's what -xzoom and -yzoom are for — changing the aspect ratio of an image before display. And if you're gonna use them, the recommendation is: increase the size of one of the dimensions instead of shrinking the other, because shrinking loses detail. no cap, detail loss is tragic.

For instance, lots of GIF and G3 FAX images have an X:Y ratio of about 2:1. You can correct that for viewing on a 1:1 display with either -xzoom 50 or -yzoom 200 (reduce the X axis to 50% of its size, or expand the Y axis to 200% of its size, respectively) — but you should use the latter so no detail gets lost in the conversion. 👑

When you zoom color images up, you can reduce blockiness with -smooth. For zooms of 300% or more, the author recommends two smoothing passes (though this can take awhile to do on slow machines). There will be a noticeable improvement in the image. trust.

You can do image processing on just a small portion of an image by loading the image more than once and using the -merge, -at and -clip options. Load the image, then merge it with a clipped, processed version of itself. To brighten a 100x100 rectangular portion of an image located at (50,50), for instance, you could type:

xloadimage my.image -merge -at 50,50 -clip 50,50,100,100 -brighten 150 my.image

If you're using a display with a small colormap to display colorful images, try using the -gray option to convert to grayscale. 🩶

🗂️ PATHS AND EXTENSIONS 🗂️

So the file ~/.xloadimagerc (and optionally a system-wide file too, bestie) is where you define a bunch of config options that affect xloadimage. It's giving settings menu but make it a text file.

This file is split into three sections: the path section, the extension section, and the filter section. You identify each one by typing the section name followed by an equals sign, like path =. Simple as.

🌸 the path statement

The path statement gives xloadimage a set of search paths to use when it's hunting for an image of a specified name. Separate each path in the list with whitespace (so like one or more spaces, tabs, or newlines — whatever you vibe with). The path gets searched in the order you specify it. For example:

path = ~/images /usr/local/images ~fred

will first look for the image name you specified, then look for the name in ~/images (the tilde gets expanded to the value of $HOME), then in /usr/local/images, then in user fred's home directory. This is how you get easy use of image repositories, periodt. 💅

🦋 the extension statement

The extension statement gives a set of default extensions to use when looking for an image of a specified name. Separate each extension in the list with whitespace. The extensions are searched in the order you specify them. For example:

extension = .gif .jpg

If you have a file named myimage.gif you could just specify the name myimage and xloadimage would append the .gif extension automatically. Iconic behaviour, no notes. ✨

🎀 the filter statement

The filter statement describes filter programs — things like uncompress — that get applied to image files automatically. You specify one filter program and any number of recognised extensions following the filter keyword. For example:

filter = uncompress .Z

specifies that the program uncompress should be used as a filter whenever an image file has a .Z extension. By default filters are provided for compressed (.Z) files and GNU zip (.gz) files. See the FILTERS section for more info on defining your own filters.

💜 little syntax rules, bestie

Any text on a line following a hash-mark (#) is ignored; if you wish to use a hash-mark in a path, extension, or filter you can escape it using a backslash (\).

If you wish to include white-space in a filter program name, path, or extension you can enclose the entire text in double-quotes. For example:

filter = "gzip -cd" .gz

Use backslash (\) characters to allow inclusion of double-quote marks or newlines.

And here's a sample ~/.xloadimagerc file, so you can see the whole vibe:

# paths to look for images in
path = /usr/local/images        # system image repository
      ~/images                 # personal images
      /usr/include/X11/bitmaps # standard X bitmaps

# default extensions for images
extension = .csun .msun .sun .face .xbm .bm

# invoke GNU zip if a .z or .zip extension is found
filter = "gzip -cd" .z .zip

🖼️ IMAGE TYPES 🖼️

Xloadimage currently supports many common and some uncommon image types, and it can create images in several formats too. For a complete list, use the -supported option. Go off, honestly. 🌈

📦 DUMPING IMAGES 📦

Several image dumpers are included that you can use to create a new image after loading and processing. The NIFF (Native Image File Format) is the simplest and creates images that xloadimage can read the fastest; it's essentially a copy of the internal image format. Speed queen. 👑

Some image dumpers allow options that affect the image output. These options are appended to the image type following a comma, and they're separated by commas. If a value is desired it can be specified following an equals-sign. For example, to create a monochrome JPEG image file with a quality factor of 80, you would use the following command line:

xloadimage image_name -dump jpeg,quality=80,grayscale new_image.jpg
⚠️ Option names can be abbreviated, but if the abbreviation is too short to be unique, the option which will be used is indeterminate. So like… don't be lazy with your abbreviations, bestie. 😭

🧚 FILTERS 🧚

Xloadimage supports automatic filtering by recognising file extensions. By default compress and gzip files are recognised and their names passed to appropriate commands to decompress them.

The xloadimage distribution includes a special "smart" uudecoder, called uufilter, that can be used to automatically uudecode files for processing. Uufilter ignores extraneous lines in the file, so it's particularly useful if the uuencoded file was created by concatenating email or news postings that had headers or line-break indicators included. It's giving "I read past the noise" energy. 💅

To make use of uufilter you can add the following to your .xloadimagerc file:

filter = "uufilter -s" .uu .uue

The filter will be automatically invoked on any file with a .uu or .uue extension.

For a list of filters automatically recognised by xloadimage use the -configuration option.

🎨 SUPPORTED IMAGE OPTIONS 🎨

the JPEG dumper's options

The JPEG image dumper supports the following options:

  • arithmetic — Use arithmetic encoding.
  • grayscale — Force a monochrome (grayscale) image to be created given a color image.
  • nointerleave — Create a non-interleaved file.
  • optimise — Enable entropy parameter optimisation.
  • quality — Adjust the quality of the image to be created. The default quality factor is 75; lower values create poorer images.
  • restart interval — Set the restart interval in MCU rows, or MCUs if 'b' follows the interval value.
  • smooth smoothing_factor — Set the smoothing factor. Value should be between 0 and 100, inclusive.

If you are not familiar with the meaning of these options you can ask the Independent JPEG Group (IJG) via email at jpeg@cs.columbia.edu. They're the yoda of JPEG, fr fr. 🫶

the PBM dumper's options

The PBM image dumper supports the following options:

  • normal — Dump a normal (ascii) PBM/PPM file.
  • raw — Dump a RawBits format PBM/PPM file. This is the default and results in significantly smaller image files than when using normal.
😭 There is no way to dump a PGM format file or a "compact" PBM format file (sorry).

the TIFF dumper's options

The TIFF image dumper supports the following options:

  • compression — Image data compression technique. Can be one of: none (no compression), rle (CCITT RLE compression), g3fax (CCITT Group 3 FAX compression), g4fax (CCITT Group 4 FAX compression), lzw (Limpel-Ziv-Welsh compression, the default), jpeg (JPEG compression), next (NeXT run-length compression), rlew (CCITT RLEW compression), mac (Macintosh PackBits compression), packbits (same as mac), thunderscan (ThunderScan compression).

Xloadimage will save using the MINISBLACK, MINISWHITE, COLORMAP, or RGB photometrics as appropriate for its internal image format. There is no way to specify a particular photometric or any other TIFF fields. That's just how it is, bestie. 🙈

👑 AUTHOR 👑

Jim Frost CenterLine Software jimf@centerline.com

For a more-or-less complete list of other contributors (there are a lot of them), please see the README file enclosed with the distribution. Shoutout to the whole squad. 💖

📁 FILES 📁

  • xloadimage — the image loader and viewer
  • xsetbg — pseudonym which quietly sets the background
  • xview — pseudonym which views in a window
  • /etc/X11/Xloadimage — default system-wide configuration file
  • ~/.xloadimagerc — user's personal configuration file

Copyright (c) 1989, 1993 Jim Frost and others.

Xloadimage is copyrighted material with a very loose copyright allowing unlimited modification and distribution if the copyright notices are left intact. Various portions are copyrighted by various people, but all use a modification of the MIT copyright notice. Please check the source for complete copyright information. The intent is to keep the source free, not to stifle its distribution, so please write to me if you have any questions. Free software slay. 🦋

💀 BUGS 💀

  • Zooming dithered images, especially downwards, is UGLY. Like, actually tragic. 😭
  • Images can come in a variety of aspect ratios. Xloadimage cannot detect what aspect ratio the particular image being loaded has, nor the aspect ratio of the destination display, so images with differing aspect ratios from the destination display will appear distorted. See HINTS FOR GOOD IMAGE DISPLAYS for more information.
  • The GIF format allows more than one image to be stored in a single GIF file, but xloadimage will only display the first.
  • Only GIF87a format is supported.
  • One of the pseudonyms for xloadimage, xview, is the same name as Sun uses for their SunView-under-X package. This will be confusing if you're one of those poor souls who has to use Sun's XView. 🙈
  • Some window managers do not correctly handle window size requests. In particular, many versions of the twm window manager use the MaxSize hint instead of the PSize hint, causing images which are larger than the screen to display in a window larger than the screen, something which is normally avoided. Some versions of twm also ignore the MaxSize argument's real function — to limit the maximum size of the window — and allow the window to be resized larger than the image. If this happens, xloadimage merely places the image in the upper-left corner of the window and uses the zero-value'ed pixel for any space which is not covered by the image. This behavior is less-than-graceful but so are window managers which are cruel enough to ignore such details. 💀

And that's the whole page, bestie! 🎀 This edition of the xloadimage manual is dated May 8, 1991, and it lives in the man section as XLOADIMAGE(1). Old? Yes. Iconic? Also yes. Go load some images. 💅✨

📦 where this page comes from