!Help for !Jclean version 4.00 (Wed 05th June 2002)


!Jclean is a desktop front end (or interface) for the
Independent JPEG Group utility 'jpegtran'. It allows all
operations available from 'jpegtran' to be performed by
clicking and drag-and-drop rather than having to resort to
the command line. Version 4.00 also uses its own code for
inserting up to three types of comments into JPEGs. Existing
comments can be either copied out or removed, or both. The
Independent JPEG Group utility 'wrjpgcom' is no longer used
in !Jclean.

Click SELECT on the icon bar icon to open up the !Jclean
options window. This lets you select the operations that
will be performed on the JPEGs when you drop them on the
icon bar icon or on the !Jclean icon showing in the options
window. Clicking SELECT a second time on the icon bar icon
will close the !Jclean options window.

Click ADJUST over the icon bar icon to open or close the
!Jclean status window which keeps you informed of !Jclean's
progress.

Full details of all the options are given below in this file
but you might find it easier to use an interactive help
application. where placing the pointer over an icon will
provide information pertinent to that icon.

Why use !Jclean?

  1. Because it can make many JPEGs smaller by optimizing the
  encoding parameters or by stripping unwanted markers such as
  text comments, embedded thumbnail images, Photoshop settings
  or Exif information.
  
  2. Because it can perform various useful transformations on
  the image.
  
  3. Because it can insert your comments into a JPEG file -
  such as a copyright notice, or perhaps the date, location,
  subject or other details of the photo.
  
  4. Because it does any or all of reasons 1 - 3 without any
  degradation of the image which would occur were you to
  decode, change and re-encode the image e.g. by passing it
  through ChangeFSI. To the best of my knowledge, all image
  processing software will decode JPEGs on loading and
  re-encode them on saving out as JPEGs, and this always
  degrades the image.



######################################################

1. SOME IMPORTANT POINTS

######################################################


The original JPEG file could be overwritten by the result
file, depending on the options you have selected - so ensure
you have a backup copy if you don't want to risk losing
information. Errors may occur if, for example, there is not
enough disc space, or the medium is write protected. Ensure
that all files (JPEGs and comment files) are not locked and
are both read and write enabled.

Length of filenames should now cause no problems. !Jclean
should cope with paths up to 4095 characters in length, with
leaf names up to 255 characters, for both JPEGs and comment
files. I haven't been able to test this on RISC OS 3.7 (even
using !raFS), so I would welcome confirmation that it does
indeed work - or reports with as much information as
possible where it fails.

!Jclean itself, and the Scrap directory, should both be kept
fairly near the root directory.

You are advised to read the files inside the 'doc' directory
inside !Jclean, particularly the section on 'jpegtran' in
the file, 'usage'.

RISC OS ports of the other utilities by the independent JPEG
Group (cjpeg, djpeg, wrjpgcom and rdjpgcom) are available
(for command line use) from Jrme Mathevet's website:

http://www.multimania.com/mathevet/jpegv6b.zip

The usual disclaimer: This software may be completely
unsuitable for any purpose to which you will put it so don't
blame me if it floods your home and runs off with your
daughter. You use it at your own risk. That said, you may
use it freely and distribute it provided no charge is made.

Please do not hesitate to inform me of any problems in the
use of !Jclean.

Bug reports: david@dacha.freeuk.com

Web site: http://www.dacha.freeuk.com/



######################################################

2. THE JCLEAN MENU

######################################################


Info

  Leads to the usual program information.


Help

  Opens this !Help file in a text editor window.


Options...

  Click to open or close the !Jclean Options window. This menu
  option is ticked when the window is open.


Status...

  Click to open or close the !Jclean Status window. This menu
  option is ticked when the window is open.


Open Scrap

  Click to open !Jclean's scrap directory. As well as the
  temporary files used in !Jclean's processing, this directory
  contains the Log file and also the Comments file where
  comments embedded in JPEGs might be saved.


New Log

  Click to start a new Log file. The existing Log file might
  be backed up if not empty, depending on your configuration
  options. (See the 'Config' file inside the !Jclean
  application directory on how to set the number of backups.)


New Comments

  Click to start a new Comments file. The existing Comments
  file might be backed up if not empty, depending on your
  configuration options. (See the 'Config' file inside the
  !Jclean application directory on how to set the number of
  backups.)


Quit

  Click to quit !Jclean. Temporary files in !Jclean's scrap
  directory will be deleted but the Log and Comments files
  will be kept.



######################################################

3. THE JCLEAN OPTIONS WINDOW

######################################################


This window can be opened and closed from the icon bar icon
menu or by clicking SELECT over the icon bar icon.

The startup size, number of scroll bars, and whether or not
the window opens automatically when !Jclean starts, can be
set in the 'Config' file inside the !Jclean application
directory.

This window is divided into three sections.


A. Top Section - !Jclean action options
=======================================


Clean (ignore options)

  If you tick this then all the options in the middle and
  bottom sections are ignored. JPEGs are passed through
  jpegtran with options set to Optimise and to remove all
  inessential header blocks such as comments, Exif
  information, thumbnails, etc.


Use TaskWindow

  When this is selected, !Jclean will run jpegtran as a
  background task. No actual window displays on screen since
  output is redirected to files in !Jclean's scrap directory.
  If not selected, jpegtran runs as a single task and may take
  control of the computer for up to several minutes at a time,
  depending on the size of JPEG and operation performed.


Stamp

  !Jclean's default action is to read the time and date
  information of the original JPEG before processing it and
  write it back to the processed JPEG. If you tick this
  option, the result file will have the new time and date of
  the processing.
  
  Note that if you insert a 'filedate' comment (see Middle
  Section) with this option ticked, the date used will be the
  new filedate.


Recurse

  Tick this if you want to process a whole directory structure
  full of JPEGs. !Jclean will search up to 128 levels of
  nesting before going horribly wrong - although a "string too
  long" error will probably occur long before then as the file
  pathnames get longer. If unticked, !Jclean will ignore
  directories and process only JPEGs dropped directly onto its
  icon.


Output to

  Tick this if you do NOT want !Jclean to overwrite the source
  files with the result files. To have !Jclean save them
  elsewhere, you need to have dragged the required output
  directory (or a file within that directory) into the box to
  the right of this option. !Jclean will not allow application
  directories to be the output directory.
  
  Note that !Jclean will automatically overwrite source files
  if this option is unticked but will automatically NOT
  overwrite files of the same name (i.e. it will abort the
  operation after processing) when this option is selected.
  The operation aborts similarly if no directory has been
  dropped into the output directory icon.
  
  By having no output directory, or using the source directory
  as output directory, you can make !Jclean perform all
  processing with no actual output of processed JPEGs but just
  the LOg file. This might be useful for finding out if JPEGs
  contain any errors.


B. Middle Section - !Jclean processing options
==============================================


Save comments to  * scrap  * <jpeg>/out

  When this option is ticked, !Jclean will copy any comments
  it finds to either the 'Comments' file inside !Jclean's
  scrap directory or to new individual files with the same
  name as the JPEG but with a user specified file extension.
  By default the extension is '/out' but it can be defined in
  the 'Config' file inside the !Jclean application directory.
  If the "<jpeg>/out" file already exists, !Jclean will not
  overwrite it.
  
  Note that other types of embedded information, such as Exif
  data, thumbnails, etc., will not be copied out.


Remove existing comments

  When this option is ticked, !Jclean will remove any comments
  it finds in the source JPEG. Other types of embedded
  information, such as Exif data, thumbnails, etc., will not
  be removed. (Use "Remove inserts" in jpegtran to do this.)


Insert 'filedate'

  Ticking this causes !Jclean to insert one of the three types
  of comment into every JPEG. This is a text string which may
  contain a substring which !Jclean will change to the
  filedate of the source JPEG (if 'Stamp' is not ticked) or to
  the filedate of the result JPEG (if 'Stamp' is ticked). The
  string is read at startup from !Jclean's 'Config' file. The
  'Config' file contains full information about how to format
  the time and date.
  
  Example use: Copyright notice.


Insert individual file <jpeg>/txt

  When this is ticked, !Jclean will look for a file with the
  same name as the source JPEG (in the same directory) but
  with a specified file extension. By default the extension is
  '/txt' but it can be defined in the 'Config' file inside the
  !Jclean application directory. If such a file exists and is
  not too large (maximum of 65534 bytes) and is not empty,
  !Jclean will insert it as a comment.
  
  Example use: Photo details.

  If you wish to insert individual comments into your JPEGs
  (e.g. date and location of photographs), then you must
  create a file for each JPEG. Each file must be in the same
  directory as the JPEG into which it is to be inserted and it
  must have the same name as the JPEG with a "/txt" extension
  or suffix. (The case doesn't matter.) !Jclean will strip
  "/jpg" and "/jpeg" extensions from the JPEG filename before
  adding the "/txt" extension to look for a comment file.
  Other extensions will not be stripped.
  
  Examples:
  
   JPEG filename   -->   comment filename
  
   Snowdon               Snowdon/txt
   BenNevis/jpg          BenNevis/txt
   Matterhorn/jpeg       Matterhorn/txt
   BenNevis/jp           BenNevis/jp/txt
   Snowdon/exif          Snowdon/exif/txt
   
  This might cause difficulties if you are limited to
  10-letter filenames (so why aren't you using raFS?) or have
  been creative with the use of extensions. E.g. the three
  files "Snowdon", "Snowdon/jpg" and "Snowdon/jpeg" can only
  have one comment file, "snowdon/txt", between them.


Insert file [<filename>]

  This option lets you insert a common comment file into all
  your JPEGs. The file must either have been dropped into the
  icon to the right of this option or its path written to the
  option in !Jclean's 'Config' file.
  
  Example use: Camera/expedition details.


jpegtran (using options below)

  If this option is not selected, !Jclean will not run
  jpegtran but perform only the comment operations listed
  above. If it is ticked, jpegtran will be run using the
  options in the Bottom Section.


C. Bottom Section - jpegtran processing options
===============================================


Greyscale

  This removes any colour information in the image, leaving
  only luminance (i.e. a scale of black to white). You can use
  this option to convert a coloured image to monochrome or to
  remove erroneous colour channels from a grey image
  incorrectly encoded as coloured. The advantage is a smaller
  file and quicker decoding time. The disadvantage is that you
  could accidentally lose colour information forever.


Optimised

  This ensures the most efficient encoding parameters, usually
  producing a smaller file.  For the smallest possible file,
  ensure that the "Progressive" and 'Set restarts every"
  options are unticked, and that "Remove inserts" is ticked.


Progressive

  This produces a JPEG which decodes in a way similar to
  interlaced GIFs in that a full-size image of low quality is
  displayed quickly with more detail being filled in on each
  subsequent pass. It would be ideal for slow internet
  connections but not all decoders recognise it.


(report)  * 1  * 2

  This option has no effect on the JPEGs but determines the
  amount of information that jpegtran provides on each JPEG it
  sees. If not ticked, jpegtran will report only errors. If
  ticked with level '1' reporting selected, jpegtran will also
  describe the header markers (information blocks) it finds.
  With level '2' selected, jpegtran will also print out the
  quantization and Huffman tables.
  
  All jpegtran reports are included in the Log file entry for
  each JPEG.


Set restarts every  * Nth block  * Nth row

  This sets markers in the JPEG which allow decoders to resume
  correctly even if data stream has previously become corrupt,
  e.g. during downloading on the internet or by radio
  transmission from space. Without restarts, a single bit
  error in the first few bytes of the image data can make the
  entire image unviewable. There are drawbacks. Setting a
  restart every block could nearly double the size of the
  JPEG. !Jclean allows a maximum interval of 99 for both block
  and row restarts.

  Note that holding down the Shift key while clicking over the
  up and down icons will cause increments or decrements by 10.

Transform
  
  * Rotate 90 degrees anticlockwise
  * Rotate 180 degrees
  * Rotate 90 degrees clockwise
  * Flip horizontally
  * Flip vertically
  * Transpose across upper left to lower right axis
  * Transpose across upper right to lower left axis

  This allows seven rotate and mirror operations to be
  performed on the JPEG without image degradation. Such
  transformations can only be carried out on complete JPEG
  sample blocks. Common sizes of JPEG blocks are 16x16 or 16x8
  pixels, although greyscale JPEGs usually have 8x8 pixel
  blocks. Because of this limitation, JPEGs may have
  incomplete blocks of anything up to 15 pixels wide at the
  right hand edge, or up to 15 pixels deep at the bottom edge.
  Since these incomplete blocks cannot exist on the left hand
  or top edges, they might not be transformed correctly.

trim edges

  This option may be used in conjunction with "Transform" to
  removes edge pixels of incomplete blocks that are not
  transformed correctly. The information is lost and cannot be
  recovered but trimming is necessary if the transformed image
  is not to appear strange. Incomplete blocks which are not
  affected or which do transform correctly are not trimmed.

  Interactive Help provides details of which edges cannot be
  correctly transformed, and which will be trimmed if "trim
  edges" is ticked, for each of the seven transformations.



######################################################

4. THE JCLEAN STATUS WINDOW

######################################################



This window can be opened and closed from the icon bar icon
menu or by clicking ADJUST over the icon bar icon.

The only setting you can make for this window in the
'Config' file inside the !Jclean application directory is
whether or not the window opens automatically when !Jclean
starts.


Queued, Processed, Completed, Aborted

  These four boxes show the number of JPEGs you've dropped
  into !Jclean, the number processed so far, the number
  successfully completed and written back (or saved to a new
  directory), and the number aborted for error or skipped.


Status: waiting

  This shows the current state of !Jclean's actions. "waiting"
  means that !Jclean is waiting for JPEGs to be dropped on it.
  During processing, "waiting" may be replaced by any of:
  
  queueing   - when the JPEG paths are being stored
  reading    - when the next JPEG is about to be processed
  processing - when a JPEG is being acted upon
  paused     - when the "Pause/Step" button has been clicked
  stepping   - when the "Pause/Step" button is clicked again
  resumed    - when non-step processing has been resumed
  skipped    - when "Skip" is used to miss processing a JPEG
  aborted    - when the processing has been aborted
  
  These messages are also written to the Log file along with
  the time they occurred.

  Under the "status" line is a long icon where the name JPEG
  currently being processed will be displayed. To the right of
  the name is a short icon in which the original size of the
  JPEG is given.


Show Log

  Clicking this button opens up !Jclean's Log file in a text
  editor. Note that any subsequent writes to the Log file will
  not be shown in the displayed copy and that the button will
  have to be clicked again to reopen the file if you want to
  see them.


Pause/Step

  Clicking this button initially causes processing to be
  suspended at the next available opportunity. !Jclean cannot
  pause during queueing, nor during singletasking operation of
  jpegtran, and will not pause during its own comment
  processing (generally quite quick).
  
  A second click initiates a step process whereby the current
  JPEG is processed and the next in the queue read so that you
  can decide whether to skip or process it.


Resume

  Clicking this button resumes normal non-step processing
  after a pause. The "status" line will show "resumed" while
  the current JPEG is being processed and will revert to
  showing "processing" thereafter.


Skip

  Click this button to 'skip' or abort the process of a single
  JPEG, preferably while in step mode.


Abort+End

  This button aborts the current process and ends all
  processing on the queued list of JPEGs. You cannot resume
  processing on any unprocessed JPEGs in the queue but must
  drop them into !Jclean again.



######################################################

5. SCRAP WORKSPACE, LOG AND COMMENTS FILES

######################################################


!Jclean uses !Scrap workspace to store two copies of the
JPEG currently being processed and up to four text files:
one for reports generated by jpegtran, one for queued JPEG
filepaths, and two for stored comment filepaths.

The same !Scrap directory is used for !Jclean's Log file and
for the Comments file in which comments from JPEGs may be
written. Up to 9 backup copies of both Log and Comments
files may also be stored in the !Scrap directory.

When !Jclean quits normally, the JPEGs and temporary text
files are deleted but all Log and Comments files are kept.



######################################################

6. CUSTOMISING JCLEAN - MESSAGES, CONFIG AND !RUN

######################################################


You do not need to go into the Basic program or the
Templates file to translate any of the options window
legends, menu options, error messages or help messages into
other languages. !Jclean reads them all from the 'Messages'
and 'Config' files which may be found inside the !Jclean
application directory.

The 'Messages' file contains legends for !Jclean icons, Log
and error messages, and interactive Help messages. You
should not need to change anything unless translating these
into another language. The window and icon sizes are
designed to accommodate the default English legends in 12 pt
Corpus.Medium, which is the widest of the ROM fonts. (I use
Sassoon.Primary.Oblique at 12 pt height, 13.25 pt width as
my desktop font.)

The 'Config' file allows you to customise most of !Jclean's
startup conditions and behaviour. Edit it in a text editor.
Extensive comments are included to assist you. You are
advised to make a copy before editing (e.g. '~Config') just
in case of accidental deletions.


The !Run file sets some system variables which you can
change.


Set Jclean$ScrapDir <Wimp$ScrapDir>.Jclean

  You can change this to point to a RAM disc for faster
  operation provided you ensure that the RAM disc is large
  enough. Log and Comments files will be lost at shutdown.


Set Jclean$LogDir <Wimp$ScrapDir>.Jclean
Set Jclean$CommentsDir <Wimp$ScrapDir>.Jclean

  You can change either or both of these two variables to
  point to other directories, thus removing the Log and/or the
  Comments file from !Scrap. If !Jclean finds the directories
  don't exist when creating the Log and Comment files, it will
  revert to using <Jclean$ScrapDir>. Errors might occur if the
  directories are deleted during !Jclean operations.


Set Alias$jpegtran <Jclean$Dir>.jpegtran %%*0

  If you normally have a copy of jpegtran available for
  applications to use (e.g. inside !Boot.Library), you can
  change this variable to point to that copy. Make sure it's
  not an older version than the one inside !Jclean.



######################################################

ACKNOWLEDGEMENTS

######################################################


My thanks to Nick Roberts for showing me how to redirect
error messages from jpegtran.



######################################################


Bug reports: david@dacha.freeuk.com

Web site: http://www.dacha.freeuk.com/


######################################################

end of !Help file.
