Was kann das Programm?

What does wshForCZP do?

wshForCZP is a tool to assist CZPBatch, the batch processing application of CombineZP. It makes batch processing easier by copying the source image folders to one working directory and writing the results to a target directory if required.

The operation of CZPBatch isn't affected by wshForCZP - wshForCZP simplifies just preliminaries and refinishing for a run of CZPBatch.

I developed wshForCZP in the course of work on focus stacking with CombineZP (especially with CombineZP macro «All Methods» to compare the results of diverse image processing methods). When I realized that I had to click through the same preliminaries and after-treatments again and again I automatized these jobs as far as possible.

Bug reports and proposals please to:

wsh.for.czp@wsh-wsh.de


Hilfe-Anleitung

wshForCZP's Help File

The help file you're reading makes frequently use of a colour based format to mark active texts: if a text like this one is labeled by bold letters of dark violet colour, you can make visible a highlight in an accompanying image by moving the cursor over the text; the colour of the text will change to red when it is touched by the cursor:

The application wshForCZP uses two languages - German and a language I hope having some similarity to English. I apologize for this text to the people of the islands that brought up William Shakespeare; I tried my very best.

Feel free to send corrections and improvements to wolfgang.schlegel@wsh-wsh.de.

Bad English I can quite good.

W.S.


Installation

Installation of wshForCZP

wshForCZP must be installed in the same directory as CombineZP. If you didn't install CombineZP in the default installation directory "C:\Program Files (x86)\Alan Hadley\CombineZP" you have to change the installation directory during the installation of wshForCZP:

During the installation process the following files are copied to the installation directory:

  • Save In Loop.mac
  • wshForCZP All Methods.mac
  • wshForCZP.czm
  • wshForCZP.dll
  • wshForCZP.exe
  • wshForCZP.ico
  • wshForCZP5.bmp
  • wshForCZP_Deutsch.chm
  • wshForCZP_English.chm
  • wshforczpA.bmp
  • wshForCZPB.bmp
  • wshForCzpCounter.ecd
  • wshForCzpCounter.exe

If needed eventually some more dlls are supplied.


Anfangs-Konfiguration

Initial Configuration of wshForCZP

Some properties of wshForCZP can be configured. During installation they get their default values. You don't have to care about most of them for the moment. Important is the working directory of CZPBatch; it's default value is "C:\czpBatchFolder". It's not so bad if this directory doesn't exist, wshForCZP will notify you about this and supply alternative remedies for the problem:

The simplest solution for the problem at this point is to create the default CZPBatch working directory by selecting the first option.

The directory you choose here you'll have to specify later in the application window of CZPBatch:


Erster Start

First Start of wshForCZP

After first starting wshForCZP you'll see the main window. Now you can perform two actions: you can choose folders containing source images for batch processing or you can edit configuration settings. Moreover you can change the language used by the application (English or German) or show this help file.

  • If you want to choose folders containing source images select the menu item «Edit → Select folders» respectively click the corresponding button in the toolbar.
  • If you want to edit configuration settings select the menu item «Configuration → Edit configuration» respectively click the corresponding button in the toolbar.
  • If you want to toggle the language of the application select the menu item «Language → Toggle language» respectively click the corresponding button in the toolbar.
  • If you want to see the help file you are reading select the menu item «Help → Help Topics» respectively click the corresponding button in the toolbar.


Konfiguration

Configuration Settings of wshForCZP

By selecting the menu item «Configuration → Edit configuration» (or clicking the corresponding button in the toolbar) you get a dialog for configuring the operations of wshForCZP. For the moment you needn't take care of these configuration settings, the program works using the default values. When you got some experience with wshForCZP you can use it more flexibly by means of changes in configuration.

There are three tabs in the configuration dialog:

  1. Folders and Files
  2. wshForCZP Actions
  3. Sound Events

By clicking the button «Restore defaults» you can reset all configuration settings on the current tab to their default values. If all configuration settings on the current tab are set to their default values this button is deactivated.

By clicking the button «Set entire configuration to defaults» you can reset all configuration settings of wshForCZP to their default values. If all configuration settings of wshForCZP are set to their default values this button is deactivated.


Tab Ordner

The Configuration Tab «Folders and Files»

In this tab you can configure three properties of wshForCZP: Source directory for CZPBatch, Initial folder for image folder selection, and the Name for image output folder.

Source directory for CZPBatch

Here you specify a working directory for CZPBatch; this directory must be selected in CZPBatch's input field «Outer Folder». By clicking the button «Browse» you bring up a dialog for selecting an existing directory. The default is "C:\czpBatchFolder".

You can choose any directory for this purpose; however it must be on the same computer as the CombineZP installation. It's recommended to use this directory exclusively for batch processing by means of wshForCZP and CZPBatch. CZPBatch creates a subdirectory called CZPoutputs in this directory - this directory may stay there without causing trouble, CZPBatch writes it's own output images to it. No more subdirectories should exist in the directory specified before and after the operation of wshForCZP.

If after an irregular termination of wshForCZP respectively CZPBatch some subdirectories should remain in the specified working directory you will be notified of this at the next start of wshForCZP; in this case you should delete those directories, but save output image files eventually located therein before. During the batch processing initiated by wshForCZP you will find subdirectories and files in this working directory which you should let rest in peace; if they were deleted manually before the batch processing is finished the operation of wshForCZP would be disturbed. If all processing is done regularly wshForCZP will automatically delete all subdirectories (except CZPoutputs) and files after processing has finished.

Initial folder for image folder selection

Here you specify which folder will be initially opened when you bring up the dialog for choosing source folders. The dialog can start without any folder opened or at the folder which was selected last in wshForCZP. It's also possible to specify a certain folder to open the dialog with: this may be the desktop, the folder "Private", the folder "Pictures", or any folder else you can select by means of the button «Browse».

The default is the folder last used in wshForCZP.

Name for image output folder

Here you specify a name for the folder which is created by wshForCZP in the source folder to receive the images produced by the batch processing.

The default is "output".

This folder will never be overwritten by wshForCZP; if the source folder already contains a subfolder of this name wshForCZP will append a numerical suffix to the name of the newly created folder (e.g. "output_0001" if "output" already exists).


Tab Aktionen

The Configuration Tab «wshForCZP Actions»

In this tab you can configure two properties of wshForCZP: the name of the directory CombineZP uses for the Output of "Export Rectangles" and the operation method concerning the Check for uniform dimensions of source images.

Output of «Export Rectangles»

In an input field you can specify the name of the folder to which CombineZP writes the image files created by the menu command «Export Rectangles».

Default is CombineZP's default "rectangles". If you don't have some special reason to put the outputs of «Export Rectangles» to a directory of a different name you'll leave this value on the default.

Now you can specify through three option fields how wshForCZP should handle the contents of such folders.

This is based on the operation method of CombineZP's menu command «Export Rectangles» - this command exports even the frames "Out" and "Picture". If you just want to get some region in a series of in other respect still unprocessed images you can't make too much use of the frames span class="folder_name">"Out" and "Picture" - they are simply black. If you now by means of «Export Rectangles» create some series of image regions which are intended for focus stacking the two mentioned frames can get annoying. By means of our three option fields you can determine how to handle image files which are located in a folder of the name specified in the input field (default as mentioned "rectangles") AND which contain in their file names either the string "out" or the string "picture". wshForCZP can treat such files in the same way as any others, but they can also be ignored for batch processing or even additionally deleted from the source folder (the latter option is to be used with care: you could quickly delete something you had still needed!).

The default is to ignore such image files.

Check for uniform dimensions of source images

CombineZP needs a stack of frames with uniform dimensions to apply the focus stacking macros. wshForCZP can check during it's preliminary operation whether this condition is fulfilled. This check always makes sense but unfortunately consumes time. If you're sure that all your images are of identic dimensions you can skip this test. There are three options:

  • Always prompt for check or not
  • Perform check and don't prompt
  • Don't perform check and don't prompt

Default is the user being prompted.


Tab Signale

The Configuration Tab «Sound Events»

In this tab you can determine how wshForCZP will notify you about progresses in batch processing by sound events. The first sound event is played when a single source folder has been processed, the second sound event signals finishing of the entire batch processing. The second event may differ in dependency of irregularities occuring during finishing operations of wshForCZP; there can be a sound for finishing with or without errors.

Such irregularities most are due to errors in writing files, which can be caused by network problems, missing writing permissions, or a lack of hard disk space. Together with the sound event for «Finished with errors» wshForCZP will present to you a message box containing a detailed listing of the errors in such cases.

Sound event for «One folder finished»

You can mute the sound event for «One folder finished», you can use the default sound event or you can use your own .WAV file for this purpose. By clicking the button «Play» you can listen to the current event, by clicking the button «Browse» you can select an existing .WAV file for this sound event.

Sound event for «Entire batch finished»

The sound event for «Entire batch finished» can also be muted. If it is audible, you can select different sound events for Finished perfectly correct or Finished with errors; you do this in exact analogy to the way you select the sound event for «One folder finished».

Default: all events are audible and use the default sounds.


Arbeitsablauf

A typical run of wshForCZP

  1. Start the application wshForCZP.
  2. Choose source image folders. For this purpose click the button «Select source folders» on the very left of the toolbar.
  3. In the upcoming dialog «Choose source folders» choose a folder by selecting it and clicking the button «OK». After having choosed the last source folder close the dialog by clicking «Cancel».
  4. Wait until application window of CZPBatch appears.
  5. Be sure the input field «Outer Folder» shows the contents of the working directory specified by the configuration of wshForCZP.
  6. In the application window of CZPBatch select an appropriate Macro and an appropriate Macro Set.
  7. Close the application window of CZPBatch by clicking «OK».
  8. The rest is done automatically by wshForCZP. After CZPBatch has finished it's operations there will appear again the application window of wshForCZP. Anew you will be entertained by a message box containing a progress bar.
  9. Now wshForCZP moves the created images to newly created subdirectories of the source folders. Finally wshForCZP brings a message box to the screen notifying you that batch processing is finished.
  10. If there occured any irregularities during batch processing the message box contains a listing of the errors.
  11. When you close the message box wshForCZP terminates.


Symbolleiste

The Toolbar

All important functions of wshForCZP are available through buttons in the toolbar.

Select source folders

By clicking this button you start a new batch processing session. The dialog for choosing source folders will appear. The same functionality is available from the menu item «Edit → Select folders».

Configuration dialog

By clicking this button you get access to the configuration settings of wshForCZP. The configuration dialog will appear. The same functionality is available from the menu item «Configuration → Edit configuration».

Toggle language

By clicking this button you can toggle the language used by wshForCZP. between English and German. The same functionality is available from the menu item «Language → Toggle language».

Show help file

By clicking this button you can bring up the help file you are reading now in the version of the current language. The same functionality is available from the menu item «Help → Help Topics».


Dialog Quellordner-Auswahl

Dialog «Choose source folders»

If you select the menu item «Select folders» the following dialog appears. There you can choose the folders containing the image files you want to process:

You choose a folder by marking it and then clicking «OK». The paths to the chosen source folders appear in the main window. The source folders don't have to be on the same computer, they may be available over the network.

When you have chosen all the source folders you want to process click on «Cancel» in the dialog - the dialog will close, and wshForCZP will start the preliminary processing of the chosen source folders. During this processing you'll see a message box containing a progress bar:

When all temporary folders are prepared wshForCZP will start the program CZPBatch. In it's application window you select a macro set, a macro and in case the correct working directory and then start the operation of CZPBatch by clicking the button «OK».


CZPBatch-Anwendungsfenster

Selections in the window of CZPBatch

Here you have to take care of two settings.

  • First the input field «Outer Folder» must show the contents of the directory you specified in wshForCZP as working directory of CZPBatch (see configuration setting «Source directory for CZPBatch). You'll see the path to the working directory on the upper left of the application window of CZPBatch. You can change it in the field «Outer Folder».
  • Second you must specify a Macro and a Macro Set cooperating with wshForCZP. As examples «wshForCZP» and «wshForCZP All Methods» were added to the installation; you can use your own customized macros, but they have to meet certain conditions (see here).


Details

Details of Operation of wshForCZP

wshForCZP works in two different modes: preparation (accessible by the menu item «Edit -> Select folders» respectively the first button of the toolbar) and finishing (wshForCZP automatically switches to this mode if the program detects unprocessed CZPBatch output in the working directory of CZPBatch). Normally you start the preparation mode; wshForCZP will be started in finishing mode automatically after batch processing by CZPBatch has finished.

Preparation Mode

When you start the preparation mode there should be no files and no subdirectories (except maybe CZPoutputs) in the working directory ofCZPBatch.

After selecting the menu item «Select folders» there will appear a dialog for choosing the folders containing the image files to process. You choose a folder by selecting it and then clicking «OK». The paths to the chosen source folders will appear in the main window. When you have chosen all them source folders you want to process click on the dialog's «Cancel» button - the dialog will close and wshForCZP will start the processing of the chosen source folders.

According to configuration setting you may now be asked if wshForCZP should check the images in the source folders for uniform dimensions (you can also configure wshForCZP to perform this check or to abstain from it without prompting; see here). If there are any problems concerning the CZPBatch working directory specified by the configuration setting (see here), you will be notyfied by a message box prompting you for remedies.

If the checking of image dimensions is performed and images of different dimensions are detected in a source directory there will appear a message box containing information thereto. It gives you the options to exclude the image files of deviating dimensions or the entire source folder from batch processing or to process the images anyway; if you don't like any of this alternatives you can terminate the program wshForCZP at this point.

Now wshForCZP starts the preliminary operations. For each source folder there will be created a subdirectory in the CZPBatch working directory; the source images will be copied to this subdirectory. A message box owning the ingenious title «Please wait...» and a progress bar banishes boredom while wshForCZP is busy preparing the CZPBatch working directory.

The image files will in any case be copied and not just moved. Indeed it would be possible to improve speed by just moving them, but in developing wshForCZP priority was given to safety - if batch processing was terminated by any unexpected error you had to move back the image files to their hereditary location manually, in the course of which this and that could go wrong. The source image files stay all the time at their initial location in the file system and are only copied.

In addition to the subdirectories containing the source images wshForCZP creates the files wshForCZP_Anzahl and wshForCZP_KontrollMap in the CZPBatch working directory. They are used internally and deleted automatically during cleaning up operations in the finishing mode after the batch processing. You don't have to take notice of these two files in any way - however you must not delete or change them during batch precessing with wshForCZP, otherwise wshForCZP will slip away.

wshForCZP_Anzahl contains simply the number of subdirectories still waiting for processing; it's content gets decremented by any run of wshForCzpCounter.exe. When the content reaches zero wshForCZP will automatically be started in finishing mode.

wshForCZP_KontrollMap contains the mapping of the temporary subdirectories in the CZPBatch working directory to the input folders containing the original source images.

When wshForCZP has finished it's preliminary operations the program CZPBatch is started automatically. Be sure the input field «Outer Folder» of CZPBatch shows the contents of the CZPBatch working directory specified in wshForCZP's configuration settings (default is "C:\czpBatchFolder"). In the fields «Macro Set» and «Macro» select items in accordance with criteria explained elsewhere (see here). The remaining options affect only the output of CZPBatch to the directory "CZPoutputs". Start batch processing by clicking «OK». You can choose to be notified of accomplished procession of single source folders by sound events; also available is a sound event for finishing the entire batch processing (see configuration settings).

Finishing Mode

wshForCZP is started automatically in this mode when CZPBatch has finished it's operations (and if you specified a suitable macro for CZPBatch; see here). In this mode you are not expected to supply any input; wshForCZP simply writes the resulting images created by CZPBatch to subdirectories of the source folders. If problems should be found during this operation (due to missing writing permissions or difficulties in network) wshForCZP will notify you by means of a final message box.

In such an error case the created image files eventually are located in an emergency directory called wshForCZP_save which is located in the CZPBatch working directory. wshForCZP_save contains subdirectories whose names will give you a hint at the corresponding source image folders. In these subdirectories you will find the output directories containing the output images - you can move them manually to the source image folders. When you got saved all them output folders you can delete wshForCZP_save manually.

Details about errors and emergency directory you'll find in the message box - you can take them from there by clicking the button «Copy to Clipboard».

It's worth to remark again that in developing wshForCZP safety of source files was given priority - wshForCZP will never overwrite a subdirectory already existing in a source directory. If there exists a subdirectory called by the name of the output directory to create wshForCZP will create a new subdirectory with a name differing in an appended numerical suffix.

If any problems occured in batch processing and CZPBatch terminated in an unexpected way you could try to start wshForCZP - if the contents of the files wshForCZP_Anzahl and wshForCZP_KontrollMap in the CZPBatch working directory are consistent, wshForCZP will switch automatically to the finishing mode and start finishing operation. If the contents of these files are inconsistent wshForCZP will notify you by means of a message box and terminate.


Makro-Anleitung

Indispensable Properties of the Macro for CZPBatch

The macros, macro sets, and commands described here are supplied by the installation of wshForCZP - you'll find them in the files

  • wshForCzpCounter.ecd
  • Save In Loop.mac
  • wshForCZP All Methods.mac
  • wshForCZP.czm

Creation is described here just for demonstration purposes to give you a starting point for creating your own macros.

First you need a command to start the console application wshForCzpCounter belonging to wshForCZP. You create this command from CombineZP by means of the menu item «Macro → Edit → Commands»; edit one of the still unused external commands (called «External Command #n»): in the input field «Name» as in the input field «Program» you have to type the string «wshForCzpCounter»; the input field «Command Line» you leave blank. If you save this command it will be available in the listbox «Command» of the macro editor under the name «wshForCzpCounter». A macro intended to cooperate with wshForCZP must contain this command as the last command:

  • ...
  • ...
  • wshForCzpCounter(0,0,0)

Like wshForCZP.exe the executable file wshForCzpCounter.exe must be located in the same directory as CombineZP.exe and CZPBatch.exe (typically "C:\Programme\Alan Hadley\CombineZP"; you have to select the installation directory of CombineZP during the installation of wshForCZP).

Furthermore we have to look at the macro «Output Active Frame»: using this command a single macro can save multiple output images. To save all results of the standard macro «All Methods» with CZPBatch you have to do the following:

  1. Create by means of the macro editor a short macro called «Save In Loop». It should consist of just three commands:
    • Output Active Frame(1)
    • Go (Relative) to Frame(1)
    • Restart Macro
  2. Create a macro called «wshForCZP All Methods»; for this purpose append to the standard macro «All Methods» the two following commands:
    • ...
    • ...
    • Save In Loop(1,0,1)
    • wshForCzpCounter(0,0,0)

The macro «wshForCZP All Methods» saves the results of all 6 standard macros to a subdirectoriy called "output". wshForCZP in finishing mode searches image files in a subdirectory of this name and moves them to a subdirectory of the source folder (unwieldy file names are shortened to the name of the corresponding macro). To make this function you have to select the macro «wshForCZP All Methods» in the input field «Macro» of the application CZPBatch (or some other equivalent macro with the required properties, if you want to get something else as a result). In any case indispensable for wshForCZP is «wshForCzpCounter(0,0,0)» as the final command.

The macro set is saved as "wshForCZP.czm".


Die Menueleiste

The Menu Bar of wshForCZP

The menu bar of wshForCZP contains the following submenus:

  1. Menu «Edit»
  2. Menu «View»
  3. Menu «Configuration»
  4. Menu «Language»
  5. Menu «Help»

All important menu commands are also available through buttons in the toolbar. If you are owner of a mouse you will typically never need the menu bar.


Menue Bearbeiten

Menu «Edit»

The menu «Edit» contains only one command:

  1. «Select folders»

If you select this menu item you start a new batch processing session. The dialog for choosing source folders will appear. The same functionality is available from the button «Select source folders» in the toolbar.


Menue Ansicht

Menu «View»

The menu «View» contains two commands:

  1. «Toolbar»
  2. «Statusbar»

Using this commands you can hide and reshow the corresponding bar. Both commands are totally useless.


Menue Konfiguration

Menu «Configuration»

The menu «Configuration» contains only one command:

  1. «Edit configuration»

If you select this menu item you get access to the configuration settings of wshForCZP. The dialog «Configuration Settings» will appear. The same functionality is available from the button «Configuration dialog» in the toolbar.


Menue Sprache

Menu «Language»

The menu «Language» contains three commands:

  1. «German»
  2. «English»
  3. «Toggle language»

If you select one of the first two menu items the application wshForCZP will change to the corresponding language; if you select the third menu item the application will change to the language currently not in use - the latter functionality is also available from the button «Toggle language» in the toolbar.


Menue Hilfe

Menu «Help»

The menu «Help» contains two commands:

  1. «Help Topics»
  2. «Info about wshForCZP...»

If you select the first menu command you bring the help file you are reading now to the screen. The same functionality is available from the button «Show help file» in the toolbar.

If you select the second menu command you'll see a small message box containing information about version number and copyright.