Extensions:Uni-Verse/pngload

Introduction

This page describes the tool called "pngload". As the name suggest, it is a program that loads bitmap images in the PNG format, and uploads them into a Verse server. This provides a quick and easy way to get an existing image online through Verse.

Installation

Requirements

These are the various pieces of software that pngload depends on, and that you must make sure are available if you want to compile it yourself. If you are running a pre-compiled version, dependencies might be different.

Verse

Naturally, you must have the Verse API available in order to compile this program. See the Verse home page for more information.

libpng

A standard library for loading and writing images in the PNG format. Available from the libpng home page.

Running pngload

The pngload program is a pure command-line tool, meaning it has no graphical (window-based) user interface. To use it, you simply run the executable ("binary") from the command prompt, and control its behavior by passing suitable arguments.

A basic invocation looks like this:

 $ pngload foo.png

The above will attempt to load the "foo.png" PNG image, and then upload it to a Verse server running on the same machine.

If you want to upload to a Verse server running elsewhere, use the -ip option, like so:

 $ pngload -ip=verse.example.org bar.png

The above will attempt to upload the "bar.png" PNG image, to a server running on the host verse.example.org.

By default, pngload will name the bitmap nodes it creates after the files they contain. So, the above would create bitmap nodes named foo and bar on the Verse server, respectively. Sometimes, this is not what you want, and you can specify an explicit name like this:

 $ pngload baz.png@testimage

The above will attempt to upload the "baz.png" PNG image, into a node on the local Verse server, which will be named "testimage".

So far, all examples have uploaded just a single image. Sometimes you have a set of images that you all want uploaded, and pngload support this by just accepting several filenames at once:

 $ pngload foo.png bar.png baz.png

The above attempts to upload all three images, in a single run. Images that fail to load will be reported, but the program will not abort.

Output

The above shows only how to call pngload, it does not show any output displayed by the program as it runs.

By default, pngload will print a two lines of information for each image it tries to upload: one line giving a summary of the image's properties, and one line giving the ID and name of the node it created to hold the data. After all the images' lines, a final summary will be printed before pngload exits.

Note that Verse node ID:s are session-local, so there is no guarantee that the node ID printed by pngload will mean anything to some other tool. The name should, though.

Here is how a complete upload will look:

 $ ./pngload ~/data/graphics/test-images/pnggrad16rgb-small.png

 Handling connection, stage 1
 Loaded "/home/emil/data/graphics/test-images/pnggrad16rgb-small.png", 9x9 pixels, RGB,  16 bits/pixel
 Created node 1, set name to "pnggrad16rgb-small"
 Done, uploaded 1 images, 12 tiles in total

You can use the -q ("quiet") option to suppress all this output (except the "Handling connection ..."-line, which is from the Verse library itself).

Limitations

Currently, pngload will only load images that are three (RGB) or four (RGBA) channels. Attempts to load images with non-supported color types will be ignored (and a warning will be printed).

Further, pngload will only create 8- and 16-bit unsigned integer layers, depending on the bits per pixel of the source image. This means that 1-bit, and floating point, formats are not supported.

Also, pngload does not try very hard when it names the nodes it creates. It will simply strip the extension (".png") from the filename, and use the result as the new node name. It does not check for node name collisions; but this is something the server should probably do.