Version 1.1 from http://zxds.raxoft.cz/pzx/pzxtools_11_src.zip

changes.txt

@@ -0,0 +1,17 @@
+1.1 (21.4.2011)
+
++ Added -l option to pzx2txt and annotate_pulses.pl script, allowing
+  convenient annotation of pulses with their initial pulse level.
+
+1.0 (21.8.2007)
+
+* Fixed handling of incomplete command line arguments.
+
+1.0 rc 2 (2.8.2007)
+
+* Fixed overflow bug in WAV generation, which caused pzx2wav render
+  all pauses as very short ones.
+
+1.0 rc 1 (28.6.2007)
+
++ First release.

docs/pzx_scripts.txt

@@ -0,0 +1,182 @@
+PZX scripts documentation
+=========================
+
+The PZX tools suite contains few scripts which demonstrate the possibilities
+of processing the PZX files dumped as text files. Such text files are
+generated by pzx2txt and can be converted back to PZX by txt2pzx.
+See PZX text format specification for more details about the format itself.
+
+The scripts themselves are simple perl scripts which read the input from
+the file(s) specified on the command line (or standard input if no such file
+is specified) and write the output to standard output.
+
+The following scripts are currently available:
+
+expand_pulses.pl
+----------------
+
+This script expands the pulses so each pulse is output on a separate line,
+as if pzx2txt -e was used in the first place.
+
+Some scripts may require their input expanded in this way.
+
+annotate_pulses.pl
+----------------
+
+This script annotates the pulses with their initial pulse level,
+as if pzx2txt -l was used in the first place.
+
+This may be useful if you want to verify the polarity is as expected.
+
+adjust_pulses.pl        
+----------------
+
+This script may be used to adjust pulse durations by specified scale factor
+and bias. It even supports use of different factor and bias depending on
+whether the pulse level is low or high. This may be useful if the pulses
+were created using either too low or too high level threshold. Note that
+in this case the script needs the pulses expanded, see expand_pulses.pl.
+
+The script first multiplies each pulse duration by scale factor, then adds
+the bias value. Both factor and bias are chosen according to current pulse
+level. The resulting value is clamped to <0,2^32-1> range and output.
+
+The scaling factor and bias is set by use of SCALE and BIAS keywords in the
+input stream. The syntax is as follows:
+
+SCALE [a] [b]
+
+This sets the scaling factors for low and high pulses to values a and b,
+respectively. If b is not present, both factors are set to a. If neither a
+nor b is present, both factors are set to 1.
+
+BIAS [a] [b]
+
+This sets the bias for low and high pulses to values a and b,
+respectively. If b is not present, both biases are set to a. If neither a
+nor b is present, both biases are set to 0.
+
+Example:
+
+        SCALE 0.9 1.1   - Fix effect of sampling threshold biased towards high pulses.
+        SCALE 2         - Make every pulse twice as long.
+        SCALE           - No more scaling.
+
+        BIAS 0 855      - Make every high pulse 855 T cycles longer.
+        BIAS -10        - Make every pulse 10 T cycles shorter.
+        BIAS            - No more biasing.
+
+filter_pulses.pl
+----------------
+
+This script may be used to map pulse durations in certain ranges to
+specified values. This is extremely useful for fixing rounding errors caused
+by sampling.
+
+The script maintains the list of ranges and the resulting value to use for
+each range. Each pulse duration is compared with the list and the resulting
+value of the first match is used instead. In case no match is found, the
+duration itself is used as it is.
+
+The ranges are set by use of FILTER keyword in the input stream. The syntax
+is as follows:
+
+FILTER <duration> <range>
+
+Add mapping of durations in range <duration-range,duration+range> to
+given duration to the list of range mappings.
+
+FILTER <duration> <min> <max>
+
+Add mapping of durations in range <min,max> to given duration to the list of
+range mappings.
+
+FILTER
+
+Reset the range list.
+
+Example:
+
+        FILTER 855 600 1300     - Map anything within <600,1300> range to 855 T cycles.
+        FILTER 0 100            - Map everything below 100 T cycles to zero.
+        FILTER                  - No more filtering.
+
+average_pulses.pl
+-----------------
+
+This script may be used to compute the average duration and total count of
+all pulses encountered. This may be useful for data analysis, as well as
+actual data filtering when used in conjunction with script_filter.pl.
+
+The script simply sums durations and counts of all nonzero pulses and
+discards anything else. The result is then printed as 
+
+PULSE <average> <count>
+
+so it can be directly used for further script processing.
+
+sum_pulses.pl
+-------------
+
+This script may be used to compute the total duration of all pulses
+encountered. This may be useful for data analysis, as well as actual data
+filtering when used in conjunction with script_filter.pl.
+
+The script simply sums durations of all pulses and discards anything else.
+The result is then printed as
+
+PULSE <duration>
+
+so it can be directly used for further script processing.
+
+count_pulses.pl
+---------------
+
+This script may be used to create histogram of durations of all pulses
+encountered. This may be useful for data analysis, in particular for
+discovering what pulse ranges are most often used.
+
+The script simply sums counts for each duration encountered and discards
+anything else. The result is then printed as
+
+PULSE <duration> <count>
+
+for each duration encountered, sorted from shortest to longest duration.
+
+script_filter.pl
+----------------
+
+This script may be used to filter parts of the input through other scripts,
+or, in fact, any other programs. It is extremely powerful tool with
+countless possibilities, but as usual with great power comes great
+responsibility - it will happily execute any command it is told to, so make
+sure you know what input you are running it at.
+
+The script will normally just copy any input to the output, line by line.
+However whenever it encounters a SCRIPT keyword specifying some command, it
+will filter any further input via that command, effectively replacing the
+input with the command's output. It will continue doing so until end of file
+or until it encounters another SCRIPT keyword (with or without command).
+
+Examples:
+
+        SCRIPT average_pulses.pl                        - Change duration of following pulses
+                                                          to their average duration.
+        SCRIPT sum_pulses.pl | sed -e 's/PULSE/PAUSE/'  - Turn the following pulses into pause
+                                                          of their total duration.
+        SCRIPT count_pulses.pl                          - Create histogram of only
+                                                          the following pulses.
+        SCRIPT cat info.txt                             - Replace following input
+                                                          with content of file info.txt.
+        SCRIPT                                          - End input of previous command.
+
+History
+=======
+
+1.1 (21.4.2011)
+
++ added annotate_pulses.pl script, and added support for annotated pulses in general.
+
+1.0 (16.6.2007)
+
++ initial release.