DStretch Help

DStretch is a plugin to the imaging program ImageJ.  I wrote DStretch to help enhance faint pictographs.  Over the years I have visited many rock art sites whose art has faded over time.  DStretch can bring back the beauty of these faded sites.  We may never know the meaning of the art, but at least we can get a better idea of what the artist intended.

DStretch performs a decorrelation stretch on color images.  This enhances faint colors in the image.  By doing the stretch within different colorspaces one can get different results.  DStretch has many colorspaces avaliable, including some that have been specially developed to give good results for pictographs.

I sometimes give out a handout(pdf) at presentations.  It is partly the same as this page, but also has some additional information.

Current version is 6.4, February 2008.   New colorspaces in version 5 are LRE (good for reds), LDS (good for yellows) YBK (good for blue-blacks), and YBR (sometimes gives better looking reds than YDS).   The "L" spaces take longer to calculate, but can give excellent results.  The "Y" spaces are very fast so I often use them first.  The handy CRGB matrix is also fast.  For red pictographs I use either the CRGB matrix or the LRE colorspace.  Sometimes LDS works well if the background rock provides some yellow that contrasts with the red.  YBK de-emphasizes reds and can bring out dark blue-black pigments.  LDS is a good all-around enhancement choice which brings out yellows much better than LAB (but at the price of enhancing noise and jpeg artifacts).  In 5.4 I created a new "simple" GUI which makes DStretch even easier to use.  The old interface is available in expert mode.

To get the current DStretch version email DStretch@prodigy.net

Photography Tips

1. Camera: Bigger sensor is better, DSLR’s are good. Lens makes a difference.
2. Camera megapixels: When choosing a camera higher is not necessarily better, but use all you have (See 6.)
3. Best format is tiff or raw. If you use jpeg use the highest quality setting.
4. Use the lowest ISO setting available on your camera.
5. Expose adequately: long enough to get correct exposure, but short enough to avoid camera shake.  Use flash if you have to.  Avoid direct sun.
6. If shooting jpegs use the highest camera resolution setting (highest megapixels).

Professional photographers often advise "Expose Right".  This is advice for those shooting raw to put the histogram a stop to the right of the normal exposure, i.e. overexpose a little.  When you "develop" the raw data you compensate for the overexposure.  This technique can reduce noise levels in dark areas of the image.  Less noise is good because the enhancement process greatly increases noise.  Tip number 4 above is important because lower ISO gives lower noise.

Other Digital Imaging Tools

I highly recommend Irfanview for viewing images and for browsing the images in a directory. It’s small, fast and free. It has a thumbnail mode and a slideshow mode. During installation, associate it with image file extensions (.jpg, .tif, etc). Additionally it is possible to make ImageJ the default editor for Irfanview.  For uses beyond browsing (i.e. for color cast corrections) PhotoShop is the standard, but is expensive. I don’t own PhotoShop, although I do have an old version of Photoshop Elements that I sometimes use. I also use PaintShop Pro and the Gimp (freely available).  Over time I have added many useful corrections to DStretch and now I seldom have a need for the other programs. I continue to add new routines to DStretch and welcome suggestions from users.

Installation

Install ImageJ first.  ImageJ is an imaging program for the medical community that has many features for manipulating and analyzing images.  Place the dstretch_.jar file in the plugins folder of ImageJ.  When you next start up ImageJ there will be DStretch menu items under the plugins menu.  'DStretch...Run' is the menu item for the main DStretch program.  Use the file open and file save menu items of ImageJ to get images into and out of the DStretch plugin.   The other DStretch menu items are described below.

Using DStretch

Open an image using the ImageJ file open menu then choose 'DStretch...Run' from the DStretch menu under the Plugins menu.  A new window will open with the DStretch panel under the image.  If you choose the 'DStretch...One' menu item the DStretch panel will install itself beneath the image without opening a new window.  There are two DStretch GUI's: simple and expert.  'DStretch...Run' starts DStretch up in simple mode, but you can always change to expert and vice versa.  Set the scale (the default 15 is a good place to start) then hit one of the colorspace buttons: YDS,YBR,YBK,CRGB,LDS,LRE,RGB.  In the latest version the colorspace buttons are colored orange.  This will do a decorrelation stretch on the image using the colorspace.  CRGB not exactly a colorspace, see explanation of colorspaces and the CRGB button below.  The 'Auto Contrast' button will optimize contrast in the image.  I recommend using it after a stretch.  The 'Flat' button evens out illumination in the image.  Use it before or after a stretch.  If used before it can change the stretch color behavior.  If used after it will leave the colors alone, but flatten the brightness.  Follow with the 'Auto Contrast' button.  DStretch creates false color images and sometimes the colors can be pretty wild, especially when using CRGB.  I have added a 'Sat' button to simple mode so you can tame the wild colors by decreasing the saturation of the stretched image.  The 'Save' button saves the image as a jpeg file.  It gives you the choice to change the jpeg quality before saving.  Although I always use the highest (100) jpeg quality if I save an image before DStretch, afterwards, if I do not intend to do other processing, I will use 75 to reduce file size.  The 'Save' button also allows you to save the matrix used by DStretch as a text file.  The matrix file also documents the coefficients used for the YXX and LXX adjustable colorspaces.  The 'Reset' button reverts back to the original image.  To avoid doing a stretch on a stretch, DStretch will reset automatically before a second stretch.  The 'Auto Contrast', 'Flat', 'Sat' and 'CB' buttons do not count as stretches.  This lets you perform these either before or after a stretch.

The YXX and LXX buttons give stretches in a user adjustable colorspace.  You can try your hand at designing a colorspace that will give better results on your image.  See the discussion below for advice on how to use them.

Colorspaces

A colorspace is a particular way of decomposing a color into components.  RGB is the most well known.  In the RGB colorspace each color is split into red green and blue components, i.e. a color is broken up into three numbers, one number gives the strength of red in the color, another the strength of green in the color and finally a third number gives the strength of blue in the color.  There are other colorspaces besides RGB, for instance CMYK (cyan, magenta, yellow, black) used for printing.  The YUV colorspace was devised for TV.  It splits a color into brightness (Y) and color (U,V) components.  By experiment I have found some colorspaces that work nicely on rock art images.  In the spirit of names such as RGB, YUV, LAB, I have named mine using 3 letters.  CRGB is not a colorspace, it is the name of a matrix.  When you do a stretch the program analyzes the image inside the colorspace you have chosen then creates a matrix that defines the stretch.  To create the new image the program applies the matrix to each color in the image.  CRGB is a particularly useful matrix that was created for an image in RGB colorspace.  You can save the matrices created by your stretches by checking the box on the 'Save' dialogue.

Adjustable Colorspaces

There are two adjustable colorspaces, a 'Y' one, based on YDS, and an L one, based on LAB.   In these colorspaces  there are three or four multipliers that can be adjusted.  For YXX the default (1,.8,.4) was chosen to give better looking reds than YDS.  Using (1,.2,1.6) can give improved enhancement of black-blue pigments.  I call this combination YBK (it used to be called YBB).  YDS is given by (1,.5,1).  In LXX the defaults (1,1,1,1) give the expert mode colorspace LAX, (.5,.5,1,1) gives the usual LAB.  The 'yellow enhance' (.5,.5,1,.5) and 'red enhance' (.5,.5,.5,1) parameter sets are very useful.  I call them LDS and LRE respectively.  To get the 'Y' equivalent of LRE try (8,1,.4).  To get the 'L' equivalent of YBK try (.5,.5,1,.5).  One way I use the adjustable colorspaces is to start with a good enhancement in one of the standard Y or L colorspaces then starting from those multipliers I adjust them slightly until I get the best result.  I have added some adjustable colorspace choices that I have found useful to the builtin menu.

Direct Enhancements

An easy way to use DStretch is to use the DStretch menu entries that look like 'DStretch...YDS', 'DStretch...LRE', etc.  These skip the user interface (GUI) and perform the enhancement directly.  Only the scale needs to be chosen.   If you want a scale other than the default use the 'DStretch...Set Scale' menu item.  To do one of these enhancements open an image in ImageJ, then choose one of the menu commands ('DStretch...YDS', 'DStretch...CRGB', etc).   You can use Undo (under the ImageJ Edit menu or ctrl Z on a PC) or Revert (under the ImageJ File menu) to get back to the original image.  Finishing with 'DStretch...Auto Contrast' often improves the enhancement.  You can make an area selection in the image before doing the enhancements to base the enhancement on just that area.

The BTN LAX enhancement in the direct enhancement menu comes from expert mode.  It can sometimes give some wild very pretty enhancements so I have included it here for ease of use.  The LAX Adj and YBR Adj commands are the same as the LXX and YXX buttons in simple mode.  These are adjustable colorspaces.  See below for some advice on how to use them.

I have added flatten, invert, auto contrast, adjust saturation, and color balance to the direct enhancement commands.  See the "Other Enhancements" section below for a discussion of the flatten command.

Builtin Enhancements

The builtin button in simple mode gives access to enhancements that I have found useful.  These can be either matrices or a choice of multipliers for adjustable colorspaces.  Expert mode has a different set of builtin matrices.

Using DStretch Expert GUI

Open an image using the ImageJ file open menu then choose 'DStretch...Run' or 'DStretch...One' from the DStretch menu under the Plugins menu.  A new window will open with the DStretch panel under the image.  To switch to expert mode just press the 'Expert' button.  Note: in expert mode the image is NOT automatically reset before a stretch.

Choose the colorspace, matrix, and scale then hit the 'DStretch' button to perform the decorrelation stretch.  The colorspace choice is the box under the 'DStretch' button.  The matrix choice is the box to the right of the colorspace.  The defaults: YDS, covariance, 15 are a good beginning.  If 'Map Back' is checked (the default) the decorrelated stretched image is mapped back using the inverse of the decorrelation matrix.  This gives an enhancement closer to the original colors.  In examples 1, 3, and 4 I choose the mapped back covariance matrix (except for CRGB which is a precalculated matrix), but change the colorspace and area selection.   Not mapped back can be useful especially in the RGB colorspace, see example 2. 

Hit 'Reset' after trying an enhancement to get back to the original image.  Unlike simple mode, in expert mode reset is not done automatically.

The "L" spaces can give excellent results but take longer to calculate.  LAB is least subject to jpeg artifacts and image noise and gives enhancements that preserve original colors (especially blacks) the best.  LRE and LDS do better on red or yellow pictographs.  RGB, correlation matrix,  mapped back, can also do well.  YBR is a modified YDS colorspace that gives better looking reds.  YBK can work well on blue-blacks.

If an area selection is placed in the image then the decorrelation will be based on that area and will be applied to the entire image.  A very small area selection can give unpredictable results sometimes giving good enhancement.  You can save the area selection using the ImageJ command: File->Save As->Selection.  To reproduce the enhancement read back the selection before doing the stretch.

If you do find a good enhancement, save the matrix to try on other images.  I found a matrix that does especially well on red pictograph sites.  I ended up using it so much that I made it into a button for convenience.  The 'CRGB' button on the right uses that matrix.  When using the 'CRGB' button the colorspace, matrix, and 'Map Back' choices do not matter.

On a new image I start with the CRGB button, then  YDS and  YBK.  This gives me an idea of what is in the image, whether DStretch will help, and what colorspace works best.  Next I will fiddle with other colorspaces, area selections, and hue shifting to get the best results.  If CRGB works well I will also try LRE, if YDS works well I will also try LDS.   On a recent trip to the Sierra de Guadalupe in Baja California I ended up always doing 3 enhancements on my images: LDS, LRE, YBK.  Scale was 15 except for YBK where I used 20.  Batch mode was very helpful.

Once you get a good enhancement, increase or decrease the scale until it is optimal.  The button 'Auto Contrast' can also help to improve an enhancement (but not always).  I usually optimize the scale first then use auto contrast.  I use flatten to even out illumination, especially to handle uneven flash illumination.  Different results can occur when using flatten before or after enhancement.  I usually will try both ways.

Expert mode does not have a 'Save' button.  To save an image use the ImageJ 'Save as' menu command, or switch to simple mode and use the 'Save' button.   ImageJ filters and adjustments can be applied to the DStretch image either before or after an enhancement.  The ImageJ Process->Enhance Contrast command is a good automatic contrast enhancement routine that I have made into a DStretch button, 'Auto Contrast'.

Use the 'Hue Shift' slider in expert mode to shift the hues of the DStretched image.  This can improve contrast.

Choose 'Built-in' or 'Saved' in the matrix chooser to skip the DStretch computation and use either a built-in or previously saved matrix and colorspace.  In 'Saved" mode when you hit 'DStretch' a file chooser opens where you can load a previously saved matrix and colorspace.  The built-in matrices are ones that have produced interesting results for me on some image.  There is a different one for each colorspace.  The built-in RGB matrix proved to be so useful that I put it into the CRGB button.  This opened up the built-in RGB slot and I put a slightly different matrix there.  The LAB built-in matrix has also proved generally useful.

Use 'Save Matrix' to save the matrix and colorspace in a text file for future use.  This can be used to apply the same DStretch to several images for consistent color enhancement.  It is a good idea to save a matrix that works well on a particular image.  I recommend setting the scale to 10 before creating a matrix that is to be saved.

Other Enhancements

Use 'Other Enhance' to access other enhancement routines.  Once I had the colorspace code written for the DStretch routines I then implemented some more conventional enhancement ideas for the colorspaces.  This is not as comprehensive as what can be done in Photoshop, but since I don't have Photoshop I wanted to see what could be done easily in those colorspaces.  Any ideas for useful enhancements are welcome. 

In the HSL colorspace you can manipulate the hue, saturation and luminance.  Turning up the saturation (with or without doing a hue histogram equalization) can give good enhancements.  Setting it to 0 gives a grayscale image.  I also implemented hue histogram equalization, both conventional and equalization using the square root of the histogram.

In other colorspaces the program calculates an enhancement multiplier and offset for each colorspace variable.  You can keep them or enter your own value.   You can use the LAB enhancement to get a grayscale image.  Just set the a and b multipliers to 0.  This gives a slightly sharper (and noisier) grayscale image than the HSL technique.  I have put the two grayscale conversion methods into the other enhancements menu.  Gray1 uses HSL, Gray2 uses LAB.

In version 4.0 I added an invert routine that creates the negative of the image.  I also added a flatten routine that evens the illumination across the image.  It uses the ImageJ FFT bandpass routine to filter out the low frequency components of the image.  The amount of flattening is governed by a number that you can change.  The default is 10.  A higher number gives greater flattness, but also increases the noise.  Sometimes I use 5 if noise is an issue.  Flattening the image first can alter the balance between luminance and colors in the stretch.  Flattening afterwards will preserve the color strength but flatten the brightness.  If I flatten afterwards I follow up with auto contrast.

Expert Mode Colorspaces

In expert mode more colorspaces (YCbCr, LAX, XYZ, CMX) are available. These are experimental and may disappear if I do not find them sufficiently useful.  Also in this mode the 'Adj Stretch' checkbox appears.  If checked, this gives more control over the decorrelation stretch process.  In most colorspaces you can modify the amount of stretching and the mean of the result.   In expert mode the built-in matrices can be edited before use.

Batch Mode

Batch mode allows enhancements to be done on all the files in a directory with the results placed in a second directory.  Access batch mode from the DStretch menu under Plugins.  Choose the input directory, output directory, then choose the DStretch choices.  Under the enhancement choices are the usual DStretch colorspaces plus some other useful enhancements.  The CRGB button is there as well as grayscale (two versions), flatten, saturate, auto contrast and invert.    Under matrix you can choose covariance (the usual choice) correlation, built-in or saved.  The output format can be jpeg or loseless tiff.   If you intend to further enhance after batch mode use tiff or jpeg with 100 quality, if not jpeg with 75 quality is good enough for most viewing and provides significant compression.  You can choose whether to map back the stretch or not and to apply auto contrast after the stretch or not.  The auto contrast enhancement option is there in case you just want to apply auto contrast to all the files in a directory without any other enhancement.

Hue Mask Panel Help

Use the 'Hue Mask Panel' to keep only a range of hues and replace the others with either black or original image.  The hsl values of the pixel under the pointer can be seen in the ImageJ status bar.  Thic panel can be accessed only when in the expert panel.

The Hue Mask panel allows the isolation of an image region by hue.  Use the DStretch panel first to enhance the image.  This panel is a tool that can transfer a region from a false color DStretched image back to the original image.  The hues within the region must fall in a separate range from the rest of the image or the region must be isolated by a selection area.  Place the mouse pointer over a pixel to see its hue in the ImageJ status bar.  The hue is the first number after "hsl=" in the status bar.  Determine the range of hues in the region and enter the minimum and maximum.  The hue histogram tool included with DStretch is useful in determining this range.

Hues are specified in degrees, 0 = 360.  The minimum can be less than 0 and the maximum can be greater than 360.  This allows for a hue range that wraps around 0/360.  The figure can be further isolated by drawing an area selection around it.  ImageJ supports several different area selection types including freehand drawing.

Clicking on 'Do Mask' will replace any hues outside the range or outside the area selection with black  After performing the mask the isolated hues can be shifted to a different color using the Hue Shift slider.  I have added options so you can specify ranges of lightness and saturation in addition to the hue range.

After masking the result is a kind of binary image, either a pixel is black or it is non-black and contains a hue in the masked range.  This lends itself to the use of "image morphology" type of algorithms to clean up isolated pixels.  I have created some cleaning tools for a hue mask image that look at the 8 nearest neighbors of a pixel and set to non-black or set to black the center pixel based on the number of non-black neighbors.  If the center pixel is to be set to a non-black value that value is calculated to be the average of the non-black neighbors.

Clicking on 'Clean' after masking will bring up options for removing isolated non-black or black points.  The strength of the cleaning is adjustable and the cleaning can be repeated a number of times.  Setting the strength to 7 makes the "clean" into a classical morphological erosion with a 3x3 square structuring element.  Setting the strength to something else will select an idiosyncratic cleaning algorithm devised by myself.  I like cleaning with strength 4 with  6 iterations.  Using the basic cleaning step as an erosion one can do a morphological open (erosion followed by dilation).  The number of iterations (n) determines the number of cleans followed by the same number of dilations.  This is equivalent to doing an open by a (2n + 1)x(2n+1) square.  The open result is then ANDed with the original hue masked image.  The open can be done either at the current resolution or at half resolution with the result applied to the current resolution image.

Clicking on 'Dilate' after masking enlarges the non-black areas by dilation.  This can be used in conjunction with cleaning (a form of erosion) to improve the shapes of masked elements.  Number of neighbors used for dilation and number of iterations can be chosen.  My algorithm for this sets the center pixel to non-black if it has >=  n non-black neighbors.  Choosing n = 1 gives a classical dilation by a 3x3 structure element.  Similarly as for the clean button there are close operations (dilation followed by erosion) available at two different resolutions.  The close result is ORed with the current image.

After masking and cleaning clicking on 'Add Original' will replace the black areas with the original image.

There are buttons for replacing the non-black pixels in an area selection with 1: the average hue of all the non-zero pixels in the selection, 2: the average saturation of all the non-zero pixels in the selection or 3: the average RGB value of all the non-black pixels in the selection.

The hue mask routines can be used to clean up a previously saved enhanced image.  In this case open the enhanced image in ImageJ, run DStretch and switch to the Hue Mask panel.

Examples   DStretch Home