INTERFACE PZSymbolChain;

(* Discretized curvature graphs *)
(* Last edited on 1999-11-15 00:03:31 by hcgl *)

IMPORT Rd, Wr;
IMPORT PZSymbol, PZSegment, PZMatch;
FROM PZTypes IMPORT LONG, LONGS, NAT, BOOL, BOOLS;

TYPE
  Symbol = PZSymbol.T;

  T = ARRAY OF Symbol;
    (*
      A "PZSymbolChain.T" is a sequence,open or closed, of curvature samples
      that have been quantized and represented as "PZSymbol.T" values. *)

(* BASIC MANIPULATION *)

(*
  The "DoXXX" procedures below are analogous to the "XXX" 
  procedures, except that the result is returned in an array
  provided by the client (which must have the correct size). *)

PROCEDURE Trim(READONLY c: T; start, length: NAT): REF T;
PROCEDURE DoTrim(READONLY c: T; start, length: NAT; VAR x: T);
  (*
    Returns a new chain that is a copy of elements from "c[start]"
    to "c[start+length-1]".  Assumes the chain is periodic, i.e.
    "c[i+n]=c[i]" for all "i", where "n=NUMBER(c)".  *)
  
PROCEDURE ReverseAndComplement(VAR c: T);
  (*
    Reverses the chain back-to-front and negates all elements. *)

PROCEDURE ExtractSegment(READONLY c: T; s: PZSegment.T): REF T;
PROCEDURE DoExtractSegment(READONLY c: T; s: PZSegment.T; VAR x: T);
  (* 
    Extracts the given segment from the curvature
    graph "c", assumed to be closed. If "s.rev" is TRUE, also reverses
    and complements it. *)

(* CHAIN MATCHING BY DYNAMIC PROGRAMMING *)
    
(*
  The procedures "FindBestMatch" and "RefineMatch" look for a 
  monotone matching "mt" (a "PZMatch.T") between two chains that 
  minimizes some measure of the distance between corresponding samples.
  They are entirely analogous to "PZLRChain.FindBestMatch"
  and "PZLRChain.RefineMatch", except that the sample distance "d(a[r], b[s])
  = |a[r]-b[s]|" is computed on the decoded sample values. *)

PROCEDURE FindBestMatch(
    READONLY a: T;
    READONLY b: T;
    READONLY decode: ARRAY PZSymbol.T OF LONG;
    READONLY errorVar: ARRAY PZSymbol.T OF LONG;
    step: LONG;
    maxDistSqr: LONG;
    skipDistSqr: LONG;
    removeUnmatchedEnds: BOOL;
    VAR (*OUT*) mt: REF PZMatch.T;
    VAR (*OUT*) avgDisc: LONG;
    VAR (*OUT*) length: LONG;
    VAR (*OUT*) matchedLength: LONG; 
    VAR (*WORK*) rCost: REF PZMatch.CostMatrix;
  ); 

PROCEDURE RefineMatch(
    READONLY a: T;
    READONLY b: T;
    READONLY decode: ARRAY PZSymbol.T OF LONG;
    READONLY errorVar: ARRAY PZSymbol.T OF LONG;
    step: LONG;
    READONLY mtOld: PZMatch.T;
    maxAdjust: NAT;
    critDistSqr: LONG;
    maxDistSqr: LONG;
    skipDistSqr: LONG;
    VAR (*OUT*) mt: REF PZMatch.T;
    VAR (*OUT*) mismatch: LONG;
    VAR (*OUT*) length: LONG;
    VAR (*OUT*) matchedLength: LONG; 
    VAR (*OUT*) minAvgDisc: LONGS;
    VAR (*WORK*) rCost: REF PZMatch.CostMatrix;
  ); 
  
(* INPUT/OUTPUT *)

PROCEDURE PrintSegment(wr: Wr.T; READONLY c: T; s: PZSegment.T);
  (*
    Prints to "wr" the segment "s" of the chain "c",
    reversed and complementd if "s.rev" is TRUE. *)

PROCEDURE Write(
    wr :Wr.T; 
    cmt: TEXT;
    READONLY c: T;
    sigma: LONG;
  );
  (*
    Writes to "wr" a coded curvature chain "c", recording also the
    encoding parameter "sigma". *)
    
TYPE
  ReadData = RECORD
      cmt: TEXT;     (* Comments *)
      samples: NAT;  (* Number of samples in chain. *)
      sigma: LONG;   (* Encoding parameter. *)
      c: REF T;      (* Encoded curvature values. *)
    END;
    
PROCEDURE Read(rd :Rd.T; headerOnly: BOOL): ReadData;
  (*
    Reads a coded curvature chain and associated encoding 
    parameters from "rd".  If "headerOnly=TRUE", reads only the
    parameters, and leaves the "c" field as NIL. *)
    
PROCEDURE ReadOld(rd :Rd.T; sigma: LONG): ReadData;
  (*
    Reads from "rd" an old-format coded curvature chain,
    which was encoded with "PZProc.OldSqueeze(epsilon, delta)",
    decodes it, and reencodes it with "PZSymbol.Encode(x,sigma)". *)
    
TYPE
  ReadAllData = RECORD
      chain: REF ARRAY OF ReadData;
      sigmaMin: LONG;  (* Minimum "sigma" value. *)
      sigmaMax: LONG;  (* Maximum "sigma" value. *)
      cmt: TEXT;       (* Comment of first chain, if any. *)
    END;

PROCEDURE ReadAll(
    prefix: TEXT; 
    band: NAT;
    extension: TEXT;
    READONLY sel: BOOLS;
    headerOnly: BOOL;
    dir: TEXT := ".";
  ): ReadAllData;
  (*
    Reads a set of numbered chains, returns a "ReadAllData" record
    "r". Chain number "i" is read if and only if "sel[i] = TRUE", and
    its "ReadData" is stored in "r.chain[i]". If "sel[i] = FALSE",
    or the file is not found, "r.chain[i] " is set to a record with null
    "c" field. 
    
    If "headerOnly" is TRUE, only the header of each file is read;
    the "c" fields are all set to NIL.
    
    The data is read from file "DDD/KKKK/PPPBBBEEE", where "DDD" is
    the directory "dir", "KKKK" is the
    curve number "k" (4 digits, zero padded), "PPP" is the prefix,
    "BBB" is the "band" number (3 digits, zero padded), and "eee"
    is the given "extension".
    
    The range of "sigma" parameters of the chains that were read is
    returned in "r.sigmaMin", "r.sigmaMax". The comment of the first chain
    read, plus the call arguments, are stored in "r.cmt". *)

END PZSymbolChain.
(*
  Copyright © 2001 Universidade Estadual de Campinas (UNICAMP).
  Authors: Helena C. G. Leitão and Jorge Stolfi.
  
  This file can be freely distributed, used, and modified, provided
  that this copyright and authorship notice is preserved, and that any
  modified versions are clearly marked as such.
  
  This software has NO WARRANTY of correctness or applicability for
  any purpose. Neither the authors nor their employers chall be held
  responsible for any losses or damages that may result from its use.
*)