Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       xloadimage,  xsetbg, xview - load images	into an	X11 window or onto the
       root window

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

       Xloadimage displays images in an	X11 window, loads them onto  the  root
       window,	or  writes them	into a file.  Many image types are recognized;
       use the -supported option to list them.

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

       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.  This can also  be
       done forcibly with the -halftone, -dither, and -colors options.

       A variety of image manipulations	can be specified, including gamma cor-
       rection,	brightening, clipping, dithering,  depth-reduction,  rotation,
       and  zooming.  Most of these manipulations have simple implementations;
       speed was opted for above accuracy.

       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.

       If more than one	image file is specified	on the command line, each  im-
       age 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  recognized  image	 types
       into any	of the formats that support dumping.

       Xsetbg  is equivalent to	xloadimage -onroot -quiet and xview is equiva-
       lent to xloadimage -view	-verbose.

       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	diffi-
       cult to predict)	or xloadimage (which conflicted	with class naming con-

       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 im-

       -border color
	       This  sets  the	background  portion of the window which	is not
	       covered by any images to	be color.

	       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  sys-
	       temwide	file (normally /usr/local/etc/xloadimagerc).  This re-
	       places the -path	option.

	       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  op-
	       tion 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.

       -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  im-
	       age  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.

	       Use the entire screen to	display	images.	 If combined with -on-
	       root, 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 im-
	       age_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	the supplied images rather than	display	them.

	       Forcibly	 install  the  image's colormap	when the window	is fo-
	       cused.  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.

       -list   List the	images which are along the image path.

       -onroot Load image(s) onto the root window instead of viewing in	a win-
	       dow.   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 configura-
	       tion.   This  option is obsolete	and has	been replaced by -con-

       -pixmap Force the use of	a pixmap as backing-store.  This  is  provided
	       for  servers  where  backing-store is broken (such as some ver-
	       sions of	the AIXWindows server).	 It may	improve	scrolling per-
	       formance	on servers which provide backing-store.

	       Force the use of	a private colormap.  Normally colors are allo-
	       cated 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.

	       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.

	       Causes xloadimage to be talkative, telling you what kind	of im-
	       age it's	playing	with and any special processing	that it	has to
	       do.  This is the	default	for xview and xloadimage.

	       Print  the  version  number  and	 patchlevel of this version of

       -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:  Di-
	       rectColor, 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  ar-
	       gument  must be in hexadecimal and must be preceded by "0x" (eg
	       -windowid 0x40000b.  This is intended  for  setting  the	 back-
	       ground  pixmap of some servers which use	untagged virtual roots
	       (eg HP-VUE), but	can have other interesting applications.

       The following options may precede each image.  These options are	 local
       to the image they precede.

       -at X,Y
	      Indicates	 coordinates  to  load the image at on the base	image.
	      If this is an option to the first	image, and the -onroot	option
	      is  specified, the image will be loaded at the given location on
	      the display background.

       -background color
	      Use color	as the background color	instead	of the	default	 (usu-
	      ally white but this depends on the image type) if	you are	trans-
	      ferring a	monochrome image to a color display.

       -brighten percentage
	      Specify a	percentage multiplier for a color image's colormap.  A
	      value  of	more than 100 will brighten an image, one of less than
	      100 will darken it.

	      Center the image on the base image loaded.  If this is an	option
	      to the first image, and the -onroot option is specified, the im-
	      age will be centered on the display background.

       -clip X,Y,W,H
	      Clip the image before loading it.	 X and Y define	the upper-left
	      corner  of  the clip area, and W and H define the	extents	of the
	      area.  A zero value for W	or H will be interpreted  as  the  re-
	      mainder of the image.

       -colors n
	      Specify  the maximum number of colors to use in the image.  This
	      is a way to forcibly reduce the depth of an image.

       -delay secs
	      Automatically advance to the next	image after secs seconds.  You
	      may want to use the -global switch with this command to create a
	      slideshow	with multiple images.

	      Dither a color  image  to	 monochrome  using  a  Floyd-Steinberg
	      dithering	algorithm.  This happens by default when viewing color
	      images on	a monochrome display.  This is slower  than  -halftone
	      and affects the image accuracy but usually looks much better.

       -foreground color
	      Use  color  as  the foreground color instead of black if you are
	      transferring a monochrome	image to a color  display.   This  can
	      also be used to invert the foreground and	background colors of a
	      monochrome image.

       -gamma display_gamma
	      Specify the gamma	correction for the display.  The default value
	      is 1.0, a	typical	display	needs 2.0 to 2.5.

	      Force  the  following  option to apply to	all images rather than
	      one specific image.  Local image options will temporarily	 over-
	      ride any option specified	with -global.

       -gray  Convert  an  image  to grayscale.	 This is very useful when dis-
	      playing colorful images on servers with limited  color  capabil-
	      ity.   It	 can  also  be	used  to convert a bitmap image	into a
	      grayscale	image, although	the resulting image  will  be  smaller
	      than  the	 original.   The  optional  spelling -grey may also be

	      Force halftone dithering of a color image	when displaying	 on  a
	      monochrome  display.   This  option is ignored on	monochrome im-
	      ages.  This dithering algorithm blows an	image  up  by  sixteen
	      times;  if you don't like	this, the -dither option will not blow
	      the image	up but will take longer	to process and	will  be  less

       -idelay secs
	      This  option  is	no  longer  supported  due  to the addition of
	      -global.	The same functionality can be had with -delay.

	      Inverts a	monochrome image.  This	is shorthand  for  -foreground
	      white -background	black.

       -merge Merge  this  image  onto	the base image after local processing.
	      The base image is	considered to be the first image specified  or
	      the last image that was not preceded by -merge.  If used in con-
	      junction with -at	and -clip, very	complex	images	can  be	 built
	      up.   This option	is on by default for all images	if the -onroot
	      or -windowid options are specified.

       -name image_name
	      Force the	next argument to be treated as an image	name.  This is
	      useful if	the name of the	image is -dither, for instance.

	      Reset globally-specified options.

	      Normalize	a color	image.

       -rotate degrees
	      Rotate  the  image  by  degrees clockwise.  The number must be a
	      multiple of 90.

	      Shrink an	image down to fit on the display.   This  is  particu-
	      larly  useful  with  servers  that  do  not support window sizes
	      larger than the physical screen (eg DECWINDOWS servers).

	      Smooth a color image.  This reduces blockiness after zooming  an
	      image up.	 If used on a monochrome image,	nothing	happens.  This
	      option can take awhile to	perform, especially on	large  images.
	      You  may specify more than one -smooth option per	image, causing
	      multiple iterations of the smoothing algorithm.

       -tile  Tile this	image (after any necessary merging or tiling) to  cre-
	      ate  a fullscreen	image.	This is	usually	used to	create a large
	      background image on which	to merge other images.	-geometry  can
	      be  used	to  set	 the  new  image  size to something other than

       -title title
	      Change the title of the image.  This sets	the title bar title if
	      displaying  in  a	window or the NIFF file	image title if dumping
	      the image.

       -xzoom percentage
	      Zoom the X axis of an image by  percentage.   A  number  greater
	      than 100 will expand the image, one smaller will compress	it.  A
	      zero value will be ignored.  This	option,	and the	related	-yzoom
	      are  useful for correcting the aspect ratio of images to be dis-

       -yzoom percentage
	      Zoom the Y axis of an image by percentage.  See -xzoom for  more

       -zoom percentage
	      Zoom  both  the X	and Y axes by percentage.  See -xzoom for more
	      information.  Technically	the percentage actually	zoomed is  the
	      square  of  the  number supplied since the zoom is to both axes,
	      but I opted for consistency instead of accuracy.

       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  using a monochrome display and a color image	you will probably want
       to 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

       Since  images are likely	to come	from a variety of sources, they	may be
       in a variety of aspect ratios which may not be supported	by  your  dis-
       play.   The  -xzoom and -yzoom options can be used to change the	aspect
       ratio of	an image before	display.  If you use these options, it is rec-
       ommended	that you increase the size of one of the dimensions instead of
       shrinking the other, since shrinking looses detail.  For	instance, many
       GIF  and	G3 FAX images have an X:Y ratio	of about 2:1.  You can correct
       this for	viewing	on a 1:1 display with either -xzoom 50 or  -yzoom  200
       (reduce	X  axis	 to  50%  of its size and expand Y axis	to 200%	of its
       size, respectively) but the latter should be used so no detail is  lost
       in the conversion.

       When  zooming  color  images up you can reduce blockiness with -smooth.
       For zooms of 300% or more, I recommend two smoothing  passes  (although
       this  can take awhile to	do on slow machines).  There will be a notice-
       able improvement	in the image.

       You can perform image processing	on 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  ver-
       sion  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 im-
       ages, try using the -gray option	to convert to grayscale.

       The file	~/.xloadimagerc	(and optionally	a system-wide file) defines  a
       number of configuration options that affect xloadimage.

       This  file is split into	three section, the path	section, the extension
       section,	and the	filter section.	 The sections are identified by	typing
       the section name	followed by an equals sign, eg "path =".

       The path	statement is used to provide a set of search paths to use when
       looking for an image of a specified name.  Separate each	 path  in  the
       list  by	 whitespace  (eg  one or more spaces, tabs, or newlines).  The
       path is searched	in the order it	is specified.  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 is expanded to the value of $HOME), then in
       /usr/local/images, then in user fred's  home  directory.	  This	allows
       easy use	of image repositories.

       The  extension statement	is used	to provide a set of default extensions
       to use when looking for an image	of a specified	name.	Separate  each
       extension  in  the  list	by whitespace.	The extensions are searched in
       the order in which they are specified.  For example:

	 extension = .gif .jpg

       If you have a file named	myimage.gif you	could specify the name myimage
       and xloadimage would append the .gif extension automatically.

       The  filter statement is	used to	describe filter	programs, such as "un-
       compress", which	are to be applied to image files  automatically.   You
       specify one filter program and any number of recognized extensions fol-
       lowing the filter keyword.  For example:

	 filter	= uncompress .Z

       specifies that the program uncompress should be used as a filter	 when-
       ever 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	information on defining	your own filters.

       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	 exam-

	 filter	= "gzip	-cd" .gz

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

       The following is	a sample ~/.xloadimagerc file:

	 # paths to look for images in
	 path =	/usr/local/images	 # system image	repository
	       ~/images			# personal images
	       /usr/local/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

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

       Several image dumpers are included that can be used to create a new im-
       age  after loading and processing.  The NIFF (Native Image File Format)
       is the simplest	and  creates  images  that  xloadimage	can  read  the
       fastest;	it is essentially a copy of the	internal image format.

       Some  image  dumpers allow options that affect the image	output.	 These
       options are appended to the image type following	a comma	and are	 sepa-
       rated  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.

       Xloadimage supports automatic filtering by recognizing file extensions.
       By  default  "compress" and "gzip" files	are recognized 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  is
       particularly  useful if the uuencoded file was created by concatenating
       email or	news postings that had headers or  line-break  indicators  in-

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

	 filter	= "uufilter -s"	.uu .uue
       The filter will be automatically	invoked	on any file with a .uu or .uue

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

       The JPEG	image dumper supports the following options:

	       Use arithmetic encoding.

	       Force a monochrome (grayscale) image  to	 be  created  given  a
	       color image.

	       Create a	non-interleaved	file.

	       Enable entropy parameter	optimization.

       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,

       If you are not familiar with the	meaning	of these options you  can  ask
       the Independent JPEG Group (IJG)	via email at

       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

       There  is  no  way  to dump a PGM format	file or	a "compact" PBM	format
       file (sorry).

       The TIFF	image dumper supports the following options:

	       Image data compression technique.  Can be one of: none (no com-
	       pression),  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 com-
	       pression), 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.

       Jim Frost
       CenterLine Software

       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.

	    xloadimage		    - the image	loader and viewer
	    xsetbg		    - pseudonym	which quietly sets the background
	    xview		    - pseudonym	which views in a window
	    /usr/local/etc/xloadimagerc	    - 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.

       Zooming dithered	images,	especially downwards, is UGLY.

       Images  can  come in a variety of aspect	ratios.	 Xloadimage cannot de-
       tect what aspect	ratio the particular image being loaded	has,  nor  the
       aspect  ratio  of the destination display, so images with differing as-
       pect 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  Max-
       Size 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 hap-
       pens,  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.

				  8 May	1991			XLOADIMAGE(1x)


Want to link to this manual page? Use this URL:

home | help