                      ImageSize 0.12f

by Andy Ward. (andy@connectiv.co.uk)

Released April 1st 1996 (pm, so it's not a joke anymore ;-)


Note: This is a user manual only for the stand-alone utitity. If
you want to find out how to integrate the core code in your
programs load '[IMG_Lib]' into an editor.



Instructions
============

This is ImageSize.  It works out the size of images.  'Mazing hey?  I wrote
it because I was fedup with loading files into ChangeFSI et al, and having
to wait ages for them to render just so I could get the image dimensions
to put in some HTML.

Overview
--------

This little utility will almost instantaneously come back with the
dimensions of _any_ GIF, JFIF (including PJPEGs, mono JPEGs etc.) and PNGs
(Portable Network Graphics).  The results can be displayed in a variety of
styles, selectable by switches at the command line to suit your usage.  If
you give it a whole bundle of files it will return the dimensions of all
of them.  You can use the standard RISC OS wildcards (* and #) to denote
ranges of files and they will be analysed in turn.  If you prefer to see
the file paths in a UNIX style there's an option for doing this. If
there's a corrupt file amongst the selection it will let you know and get
on with the rest.  The code is fairly bomb-proof, I hope, so it shouldn't
fall over like CFSI, FYEO, & Translator etc. do when they hit duff files.


The Controls
------------

The program is controlled from the commandline and takes a few options.
All switches are case insensitive and can be shortened to a single letter.

'imagesize -h' gives the following brief help:
-------------------------------------------------------------------------------
ImageSize 0.12f (01 Apr 1997) - Extracts the dimensions of images in various
                               formats.

usage: imagesize [options] [filename] ...

-r[aw]       Output result as raw figures. Width then height.
-t[ext]      Textual output. (default)
-i[mage]     Marked up as a HTML <IMG> construct.
-n[oOutput]  No output. Examine System variables instead.
-l[ower]     Lower case HTML.
-d[ir] <dir> Search in directory <dir>.
-s[ystem]    Search directory specified by <ImageSize$Path>
-c[reator]   Compatability mode for John Kortink's Creator`
-u[nix]      Exchanges dots and slashes in the filename (after processing).
-b[ypass]    Bypasses the wildcard process
-? or -h     This help.

FREEWARE.  Andy Ward, Feb-May 1996.
-------------------------------------------------------------------------------

Output Formats
--------------

Output-wise, there are presently four formats.  By default you get the
pure text version. e.g

  *imagesize file/gif
  File : file/gif
      Width  = 90
      Height = 20

  *

To get a 'raw' output of just the two figures (useful for integration
with another program since you can redirect the output to a file and
read it in easily.) The ordering is Width then height. e.g

  *imagesize -r file/gif { > <Wimp$ScrapDir>.output }

would put '90 20' in a file called 'output' in the wimpscrap, which you
could then peek at.

Thirdly, there's the HTML formatted option. Use the -i flag to select
this. If you want lower case HTML also include the -l flag. This will
output the result in the form:

  <img src="picture" alt="" height=512 width=768>

Finally, there's the System Varible option '-v' which outputs the results
into numeric system variables :

  ImageSize$Width and ImageSize$Height

These can then be read by external programs. This output option can be
used simultaneously with any of the other output options. I.e it doesn't
override them. Obviously you can only analyse one image at once, otherwise
you'll only be able to read the last result.

e.g you might want to use the following in an external program to read the
    dimension values easily and have the ability to export the formatted
    tag to another program:
    
imagesize -i -v <filename> { > pipe:$.file }

If you want the RISC OS filenames appearing in the output converted to
UNIX style filename simply add the '-u' switch to the command line
parameters. This will translate dots to slashes and vice-versa _after_
the program has found and processed the file.  I.e there must be a RISCOS
match for the filename on the search path. (See 'search criteria' for
details of how to get round this).  If the 'filename' contains a colon
this flag will be ignored because it is either a hardwired RISCOS
filename, or a URL, neither of which map across too well.


Search Criteria
---------------

Where the utility looks for the images depends on what flags you pass it. 
By default it just checks the Current Selected Directory.  By using the -d
flag you can specify a different directory to look in.  This can be an
explicit (ADFS::Harddisc.$.pics) or relative (^.myfiles).  By using the -s
flag you can tell ImageSize to use the system variable 'ImageSize$Path' as
a directory specifier.  (Remember that paths must end with a fullstop.)

[Note: This isn't a real 'path'. You can't comma separate a bunch of
directory paths and get ImageSize to look in all of them in turn (yet).]

As mentioned earlier, you can just give ImageSize a list of files to be
getting on with at the CLI.  If you don't specify any files then you will
be prompted to enter one, whereupon it will process it.  The program will
keep looping round asking you for another file until you give it a blank
filename (ie. just hit return).

Wildcards can be used both as command-line parameters, and when using the
interactive file entry method just mentioned. Matching  files have their
names 'expanded' so it is clear from the output which file is being
referred to.


Miscellany
----------

* The command line syntax is a bit weird, because I rolled my own parser.
Basically, you can insert the switches at any point in the parameter list
even after filenames. This means that you can change the output style
mid-way through the program. eg.

  *imagesize file1 -i file2 -l file3
  File : file1
     Width  = 128
     Height = 160

  <IMG SRC="file2" ALT="" HEIGHT=200 WIDTH=100>
  <img src="file3" alt="" height=1000 width=2>

Its a documented feature. Don't let anyone tell you otherwise, OK!
Besides, someone might find it useful.


* One final option I haven't mentioned is the '-b' option. This is really
a hangover from debugging the underlying code that allows you to totally
bypass the wildcarding code and send the filename straight to the core
code. The reason I wanted to do this is so I could test the UNIX to
RISCOS code without the front-end complaining that the file 'foo.gif'
doesn't exist. I've left it in because it may be of use to some people.
If used with the -u option you can forget all about RISCOS file
conventions.



Future Developments
===================

If you look at the source you'll see this has been written entirely in
assembler. "How sad", I hear you say. "What an anorak!" etc. Well, I have
an excuse. You see, I'm integrating the core of the code into Matthew
Hambley's ZapHTML module, so that all the HEIGHT/WIDTH fields are filled
in automatically if you have the images present locally. The code should
also be clever with the RISCOS <-> Unix path conversions, and will have
some way of refreshing the image attributes at a later date if the image
dimensions change. 

[Latest: I've finished this. It's getting munged with Matthew's source as
I write. Expect to see the feature in ZapHTML soon.]

Functionality wise, I may add some code to recognise files by their
contents rather than by filetype. I'm also planning to add code to map
filetypes to extensions (and vice-versa) and have the core code find files
based around these routines. (i.e *.gif will find all files with filetype
695 and any matching filenames)

If someone wants new file formats I may add support for them, but only if
they can show widespread need, (and it's not too hard ;-). [I only
included PNG format because it was _dead_ easy! It will be useful one day
though.] Also if anyone needs a different output format I may be persuaded
to write a few lines for them.

If you want a WIMP front-end for the utility, 'and want it now' Richard
Goodwin has knocked up one. If you ask nicely I expect he'll send it you.
I plan to make a much more comprehensive WIMP interface available in the
future, which should encompass all aspects of adding images and links to
HTML. If anyone wants to see the prototype mail me.

People have made suggestions to the effect that there should be a way of
stripping the 'head' of a filename's path off (e.g ADFS::Harddisc....) to
a pseudo-'root' directory. This would be useful for drag'n'drop
interfaces. I'm not going to implement this for the simple reason that
it's quite tricky and a lot of hard work to get this right in assembler
and it'd be much easier to do it in a High Level Language along with the
GUI stuff. 

Apart from that it's just a case of fixing the inevitable bugs. If you
find any _please_ report them to the email address below.


Credits
=======

Thanks to David N. Walker for his UNIX to RISCOS path swapping routine
which is buried in the code somewhere.

Contacting the Author
=====================

It's traditional to put contact addresses and phone numbers here, but I
like my anonymity, and I don't want any pranksters ringing me up at 4am
(and interrupting my programming ;-) so you'll just have to contact me
though my email addresses.

cheers,

Andy Ward

andy@connectiv.co.uk
andy@connecti.demon.co.uk

April 1996