aximgview − display a PNM or PAM image in an X11 window
aximgview [−help] [−version] [−wh] [−sw] [−step increment] [−display address] [−geometry geom] [−iconic] [−title title] [−xauthfile file] [−xauthtype type] [−xauthindex index]
Aximgview reads a PBM, PGM, PPM, or PAM image from standard input and displays it in an X11 window. It mimics the xloadimage(1) user interface, though there are a few additional features as well as many omissions compared to xloadimage.
If a region is selected when aximgview exits, the region’s upper-left and lower-right coordinates will be printed on standard output (selection currently has no other effect; in particular, the X11 clipboard and cut buffers are unaffected).
Mouse button 1
Drag the image to pan the window’s viewport across it.
Mouse button 2
Drag to select a region of the image or click to erase the current selection.
Esc, q, or Mouse button 3
Exit aximgview. If an image region was selected, its coordinates are printed.
Arrow keys
Pan the window’s viewport across the image.
−h, −help, −−help
Print a brief usage summary and exit.
−V, −version, −−version
Print version and copyright information and exit.
|
−wh |
Width/height mode for selection output. When printing a selected region’s coordinates, print them as <x> <y> <width> <height> instead of <x1> <y1> <x2> <y2>. The output with this option can be used directly as arguments to Netpbm’s pamcut command, for example. | ||
|
−sw |
Swap the functions of mouse buttons 1 and 2 so that button 1 selects a region while button 2 pans across the image. This may be helpful when using aximgview specifically to select an image region. | ||
|
−step |
When panning the image using the arrow keys, the distance (in pixels) panned is given by the increment. It can be negative, in which case the panning direction is effectively reversed. The default value is 50. |
The following
options control the X11 connection:
−d, −display
The address argument
specifies the X11 server endpoint to connect to. It can have
one of the following forms:
ip or ip:port
IPv4 address. If :port is omitted, a default of 6000 is assumed.
[ip6] or [ip6]:port
IPv6 address. Default port: 6000.
filename
Unix domain socket.
Without this option, aximgview will attempt to connect via the Unix domain socket /tmp/.X11−unix/X0.
Note that this form differs from the standard DISPLAY format for X11 programs, and that the DISPLAY environment variable is ignored. The main reason for this (and for having the −xauth* options) is that aximgview cannot resolve host names.
−g, −geom, −geometry
The geom argument, which should be in the standard X toolkit form [<w>x<h>][<+|−><x><+|−><y>], will determine the initial size and position of the window.
−iconic
With this option, aximgview will start as an icon rather than as a window.
−T, −title
Sets the window title. The default title is "aximgview".
−xaf, −xauthfile
Choose which file to load X11 authentication data from. Without this option, the file name is determined from the environment (see the ENVIRONMENT section below). If the file cannot be loaded or no matching entry is found within it, aximgview will attempt to connect with no authentication.
−xat, −xauthtype
When searching the .Xauthority file, only consider entries of the given type. It corresponds to the "family" field in <X11/Xauth.h> and the type of network layer used to connect to the display. Potentially useful values are: −1 to match any type of entry, 0 for an IPv4 entry, 6 for an IPv6 entry, and 256 for a local (Unix domain socket) entry. The default value is 256, which is useful in combination with the default value for the −display option (see above).
−xai, −xauthindex
When searching the .Xauthority file, the (index+1)’st entry of the matching type is used to authenticate. For example, if type is 256 and the index is 1, the second local (Unix domain socket) entry will be chosen. The default index is 0.
|
HOME |
If $XAUTHORITY is not set and no −xauthfile option is given, X11 authentication data is loaded from $HOME/.Xauthority. |
XAUTHORITY
If set and no −xauthfile option is given, X11 authentication data is loaded from this file.
Some error messages aximgview may display actually come from the X11 server. In particular, "No protocol specified" is a reply sent by the X server when it expects an authentication token but did not get any. In this case you have to use the −xauth* options to choose an .Xauthority file and/or entry.
Aximgview is written in a custom programming language called Asterix, without using the Xlib (or xcb) library normally used for X11 client programs; as such it has some limitations that X11 programs normally don’t have.
Despite all the polish, it’s still missing features that would be useful for an image viewer, such as zooming or setting an image as background.
For an example program, aximgview’s source code is very light on comments.
There are no key bindings for selecting an image region (however, X11 itself may provide mouse emulation using the keyboard; try Shift+Numlock and the number keypad).
For PGM and PPM images, the maxval must be 255. The DEPTH and MAXVAL fields of PAM images are ignored. If necessary, use Netpbm’s pamdepth(1) command (or something equivalent) to convert the image first. PAM images with a TUPLTYPE of BLACKANDWHITE, GRAYSCALE, or RGB are supported, however transparency (*_ALPHA) is not.
The DISPLAY environment variable is ignored. Perhaps this could be partially supported (i.e. IP addresses and local displays only), but a (possibly system- or user-specific) wrapper script that passes −display and −xauth* options to aximgview could provide a more reliable solution.
Aximgview reads images only from standard input. Again, a wrapper script would probably be the best way to deal with this limitation (and it could also convert images of different types like PNG or JPEG and set the window title based on the filename, for example).
Although several types of error are caught and reported to the user, there are plenty of other cases of bad input or problems that will result in the dreaded "Unexpected error" which really doesn’t tell you much about what went wrong and how to fix it.
There are plenty of limitations in its X11 support: it can only use a 32-bit pixel format and the root window depth must be 24 or 32. When authenticating to the X11 server, only MIT-MAGIC-COOKIE-1 keys are supported. It does not use the X11 resource mechanism to read defaults for options such as −step.
It keeps 2 copies of the image in memory that it doesn’t really need.
Exit codes are somewhat arbitrary and undocumented, however zero should indicate a normal exit while non-zero indicates some kind of error.
Aximgview is larger than the Asterix compiler itself.
Copyright (c) 2020 Pim Goossens
This program is free software: you are free to change and redistribute it under the terms of the GNU General Public License (GPL) version 3 or (at your option) any later version. A copy of this license should be included with the program in a file named COPYING.
There is NO WARRANTY, to the extent permitted by law.
xloadimage(1), pnm(5), pbm(5), pgm(5), ppm(5), pam(5)