nbis-wrapper-js 0.0.1

package/libnbis/nbis_arm64_darwin/man/man1/optosf.1

@@ -0,0 +1,131 @@
+.\" @(#)optosf.1 2008/10/02 NIST
+.\" I Image Group
+.\" G. T. Candela & Craig I. Watson
+.\"
+.TH OPTOSF 1B "02 October 2008" "NIST" "NBIS Reference Manual"
+.SH NAME
+optosf \- optimizes the overall smoothing factor for the PNN classifier.
+.SH SYNOPSIS
+.B optosf
+.I <prsfile>
+.SH DESCRIPTION
+.B Optosf
+optimizes the overall smoothing factor (osf) for the Probabilistic
+Neural Network (PNN) classifier.
+
+The regional weights are optimized using the \fBoptrws\fR command.  To
+save optrws runtime, it is suggested that optrws be run using the K-L
+feature vectors of only a reasonably small set of fingerprints,
+perhaps a small subset of the full prototype set that will be used in
+the finished classifier.  But then, after the full prototype set of
+feature vectors is made by transforming previously made orientation
+arrays using the transform matrix incorporating the optimized regional
+weights, one can expect that the classifier that uses these feature
+vectors will be slightly more accurate if it uses an overall smoothing
+factor slightly larger than 1, to compensate for the fact that the
+prototype set is larger than it was during optimization of the
+regional weights.  During optimization of the regional weights, no
+explicit overall smoothing factor is used, since any effect such a
+factor would have had could equally well be produced by just using
+different values of the regional weights; so, optrws in effect fixes
+the overall smoothing factor at 1.
+
+The optosf command is provided to optimize the overall smoothing factor
+for best results on the full set of prototypes.  It optimizes osf
+by attempting to find a minimum (or at least a local minimum)
+of an activation error rate that results when a set of finished
+feature vectors is classified by PNN.  The set of prototypes
+used by the PNN, during this optimization, is a superset of the
+set on which the activation error rate is computed: both sets
+start at the beginning of the provided data, but they are of different
+lengths.  Whichever fingerprint the classifier is running on is
+temporarily left out of the prototypes set, i.e. a leave-one-out method
+is used in order to simulate a realistic situation.
+
+The optimization method used is a very simple one, consisting of
+taking steps of an initial size, then halving the stepsize and
+reversing direction if the error rates ceases to decrease, etc.  This
+method, while obviously not sufficient for the general problem of
+minimizing a real function of one real variable, appears to be
+sufficient for this particular problem, since the activation error
+rate as a function of the osf seems to always have a unimodal form.
+.SH OPTIONS
+.TP
+.I <prsfile>
+A file specifying values of some or all of the parameters.  Parameters
+not specified in this file assume default values.  To find out what
+the parameters are, and as an example of the format of a parameters
+file, see the file \fIpcasys/parms/optosf.prs\fR in the PARAMETER
+FILES section below.  The user's \fIprsfile\fR must specify values
+for those parameters that \fIoptosf.prs\fR indicates have no defaults;
+it can also specify default-overriding values for one or more of
+the parameters that have defaults.
+.TP
+\fB-version
+\fRPrint ANSI/NIST stardand and NBIS software version.
+
+.SH PARAMETER FILES
+.TP
+.I pcasys/parms/optosf.prs
+Contains default values of the parameters for optosf (optimize overall
+smoothing factor command).  Parameters with no defaults must be set in
+the users \fIprsfile\fR.
+.PP
+.RS
+.B Default settings in \fIpcasys/parms/optosf.prs\fR
+.TP
+.B n_feats_use \fI64\fR
+How many (first) features of the feature vectors to use.
+.TP
+.B osf_init \fI.1\fR
+Initial value for osf (overall smoothing factor).
+.TP
+.B osf_initstep \fI.2\fR
+Initial step size for osf.
+.TP
+.B osf_stepthr \fI.01\fR
+Program stops when step size becomes <= this value.
+.TP
+.B tablesize \fI1000\fR
+Size of the table used to avoid redundant computing.
+.TP
+.B verbose \fIy\fR
+If y, write progress messages to stdout.
+.TP
+.B outfile_desc \fI-\fR
+A \- (hyphen) means let optosf make the description; otherwise,
+value is the description.
+
+.TP
+.B fvs_file \fI(no default, user must set)\fR
+The file containing the prototype feature vectors, each vector
+stored as one row of the matrix.
+.TP
+.B classes_file \fI(no default, user must set)\fR
+The file containing the classes of the prototype feature vectors.
+.TP
+.B n_fvs_use_as_protos_set \fI(no default, user must set)\fR
+The number of first feature vectors from fvs_file to use as the
+PNN prototypes when optimizing osf.
+.TP
+.B n_fvs_use_as_tuning_set \fI(no default, user must set)\fR
+The number of first feature vectors from fvs_file to run the
+PNN on to optimize osf.
+.TP
+.B outfile \fI(no default, user must set)\fR
+The results output file.
+
+.SH EXAMPLE(S)
+From \fItest/pcasys/execs/optosf/optosf.src\fR:
+.PP
+.RS
+.B % optosf optosf.prs
+.br
+Optimize the overall smoothing factor based on the parameters
+set in the file \fIoptosf.prs\fR.
+.SH "SEE ALSO"
+optrws (1B)
+
+
+.SH AUTHOR
+NIST/ITL/DIV894/Image Group

package/libnbis/nbis_arm64_darwin/man/man1/optrws.1

@@ -0,0 +1,213 @@
+.\" @(#)optrws.1 2008/10/02 NIST
+.\" I Image Group
+.\" G. T. Candela & Craig I. Watson
+.\"
+.TH OPTRWS 1B "02 October 2008" "NIST" "NBIS Reference Manual"
+.SH NAME
+optrws \- optimizes the regional weights for PNN classifier.
+.SH SYNOPSIS
+.B optrws
+.I <prsfile>
+.SH DESCRIPTION
+.B Optrws
+optimizes the regional weights, each of which goes with one 2x2-vector
+block of the orientation array.  Since that array has 28 x 30 vectors,
+there are (28 / 2) x (30 / 2) = 210 regional weights.
+
+Optimization consists of attempting to approximate the minimum,
+or at least a local minimum, of an "activation error rate" of the
+Probabilistic Neural Network (PNN) classifier when it is run on a set
+of fingerprints, using the same set as the prototypes for the PNN but
+leaving out of the prototype set, each time, the particular
+fingerprint that the network is being run on.  The program first finds
+a reasonable value to use as an initial value for all 210 weights.
+Then, it uses a very simple form of a gradient descent algorithm to
+finish optimizing the weights.  Each iteration consists of, first,
+estimating the gradient of the error at the current "basepoint", and
+second, approximately finding the minimum (or at least a local
+minimum) of the error along the straight line pointing in the
+anti-estimated-gradient direction.  (Estimating the gradient seems to
+be sufficient, and calculating it from its definition may actually
+require more computation then estimating.)  Because the activation
+error is apparently such a well-behaved function of distance along
+this line, for this particular problem, it seems sufficient to use a
+very simple algorithm for the line search: this consists of taking
+large equal-sized steps in the anti-gradient direction until the error
+ceases to decrease, then halving the stepsize and going in the
+opposite direction along the line until the error again ceases to
+decrease, etc., with the process stopping when the step size becomes
+smaller than a threshold.  This finds a local minimum, and it appears
+that this function generally is unimodal along the line, so that this
+local minimum will be the minimum along the line.
+
+The 0th basepoint is (irw,irw,...,irw), where irw is the initial value
+decided upon for all regional weights.  The 1st basepoint is the
+result of the line search that follows the gradient-estimation at the
+0th basepoint; etc.  Stopping of the program is controlled by
+specifying the number of line searches that are to be done.  If this
+parameter is set to 1, then the program only gets as far as basepoint
+1.  Since optrws records each basepoint, the program can be manually
+stopped if it turns out that it is taking too much time, without the
+run being a total waste of cycles.
+
+At each of the basepoints, optrws produces the following files (in a
+directory specified as one of the parameters).  The basepoint, as a
+"matrix" file of dimensions 14 x 15 (these dimensions correspond to
+the geometric interpretation of the basepoint as a set of regional
+weights); these files have names bspt_0.bin, bspt_1.bin, etc. or
+bspt_0.asc, bspt_1.asc, etc.  The estimated gradient of the activation
+error rate at the basepoint, also as a "matrix" file of dimensions 14
+x 15; these files have names egrad_0.bin, egrad_1.bin, etc. or
+egrad_0.asc, egrad_1.asc, etc.  And, the activation error rate at the
+basepoint, as a text file; these files have names acerr_0.txt,
+acerr_1.txt, etc.  As optrws is running (which make take several
+hours), these intermediate results files may be examined to find out
+what kind of progress the optimization is making.  The acerr files
+obviously can be examined to find out if the reported error rate is
+still decreasing or has leveled off. Also, the rwpics command (see
+rwpics man page) can be used to make, from a set of bspt files, a set
+of grayscale IHead images depicting these regional weights sets in
+their proper geometric layout.  Rwpics can also make two other
+kinds of pictures: grayscale pictures of a set of estimated
+gradients (egrad files), and grayscale-binary (i.e. 0 and 255 pixels)
+pictures showing the signs of the elements of estimated gradients.
+(The blocks whose estimated gradient elements, i.e. estimated
+partials, are negative, are ones whose weights will be increasing as
+optrws takes steps in the anti-estimated-gradient direction.)  For the
+"optimal" set of regional weights, just use the final bspt file
+produced before the optrws run stops by itself (because of doing the
+specified number of iterations) or, if optimization appears not to be
+making much more progress, kill the optrws process and use the last
+bspt file produced.  Or, it could also be interesting to do testing
+using various basepoints, to find out whether the decreases in the
+activation error during optimization correspond to error decreases on
+a test set, i.e. to find out whether even small improvements in the
+weights in the sense of training error rate, are actually significant
+in the sense of generalizing to other data.  (The weights seem to
+generalize well, not too suprisingly since there are only 210 of them,
+hardly a large enough number for them to be capable of becoming very
+specifically tuned to the training data in such a way as to have
+little generalization value.)
+
+The parameters of optrws are specified by parameter files.  The
+program first reads \fIpcasys/parms/optrws.prs\fR, which contains
+default values of some of its parameters; then it reads the
+user-provided parameters file whose name is given as the argument.
+Consult optrws.prs to find out what the parameters are, and as an
+example of the format of a parameters file.  Optrws.prs specifies
+default values for the parameters that have defaults, and it also has
+a comment concerning each parameter that has no default value.  The
+user parameters file must specify a value for each parameter that does
+not have a default, and it also can specify default-overriding values
+for one or more of the other parameters.
+
+Optrws can start several simultaneous instances of another program,
+optrwsgw, each time it needs to estimate the gradient, if desired.
+This can reduce the time needed for optimization, if there are several
+processors available.  To use this feature, set
+acerror_stepped_points_nprocs in your parameters file to a value > 1
+(probably should be <= number of processors available).  If the
+operating system on your computer does not implement fork() and
+execl(), then the Makefile for optrws should be modified by appending
+-DNO_FORK_AND_EXECL to the definition of CFLAGS, so that a different
+subset of the code will be compiled and the linker will thereby find
+no unresolved references.
+.SH OPTIONS
+.TP
+.I <prsfile>
+A file specifying values of some or all of the parameters.  Parameters
+not specified in this file assume default values.
+.TP
+\fB-version
+\fRPrint ANSI/NIST stardand and NBIS software version.
+
+.SH PARAMETER FILES
+.TP
+.I pcasys/parms/optrws.prs
+Contains default values for some of the optrws parameters.
+The remaining parameters, with no default values
+must be specified in the user \fIprsfile\fR.
+.PP
+.RS
+.B Default settings in \fIpcasys/parms/optrws.prs\fR
+.TP
+.B n_feats_use \fI64\fR
+How many (first) features of each K-L feature vector to use.
+
+.TP
+.B irw_init \fI0.1\fR
+Initial value for irw.
+.TP
+.B irw_initstep \fI1.0\fR
+Initial step size for irw.
+.TP
+.B irw_stepthr \fI.01\fR
+Optimization of irw stops when step size becomes smaller than
+this threshold.
+
+.TP
+.B grad_est_stepsize \fI.001\fR
+Step size for secant-estimation of gradient.
+.TP
+.B n_linesearches \fI2\fR
+Number of (estimate gradient, line search) iterations to do.
+.TP
+.B linesearch_initstep \fI.1\fR
+Initial step size for line search.
+.TP
+.B linesearch_stepthr \fI.01\fR
+Line search stops when its step size becomes smaller than this threshold.
+.TP
+.B tablesize \fI1000\fR
+Size of a table used to hold pairs of values corresponding to previous
+computations of the error, either as a function of irw or as a function
+of distance along downhill-pointing line.  Lookup in this table saves
+some cycles by avoiding repeated calculations.
+.TP
+.B acerror_stepped_points_nprocs \fI1\fR
+How many processes to use when computing the activation error at the
+points stepped to from a basepoint, in order to compute the
+approximate gradient by secant method.  If 1, optrws computes the
+error at all stepped points itself.  If > 1, optrws starts this many
+child processes, each of which computes the error at an interval
+of the stepped points.
+.TP
+.B verbose \fIy\fR
+If y, write progress messages to standard output.
+.TP
+.B ascii_outfiles \fIn\fR
+Whether outputfiles are to be ascii (y) or binary (n).
+
+.TP
+.B klfvs_file \fI(no default, user must set)\fR
+File containing K-L feature vectors to be used as prototypes set,
+and also as "tuning" set, for the optimization. Usually the output
+on the lintran function.
+.TP
+.B classes_file \fI(no default, user must set)\fR
+File containing the classes that go with the feature vectors of
+\fIklfvs_file\fR.  Must be a pcasys "classes" formatted file.
+.TP
+.B n_klfvs_use \fI(no default, user must set)\fR
+How many of the K-L feature vectors to use (off the top).
+.TP
+.B eigvecs_file \fI(no default, user must set)\fR
+File containing the eigenvectors.
+.TP
+.B outfiles_dir \fI(no default, user must set)\fR
+The directory in which optrws is to produce its output files.
+
+.SH EXAMPLE(S)
+From \fItest/pcasys/execs/optrws/optrws.src\fR:
+.PP
+.RS
+.B % optrws optrws.prs
+.br
+Optimizes the regional weights for a set of feature vectors based
+on the parameters set in the file \fIoptrws.prs\fR.
+.SH "SEE ALSO"
+rwpics (1B)
+
+
+.SH AUTHOR
+NIST/ITL/DIV894/Image Group

package/libnbis/nbis_arm64_darwin/man/man1/pcasys.1

@@ -0,0 +1,244 @@
+.\" @(#)pcasys.1 2008/10/02 NIST
+.\" I Image Group
+.\" G. T. Candela & Craig I. Watson
+.\"
+.TH PCASYS 1B "02 October 2008" "NIST" "NBIS Reference Manual"
+.SH NAME
+pcasys \- fingerprint classifier demo, non-graphical version
+.SH SYNOPSIS
+.B pcasys
+.I [prsfile]
+.SH DESCRIPTION
+.B Pcasys
+is the non-graphical fingerprint classifier demo program.  It reads a
+sequence of image files, each depicting one box as scanned from a
+fingerprint card, and classifies each fingerprint, using a Multi-Layer
+Perceptron (MLP) or Probabilistic (PNN) Neural Network, to one of six
+pattern\-level classes: Arch, Left loop, Right loop, Scar, Tented
+arch, and Whorl. The type of classifier MLP or PNN is chosen in the
+parameters file \fIpcasys/parms/pcasys.prs\fR.
+Pcasys optionally makes an output file, containing a results line
+for each fingerprint and a summary at the end showing the error rate 
+and the "confusion matrix", and it optionally writes progress messages
+to the standard output.
+
+The graphical version, pcasysx, is recommended as being much more
+interesting than this version.  However, pcasys is suitable if (1)
+the X Window System, which pcasysx requires, is not installed, or (2)
+greatest classification speed is desired.  (The graphical displays take
+a significant amount of additional time.)
+
+Pcasys will look in the default location \fIpcasys/parms\fR
+for the default parameter files it needs.  There are prototype
+and weights files in \fIpcasys/weights/{mlp|pnn}\fR that are needed
+by the MLP and PNN classifiers. Also, the current default location
+location for the 2700 sample fingerprint images is 
+\fI/NBIS//Test/pcasys/data/images\fR. 
+.SH OPTIONS
+.TP
+.I [prsfile]
+A file containing one or more parameter values that are to override
+the default values.  To find out what the parameters are, and as
+examples of the format of a parameters file, consult the default
+parameters files that pcasys reads, namely \fIpcasys/parms/oas.prs\fR
+and \fIpcasys/parms/pcasys.prs\fR which are described in the section
+PARAMETER FILES. Each line, in the parms file
+consists of a parameter name followed by a value; a pound sign
+indicates that the rest of its line is a comment.  If pcasys is run
+with no argument, i.e. not specifying a user parameters file, then it
+uses the default values of all parameters.
+.TP
+\fB-version
+\fRPrint ANSI/NIST stardand and NBIS software version.
+
+.SH PARAMETER FILES
+.TP
+.I pcasys/parms/oas.prs
+Contains default values of the parameters that affect the making of
+orientation arrays (oas): these are the parms of the segmentor
+(sgmnt), the image enhancer (enhnc), the ridge-valley orientation
+finder (rors), the registration program (r92a), and the
+registration-implementing pixelwise orientations reaverager (rgar).
+The values used for these parms when making the oas used in
+optimizing the classifier should also be used when running the
+finished classifier.
+\fBSee the \fImkoas\fB man page for more information about the parameters
+in this file.\fR
+.TP
+.I pcasys/parms/pcasys.prs
+Contains default values of the remaining parameters of pcasys.
+Also look at \fIpcasys.mlp\fR and \fIpcasys.pnn\fR for examples on
+using each classifier.
+.PP
+.RS
+.B Default settings in \fIpcasys/parms/pcasys.prs\fR
+.TP
+.B network_type \fI2\fR
+Set classifier as (1) PNN (Probabilistic Neural Net) or
+(2) MLP (Multi-layer Perceptron).
+.TP
+.B trnsfrm_nrows_use \fI128\fR
+How many (first) rows of the transform matrix to use, and hence, how
+many features to make for the feature vector of each incoming fingerprint,
+and also how many (first) features to use of each prototype feature
+vector when running the classifier:
+
+.TP
+.B trnsfrm_matrix_file \fIpcasys/weights/mlp/mlp_tmat.bin\fR
+File used by the demo to transform the orientation array of an
+incoming fingerprint into the low-dimensional feature vector that
+will be sent to the classifier.
+
+.TP
+.B cls_str \fIALRSTW\fR
+Class string used in graphics mode to display the
+ouput activations.  Should be same size as number of outputs
+(ie. pnn_nclasses or number outputs in mlp_wts file).  Must be
+some combination of "ALRSTW".  For PNN, these must be the same
+classes as used in the prototype files and be in the same order 
+as when the prototype were optimized.
+
+.PP
+\fIpnn (Probabilistic Neural Net) parameters:\fR
+.TP
+.B pnn_nprotos_use \fI24300\fR
+How many first feature vectors to use, from the set of prototypes.
+The value 24300 corresponds to the entire provided set, corresponding
+to volumes 1 - 9 "f" rollings of Special Database 14.
+.TP
+.B pnn_nclasses \fI6\fR
+How many different classes there are.  For the fingerprint
+pattern-level classification problem, there are 6: A, L, R, S, T, and W.
+.TP
+.B pnn_osf \fI1.368750\fR
+Overall smoothing factor for the PNN.  May be optimized using optosf.
+
+.TP
+.B pnn_protos_fvs_file \fIpcasys/weights/pnn/profvs.bin\fR
+Prototype feature vectors file.
+.TP
+.B pnn_protos_classes_file \fIpcasys/weights/pnn/procls.asc\fR
+Prototype classes file.
+
+.PP
+\fIMLP (Multi-layer Perceptron) network parameters:\fR
+.TP
+.B mlp_wts_file \fIpcasys/weights/mlp/mlp_wts.bin\fR
+MLP weights file.
+
+.PP
+\fIParameters used by the pseudoridge tracer:\fR
+.TP
+.B pseudo_slthresh0 \fI0.0\fR
+If squared-length of an orientation vector (in the fine grid used
+by pseudo) is < this value, then the vector is zeroed before the
+(possible) application of smoothing iterations.
+.TP
+.B pseudo_slthresh1 \fI0.04\fR
+If, after (possible) smoothing iterations, the squared-length of
+an orientation vector is < this value, then this location is marked
+as bad, meaning that no pseudoridge is allowed to start here and
+if one arrives here, tracing stops at this point.
+.TP
+.B pseudo_smooth_cwt \fI0.0\fR
+Center-weight for each iteration of smoothing of the orientation grid.
+An iteration consists of replacing each vector with the weighted
+average of itself and its four neighbors, with itself getting this
+much weight and its neighbors equally dividing the remaining weight
+(sum of weights is 1).
+.TP
+.B pseudo_stepsize \fI1.0\fR
+Length of one step in the production of a pseudoridge, which is actually
+a polygon.  A value of 1. corresponds to the spacing between vectors
+in the (finer) orientation array used by pseudo.
+.TP
+.B pseudo_max_tilt \fI45\fR
+Max allowed tilt of a candidate concave-upward's vertex (point of
+sharpest turning) from a horizontal that corresponds to exact
+uprightness.  In degrees.
+.TP
+.B pseudo_min_side_turn \fI70\fR
+Minimum cumulative turn that each side of concave-upward must have.
+In degrees.
+
+.PP
+\fILimits for the block of starting positions in
+pseudoridge tracing:\fR
+.TP
+.B pseudo_initi_s \fI11\fR
+Small limit, vertical. (TOP)
+.TP
+.B pseudo_initi_e \fI46\fR
+Large limit, vertical. (BOTTOM)
+.TP
+.B pseudo_initj_s \fI11\fR
+Small limit, horizontal. (LEFT)
+.TP
+.B pseudo_initj_e \fI50\fR
+Large limit, horizontal. (RIGHT)
+.TP
+.B pseudo_maxsteps_eachdir \fI200\fR
+Maximum number of steps that tracer ever takes in either of the two
+directions from starting point.  (Controls the amount of memory
+needed to store a pseudoridge, and more importantly, such a limit
+is needed to prevent possible infinitely looping pseudridges in
+some whorls.)
+.TP
+.B pseudo_nsmooth \fI3\fR
+How many iterations of smoothing.
+.TP
+.B pseudo_maxturn \fI40\fR
+Maximum turn that is allowed to occur in a single step (in degrees).
+An attempted turn sharper than this causes tracing to stop.
+
+.PP
+\fIUsed by the combine routine.\fR
+.TP
+.B combine_clash_confidence \fI.9\fR
+This is the confidence value combine assigns if pseudo
+finds a concave-upward (causing hyp class to be whorl) but PNN
+thinks the print is not a whorl:
+
+.PP
+\fIPCASYS I/O parameters.\fR
+.TP
+.B demo_images_list \fIpcasys/parms/first20.txt\fR
+List of fingerprint images to run the demo on.  The default list
+here lists the first 20 fingerprints of the provided demo set, which
+consists of the 2700 fingerprints of volume 10 "s" rollings of
+NIST Special Database 14. \fIpcasys/parms/all.txt\fR list all
+2700 files.
+
+.TP
+.B outfile \fIpcasys.out\fR
+Output file to be produced.  If no output file is wanted, set
+this to /dev/null.
+
+.TP
+.B clobber_outfile \fIn\fR
+If n, then if outfile already exists, exit with an error message.
+If y, then overwrite outfile if it already exists.
+
+.TP
+.B verbose \fIy\fR
+If y, then write progress messages to stdout.
+
+.SH EXAMPLE(S)
+From \fItest/pcasys/execs/pcasys/pcasys.src\fR:
+.PP
+.RS
+.B % pcasys
+.br
+Runs the pcasys demo using the default settings found in
+\fI pcasys/parms/pcasys.prs\fR.
+.PP
+.B % pcasys myprsfile
+.br
+Runs the pcasys demo using parameters set in \fImyprsfile\fR
+to change the value of the default settings.
+.SH "SEE ALSO"
+pcasysx (1B)
+
+
+.SH AUTHOR
+NIST/ITL/DIV894/Image Group