/* * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @file picokdt.h * * knowledge handling for decision trees * * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland * All rights reserved. * * History: * - 2009-04-20 -- initial version * */ #ifndef PICOKDT_H_ #define PICOKDT_H_ #include "picoos.h" #include "picoknow.h" #ifdef __cplusplus extern "C" { #endif #if 0 } #endif /* ************************************************************/ /* Several specialized decision trees kb are provided by this knowledge handling module: - Part of speech prediction decision tree: ...kdt_PosP - Part of speech disambiguation decision tree: ...kdt_PosD - Grapheme-to-phoneme decision tree: ...kdt_G2P - Phrasing decision tree: ...kdt_PHR - Accentuation decision tree: ...kdt_ACC these 5 tree types may be unified in the future to a single type - Phono-acoustical model trees: ...kdt_PAM (actually 11 trees, but all have the same characteristics and are instances of the same class) */ /* ************************************************************/ /* ************************************************************/ /* defines and functions to create specialized kb, */ /* to be used by picorsrc only */ /* ************************************************************/ typedef enum { PICOKDT_KDTTYPE_POSP, PICOKDT_KDTTYPE_POSD, PICOKDT_KDTTYPE_G2P, PICOKDT_KDTTYPE_PHR, PICOKDT_KDTTYPE_ACC, PICOKDT_KDTTYPE_PAM } picokdt_kdttype_t; pico_status_t picokdt_specializeDtKnowledgeBase(picoknow_KnowledgeBase this, picoos_Common common, const picokdt_kdttype_t type); /* ************************************************************/ /* decision tree types (opaque) and get Tree functions */ /* ************************************************************/ /* decision tree types */ typedef struct picokdt_dtposp * picokdt_DtPosP; typedef struct picokdt_dtposd * picokdt_DtPosD; typedef struct picokdt_dtg2p * picokdt_DtG2P; typedef struct picokdt_dtphr * picokdt_DtPHR; typedef struct picokdt_dtacc * picokdt_DtACC; typedef struct picokdt_dtpam * picokdt_DtPAM; /* return kb decision tree for usage in PU */ picokdt_DtPosP picokdt_getDtPosP(picoknow_KnowledgeBase this); picokdt_DtPosD picokdt_getDtPosD(picoknow_KnowledgeBase this); picokdt_DtG2P picokdt_getDtG2P (picoknow_KnowledgeBase this); picokdt_DtPHR picokdt_getDtPHR (picoknow_KnowledgeBase this); picokdt_DtACC picokdt_getDtACC (picoknow_KnowledgeBase this); picokdt_DtPAM picokdt_getDtPAM (picoknow_KnowledgeBase this); /* number of attributes (= input vector size) for each tree type */ typedef enum { PICOKDT_NRATT_POSP = 12, PICOKDT_NRATT_POSD = 7, PICOKDT_NRATT_G2P = 16, PICOKDT_NRATT_PHR = 8, PICOKDT_NRATT_ACC = 13, PICOKDT_NRATT_PAM = 60 } kdt_nratt_t; /* ************************************************************/ /* decision tree classification result type */ /* ************************************************************/ typedef struct { picoos_uint8 set; /* TRUE if class set, FALSE otherwise */ picoos_uint16 class; } picokdt_classify_result_t; /* maximum number of output values the tree output is mapped to */ #define PICOKDT_MAXSIZE_OUTVEC 8 typedef struct { picoos_uint8 nr; /* 0 if no class set, nr of values set otherwise */ picoos_uint16 classvec[PICOKDT_MAXSIZE_OUTVEC]; } picokdt_classify_vecresult_t; /* ************************************************************/ /* decision tree functions */ /* ************************************************************/ /* constructInVec: for every tree type there is a constructInVec function to construct the size-optimized input vector for the tree using the input map tables that are part of the decistion tree knowledge base. The constructed input vector is stored in the tree object (this->invec and this->inveclen) and will be used in the following call to the classify function. classify: for every tree type there is a classify function to apply the decision tree to the previously constructed input vector. The size-optimized, encoded output is stored in the tree object (this->outval) and will be used in the following call to the decompose function. Where needed (hitory attribute) the direct tree output is returned by the classify function in a variable. decomposeOutClass: for every tree type there is a decompose function to decompose the size-optimized, encoded tree output and map it to the outside the tree usable class value. */ /* ************************************************************/ /* decision tree defines */ /* ************************************************************/ /* to construct the input vectors several hard-coded values are used to handle attributes that, at the given position, are outside the context. */ /* graph attributes: values to be used if the graph attribute is outside the grapheme string (ie. word) */ #define PICOKDT_OUTSIDEGRAPH_DEFCH (picoos_uint8)'\x30' /* ascii "0" */ #define PICOKDT_OUTSIDEGRAPH_DEFSTR (picoos_uint8 *)"\x30" /* ascii "0" */ #define PICOKDT_OUTSIDEGRAPH_DEFLEN 1 /* graph attributes (special case for g2p): values to be used if the graph attribute is directly outside the grapheme string (ie. at the word boundary word). Use PICOKDT_OUTSIDEGRAPH_DEF* if further outside. */ #define PICOKDT_OUTSIDEGRAPH_EOW_DEFCH (picoos_uint8)'\x31' /* ascii "1" */ #define PICOKDT_OUTSIDEGRAPH_EOW_DEFSTR (picoos_uint8 *)"\x31" /* ascii "1" */ #define PICOKDT_OUTSIDEGRAPH_EOW_DEFLEN 1 /* byte and word type attributes: value to be used if a byte or word attribute is outside the context, e.g. for POS */ #define PICOKDT_EPSILON 7 /* byte and word type attributes: for attribute with history info a 'zero' value is needed when starting the sequence of predictions. Use the following value to initialize history. Note that the direct tree outputs (not mapped with output map table) of previous predictions need to be used when constructing the input vector for a following prediction. This direct tree output will then be mapped together with the rest of the input vector by the input map table. */ #define PICOKDT_HISTORY_ZERO 30000 /* ************************************************************/ /* decision tree POS prediction (PosP) functions */ /* ************************************************************/ /* construct a POS prediction input vector tree input vector: 0-3 prefix UTF8 graphemes 4-9 suffex UTF8 graphemes 10 special grapheme existence flag (TRUE/FALSE) 11 number of graphemes graph: the grapheme string of the word for wich POS will be predicted graphlen: length of graph in number of bytes specgraphflag: existence of a special grapheme boolean returns: TRUE if okay, FALSE otherwise note: use PICOKDT_OUTSIDEGRAPH* for att values outside context */ picoos_uint8 picokdt_dtPosPconstructInVec(const picokdt_DtPosP this, const picoos_uint8 *graph, const picoos_uint16 graphlen, const picoos_uint8 specgraphflag); /* classify a previously constructed input vector using tree 'this' returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPosPclassify(const picokdt_DtPosP this); /* decompose the tree output and return the class in dtres dtres: POS or POSgroup ID classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPosPdecomposeOutClass(const picokdt_DtPosP this, picokdt_classify_result_t *dtres); /* ************************************************************/ /* decision tree POS disambiguation (PosD) functions */ /* ************************************************************/ /* construct a POS disambiguation input vector (run in left-to-right mode) tree input vector: 0-2 POS or POSgroup for each of the three previous words 3 POSgroup for current word 4-6 POS or POSgroup (can be history) for each of the three following words pre3 - pre1: POSgroup or POS for the previous three words src: POSgroup of current word (if unique POS no posdisa possible) fol1 - fol3: POS or history for the following three words (the more complicated the better... :-( NEEDS TO BE uint16 ishist1-ishist3: flag to indicate if fol1-3 are predicted tree output values (history) or the HISTORY_ZERO (TRUE) or an already unambiguous POS (FALSE) returns: TRUE if okay, FALSE otherwise note: use PICOKDT_EPSILON for att values outside context, if POS in fol* unique use this POS instead of real history, use reverse output mapping in these cases */ picoos_uint8 picokdt_dtPosDconstructInVec(const picokdt_DtPosD this, const picoos_uint16 * input); /* classify a previously constructed input vector using tree 'this' treeout: direct tree output value returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPosDclassify(const picokdt_DtPosD this, picoos_uint16 *treeout); /* decompose the tree output and return the class in dtres dtres: POS classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPosDdecomposeOutClass(const picokdt_DtPosD this, picokdt_classify_result_t *dtres); /* convert (unique) POS index into corresponding tree output index */ picoos_uint8 picokdt_dtPosDreverseMapOutFixed(const picokdt_DtPosD this, const picoos_uint16 inval, picoos_uint16 *outval, picoos_uint16 *outfallbackval); /* ************************************************************/ /* decision tree grapheme-to-phoneme (G2P) functions */ /* ************************************************************/ /* construct a G2P input vector (run in right-to-left mode) tree input vector: 0-8 the 4 previous, current, and 4 following graphemes 9 POS 10-11 vowel count and vowel ID 12 primary stress flag (TRUE/FALSE) 13-15 the three following phones predicted graph: the grapheme string used to determine invec[0:8] graphlen: length of graph in number of bytes count: the grapheme number for which invec will be constructed [0..] pos: the part of speech of the word nrvow number of vowel-like graphemes in graph if vowel, set to 0 otherwise ordvow order of 'count' vowel in graph if vowel, set to 0 otherwise primstressflag: flag indicating if primary stress was already predicted phonech1-3: the three following phon chunks predicted (right-to-left) returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtG2PconstructInVec(const picokdt_DtG2P this, const picoos_uint8 *graph, const picoos_uint16 graphlen, const picoos_uint8 count, const picoos_uint8 pos, const picoos_uint8 nrvow, const picoos_uint8 ordvow, picoos_uint8 *primstressflag, const picoos_uint16 phonech1, const picoos_uint16 phonech2, const picoos_uint16 phonech3); /* classify a previously constructed input vector using tree 'this' treeout: direct tree output value returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtG2Pclassify(const picokdt_DtG2P this, picoos_uint16 *treeout); /* decompose the tree output and return the class vector in dtvres dtvres: phones vector classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtG2PdecomposeOutClass(const picokdt_DtG2P this, picokdt_classify_vecresult_t *dtvres); /* ************************************************************/ /* decision tree phrasing (PHR) functions */ /* ************************************************************/ /* construct a PHR input vector (run in right-to-left mode) tree input vector: 0-1 POS for each of the two previous words 2 POS for current word 3-4 POS for each of the two following words 5 nr words left 6 nr words right 7 nr syllables right pre2 - pre1: POS for the previous two words src: POS of current word fol1 - fol2: POS for the following two words nrwordspre: number of words left (previous) of current word nrwordsfol: number of words right (following) of current word, incl. current word, up to next BOUND (also considering previously predicted PHR2/3) nrsyllsfol: number of syllables right (following) of current word, incl. syllables of current word, up to next BOUND (also considering previously predicted PHR2/3) returns: TRUE if okay, FALSE otherwise note: use PICOKDT_EPSILON for att values outside context */ picoos_uint8 picokdt_dtPHRconstructInVec(const picokdt_DtPHR this, const picoos_uint8 pre2, const picoos_uint8 pre1, const picoos_uint8 src, const picoos_uint8 fol1, const picoos_uint8 fol2, const picoos_uint16 nrwordspre, const picoos_uint16 nrwordsfol, const picoos_uint16 nrsyllsfol); /* classify a previously constructed input vector using tree 'this' returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPHRclassify(const picokdt_DtPHR this); /* decompose the tree output and return the class vector in dtres dtres: phrasing classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPHRdecomposeOutClass(const picokdt_DtPHR this, picokdt_classify_result_t *dtres); /* ************************************************************/ /* decision tree accentuation (ACC) functions */ /* ************************************************************/ /* construct an ACC input vector (run in right-to-left mode) tree input vector: 0-1 POS for each of the two previous words 2 POS for current word 3-4 POS for each of the two following words 5-6 history values (already predicted following) 7 nr words left (previous) to any bound 8 nr syllables left to any bound 9 nr words right (following) to any bound 10 nr syllables right to any bound 11 nr words right to predicted "1" prominence (foot) 12 nr syllables right to predicted "1" prominence (foot) pre2 - pre1: POS for the previous two words src: POS of current word fol1 - fol2: POS for the following two words hist1 - hist2: previously predicted ACC values nrwordspre: number of words left (previous) of current word nrsyllspre: number of syllables left (previous) of current word, incl. initial non-prim stress syllables of current word nrwordsfol: number of words right (following) of current word, incl. current word, up to next BOUND (any strength != 0) nrsyllsfol: number of syllables right (following) of current word, incl. syllables of current word starting with prim. stress syllable footwordsfol: nr of words to the following prominence '1' footsyllspre: nr of syllables to the previous prominence '1' returns: TRUE if okay, FALSE otherwise note: use PICOKDT_EPSILON for att 0-4 values outside context */ picoos_uint8 picokdt_dtACCconstructInVec(const picokdt_DtACC this, const picoos_uint8 pre2, const picoos_uint8 pre1, const picoos_uint8 src, const picoos_uint8 fol1, const picoos_uint8 fol2, const picoos_uint16 hist1, const picoos_uint16 hist2, const picoos_uint16 nrwordspre, const picoos_uint16 nrsyllspre, const picoos_uint16 nrwordsfol, const picoos_uint16 nrsyllsfol, const picoos_uint16 footwordsfol, const picoos_uint16 footsyllsfol); /* classify a previously constructed input vector using tree 'this' treeout: direct tree output value returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtACCclassify(const picokdt_DtACC this, picoos_uint16 *treeout); /* decompose the tree output and return the class vector in dtres dtres: phrasing classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtACCdecomposeOutClass(const picokdt_DtACC this, picokdt_classify_result_t *dtres); /* ************************************************************/ /* decision tree phono-acoustical model (PAM) functions */ /* ************************************************************/ /* construct a Pam input vector and store the tree-specific encoded input vector in the tree object. vec: tree input vector, 60 single-byte-sized attributes veclen: length of vec in number of bytes returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPAMconstructInVec(const picokdt_DtPAM this, const picoos_uint8 *vec, const picoos_uint8 veclen); /* classify a previously constructed input vector using tree 'this' returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPAMclassify(const picokdt_DtPAM this); /* decompose the tree output and return the class in dtres dtres: phones vector classification result returns: TRUE if okay, FALSE otherwise */ picoos_uint8 picokdt_dtPAMdecomposeOutClass(const picokdt_DtPAM this, picokdt_classify_result_t *dtres); #ifdef __cplusplus } #endif #endif /*PICOKDT_H_*/