1 /* 2 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 /** 17 * @file picokdt.h 18 * 19 * knowledge handling for decision trees 20 * 21 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland 22 * All rights reserved. 23 * 24 * History: 25 * - 2009-04-20 -- initial version 26 * 27 */ 28 29 #ifndef PICOKDT_H_ 30 #define PICOKDT_H_ 31 32 #include "picoos.h" 33 #include "picoknow.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 #if 0 39 } 40 #endif 41 42 43 /* ************************************************************/ 44 /* 45 Several specialized decision trees kb are provided by this 46 knowledge handling module: 47 48 - Part of speech prediction decision tree: ...kdt_PosP 49 - Part of speech disambiguation decision tree: ...kdt_PosD 50 - Grapheme-to-phoneme decision tree: ...kdt_G2P 51 - Phrasing decision tree: ...kdt_PHR 52 - Accentuation decision tree: ...kdt_ACC 53 these 5 tree types may be unified in the future to a single type 54 55 - Phono-acoustical model trees: ...kdt_PAM 56 (actually 11 trees, but all have the same characteristics and 57 are instances of the same class) 58 */ 59 /* ************************************************************/ 60 61 62 /* ************************************************************/ 63 /* defines and functions to create specialized kb, */ 64 /* to be used by picorsrc only */ 65 /* ************************************************************/ 66 67 typedef enum { 68 PICOKDT_KDTTYPE_POSP, 69 PICOKDT_KDTTYPE_POSD, 70 PICOKDT_KDTTYPE_G2P, 71 PICOKDT_KDTTYPE_PHR, 72 PICOKDT_KDTTYPE_ACC, 73 PICOKDT_KDTTYPE_PAM 74 } picokdt_kdttype_t; 75 76 pico_status_t picokdt_specializeDtKnowledgeBase(picoknow_KnowledgeBase this, 77 picoos_Common common, 78 const picokdt_kdttype_t type); 79 80 81 /* ************************************************************/ 82 /* decision tree types (opaque) and get Tree functions */ 83 /* ************************************************************/ 84 85 /* decision tree types */ 86 typedef struct picokdt_dtposp * picokdt_DtPosP; 87 typedef struct picokdt_dtposd * picokdt_DtPosD; 88 typedef struct picokdt_dtg2p * picokdt_DtG2P; 89 typedef struct picokdt_dtphr * picokdt_DtPHR; 90 typedef struct picokdt_dtacc * picokdt_DtACC; 91 typedef struct picokdt_dtpam * picokdt_DtPAM; 92 93 /* return kb decision tree for usage in PU */ 94 picokdt_DtPosP picokdt_getDtPosP(picoknow_KnowledgeBase this); 95 picokdt_DtPosD picokdt_getDtPosD(picoknow_KnowledgeBase this); 96 picokdt_DtG2P picokdt_getDtG2P (picoknow_KnowledgeBase this); 97 picokdt_DtPHR picokdt_getDtPHR (picoknow_KnowledgeBase this); 98 picokdt_DtACC picokdt_getDtACC (picoknow_KnowledgeBase this); 99 picokdt_DtPAM picokdt_getDtPAM (picoknow_KnowledgeBase this); 100 101 102 /* number of attributes (= input vector size) for each tree type */ 103 typedef enum { 104 PICOKDT_NRATT_POSP = 12, 105 PICOKDT_NRATT_POSD = 7, 106 PICOKDT_NRATT_G2P = 16, 107 PICOKDT_NRATT_PHR = 8, 108 PICOKDT_NRATT_ACC = 13, 109 PICOKDT_NRATT_PAM = 60 110 } kdt_nratt_t; 111 112 113 /* ************************************************************/ 114 /* decision tree classification result type */ 115 /* ************************************************************/ 116 117 typedef struct { 118 picoos_uint8 set; /* TRUE if class set, FALSE otherwise */ 119 picoos_uint16 class; 120 } picokdt_classify_result_t; 121 122 123 /* maximum number of output values the tree output is mapped to */ 124 #define PICOKDT_MAXSIZE_OUTVEC 8 125 126 typedef struct { 127 picoos_uint8 nr; /* 0 if no class set, nr of values set otherwise */ 128 picoos_uint16 classvec[PICOKDT_MAXSIZE_OUTVEC]; 129 } picokdt_classify_vecresult_t; 130 131 132 /* ************************************************************/ 133 /* decision tree functions */ 134 /* ************************************************************/ 135 136 /* constructInVec: 137 for every tree type there is a constructInVec function to construct 138 the size-optimized input vector for the tree using the input map 139 tables that are part of the decistion tree knowledge base. The 140 constructed input vector is stored in the tree object (this->invec 141 and this->inveclen) and will be used in the following call to the 142 classify function. 143 144 classify: 145 for every tree type there is a classify function to apply the 146 decision tree to the previously constructed input vector. The 147 size-optimized, encoded output is stored in the tree object 148 (this->outval) and will be used in the following call to the 149 decompose function. Where needed (hitory attribute) the direct tree 150 output is returned by the classify function in a variable. 151 152 decomposeOutClass: 153 for every tree type there is a decompose function to decompose the 154 size-optimized, encoded tree output and map it to the outside the 155 tree usable class value. 156 */ 157 158 159 /* ************************************************************/ 160 /* decision tree defines */ 161 /* ************************************************************/ 162 163 /* to construct the input vectors several hard-coded values are used 164 to handle attributes that, at the given position, are outside the 165 context. */ 166 167 /* graph attributes: values to be used if the graph attribute is 168 outside the grapheme string (ie. word) */ 169 #define PICOKDT_OUTSIDEGRAPH_DEFCH (picoos_uint8)'\x30' /* ascii "0" */ 170 #define PICOKDT_OUTSIDEGRAPH_DEFSTR (picoos_uint8 *)"\x30" /* ascii "0" */ 171 #define PICOKDT_OUTSIDEGRAPH_DEFLEN 1 172 173 /* graph attributes (special case for g2p): values to be used if the 174 graph attribute is directly outside the grapheme string (ie. at the 175 word boundary word). Use PICOKDT_OUTSIDEGRAPH_DEF* if further 176 outside. */ 177 #define PICOKDT_OUTSIDEGRAPH_EOW_DEFCH (picoos_uint8)'\x31' /* ascii "1" */ 178 #define PICOKDT_OUTSIDEGRAPH_EOW_DEFSTR (picoos_uint8 *)"\x31" /* ascii "1" */ 179 #define PICOKDT_OUTSIDEGRAPH_EOW_DEFLEN 1 180 181 /* byte and word type attributes: value to be used if a byte or word 182 attribute is outside the context, e.g. for POS */ 183 #define PICOKDT_EPSILON 7 184 185 /* byte and word type attributes: for attribute with history info a 186 'zero' value is needed when starting the sequence of predictions. 187 Use the following value to initialize history. Note that the direct 188 tree outputs (not mapped with output map table) of previous 189 predictions need to be used when constructing the input vector for 190 a following prediction. This direct tree output will then be mapped 191 together with the rest of the input vector by the input map 192 table. */ 193 #define PICOKDT_HISTORY_ZERO 30000 194 195 196 /* ************************************************************/ 197 /* decision tree POS prediction (PosP) functions */ 198 /* ************************************************************/ 199 200 /* construct a POS prediction input vector 201 tree input vector: 0-3 prefix UTF8 graphemes 202 4-9 suffex UTF8 graphemes 203 10 special grapheme existence flag (TRUE/FALSE) 204 11 number of graphemes 205 graph: the grapheme string of the word for wich POS will be predicted 206 graphlen: length of graph in number of bytes 207 specgraphflag: existence of a special grapheme boolean 208 returns: TRUE if okay, FALSE otherwise 209 note: use PICOKDT_OUTSIDEGRAPH* for att values outside context 210 */ 211 picoos_uint8 picokdt_dtPosPconstructInVec(const picokdt_DtPosP this, 212 const picoos_uint8 *graph, 213 const picoos_uint16 graphlen, 214 const picoos_uint8 specgraphflag); 215 216 217 /* classify a previously constructed input vector using tree 'this' 218 returns: TRUE if okay, FALSE otherwise 219 */ 220 picoos_uint8 picokdt_dtPosPclassify(const picokdt_DtPosP this); 221 222 /* decompose the tree output and return the class in dtres 223 dtres: POS or POSgroup ID classification result 224 returns: TRUE if okay, FALSE otherwise 225 */ 226 picoos_uint8 picokdt_dtPosPdecomposeOutClass(const picokdt_DtPosP this, 227 picokdt_classify_result_t *dtres); 228 229 230 /* ************************************************************/ 231 /* decision tree POS disambiguation (PosD) functions */ 232 /* ************************************************************/ 233 234 /* construct a POS disambiguation input vector (run in left-to-right mode) 235 tree input vector: 0-2 POS or POSgroup for each of the three previous words 236 3 POSgroup for current word 237 4-6 POS or POSgroup (can be history) for each of 238 the three following words 239 pre3 - pre1: POSgroup or POS for the previous three words 240 src: POSgroup of current word (if unique POS no posdisa possible) 241 fol1 - fol3: POS or history for the following three words (the more 242 complicated the better... :-( NEEDS TO BE uint16 243 ishist1-ishist3: flag to indicate if fol1-3 are predicted tree 244 output values (history) or the HISTORY_ZERO (TRUE) 245 or an already unambiguous POS (FALSE) 246 returns: TRUE if okay, FALSE otherwise 247 note: use PICOKDT_EPSILON for att values outside context, 248 if POS in fol* unique use this POS instead of real 249 history, use reverse output mapping in these cases 250 */ 251 picoos_uint8 picokdt_dtPosDconstructInVec(const picokdt_DtPosD this, 252 const picoos_uint16 * input); 253 254 255 /* classify a previously constructed input vector using tree 'this' 256 treeout: direct tree output value 257 returns: TRUE if okay, FALSE otherwise 258 */ 259 picoos_uint8 picokdt_dtPosDclassify(const picokdt_DtPosD this, 260 picoos_uint16 *treeout); 261 262 /* decompose the tree output and return the class in dtres 263 dtres: POS classification result 264 returns: TRUE if okay, FALSE otherwise 265 */ 266 picoos_uint8 picokdt_dtPosDdecomposeOutClass(const picokdt_DtPosD this, 267 picokdt_classify_result_t *dtres); 268 269 /* convert (unique) POS index into corresponding tree output index */ 270 picoos_uint8 picokdt_dtPosDreverseMapOutFixed(const picokdt_DtPosD this, 271 const picoos_uint16 inval, 272 picoos_uint16 *outval, 273 picoos_uint16 *outfallbackval); 274 275 /* ************************************************************/ 276 /* decision tree grapheme-to-phoneme (G2P) functions */ 277 /* ************************************************************/ 278 279 /* construct a G2P input vector (run in right-to-left mode) 280 tree input vector: 0-8 the 4 previous, current, and 4 following graphemes 281 9 POS 282 10-11 vowel count and vowel ID 283 12 primary stress flag (TRUE/FALSE) 284 13-15 the three following phones predicted 285 graph: the grapheme string used to determine invec[0:8] 286 graphlen: length of graph in number of bytes 287 count: the grapheme number for which invec will be constructed [0..] 288 pos: the part of speech of the word 289 nrvow number of vowel-like graphemes in graph if vowel, 290 set to 0 otherwise 291 ordvow order of 'count' vowel in graph if vowel, 292 set to 0 otherwise 293 primstressflag: flag indicating if primary stress was already predicted 294 phonech1-3: the three following phon chunks predicted (right-to-left) 295 returns: TRUE if okay, FALSE otherwise 296 */ 297 picoos_uint8 picokdt_dtG2PconstructInVec(const picokdt_DtG2P this, 298 const picoos_uint8 *graph, 299 const picoos_uint16 graphlen, 300 const picoos_uint8 count, 301 const picoos_uint8 pos, 302 const picoos_uint8 nrvow, 303 const picoos_uint8 ordvow, 304 picoos_uint8 *primstressflag, 305 const picoos_uint16 phonech1, 306 const picoos_uint16 phonech2, 307 const picoos_uint16 phonech3); 308 309 /* classify a previously constructed input vector using tree 'this' 310 treeout: direct tree output value 311 returns: TRUE if okay, FALSE otherwise 312 */ 313 picoos_uint8 picokdt_dtG2Pclassify(const picokdt_DtG2P this, 314 picoos_uint16 *treeout); 315 316 /* decompose the tree output and return the class vector in dtvres 317 dtvres: phones vector classification result 318 returns: TRUE if okay, FALSE otherwise 319 */ 320 picoos_uint8 picokdt_dtG2PdecomposeOutClass(const picokdt_DtG2P this, 321 picokdt_classify_vecresult_t *dtvres); 322 323 324 /* ************************************************************/ 325 /* decision tree phrasing (PHR) functions */ 326 /* ************************************************************/ 327 328 /* construct a PHR input vector (run in right-to-left mode) 329 tree input vector: 0-1 POS for each of the two previous words 330 2 POS for current word 331 3-4 POS for each of the two following words 332 5 nr words left 333 6 nr words right 334 7 nr syllables right 335 pre2 - pre1: POS for the previous two words 336 src: POS of current word 337 fol1 - fol2: POS for the following two words 338 nrwordspre: number of words left (previous) of current word 339 nrwordsfol: number of words right (following) of current word, 340 incl. current word, up to next BOUND (also 341 considering previously predicted PHR2/3) 342 nrsyllsfol: number of syllables right (following) of current word, 343 incl. syllables of current word, up to next BOUND 344 (also considering previously predicted PHR2/3) 345 returns: TRUE if okay, FALSE otherwise 346 note: use PICOKDT_EPSILON for att values outside context 347 */ 348 picoos_uint8 picokdt_dtPHRconstructInVec(const picokdt_DtPHR this, 349 const picoos_uint8 pre2, 350 const picoos_uint8 pre1, 351 const picoos_uint8 src, 352 const picoos_uint8 fol1, 353 const picoos_uint8 fol2, 354 const picoos_uint16 nrwordspre, 355 const picoos_uint16 nrwordsfol, 356 const picoos_uint16 nrsyllsfol); 357 358 /* classify a previously constructed input vector using tree 'this' 359 returns: TRUE if okay, FALSE otherwise 360 */ 361 picoos_uint8 picokdt_dtPHRclassify(const picokdt_DtPHR this); 362 363 /* decompose the tree output and return the class vector in dtres 364 dtres: phrasing classification result 365 returns: TRUE if okay, FALSE otherwise 366 */ 367 picoos_uint8 picokdt_dtPHRdecomposeOutClass(const picokdt_DtPHR this, 368 picokdt_classify_result_t *dtres); 369 370 371 /* ************************************************************/ 372 /* decision tree accentuation (ACC) functions */ 373 /* ************************************************************/ 374 375 /* construct an ACC input vector (run in right-to-left mode) 376 tree input vector: 0-1 POS for each of the two previous words 377 2 POS for current word 378 3-4 POS for each of the two following words 379 5-6 history values (already predicted following) 380 7 nr words left (previous) to any bound 381 8 nr syllables left to any bound 382 9 nr words right (following) to any bound 383 10 nr syllables right to any bound 384 11 nr words right to predicted "1" prominence (foot) 385 12 nr syllables right to predicted "1" prominence (foot) 386 pre2 - pre1: POS for the previous two words 387 src: POS of current word 388 fol1 - fol2: POS for the following two words 389 hist1 - hist2: previously predicted ACC values 390 nrwordspre: number of words left (previous) of current word 391 nrsyllspre: number of syllables left (previous) of current word, 392 incl. initial non-prim stress syllables of current word 393 nrwordsfol: number of words right (following) of current word, 394 incl. current word, up to next BOUND (any strength != 0) 395 nrsyllsfol: number of syllables right (following) of current word, 396 incl. syllables of current word starting with prim. stress 397 syllable 398 footwordsfol: nr of words to the following prominence '1' 399 footsyllspre: nr of syllables to the previous prominence '1' 400 returns: TRUE if okay, FALSE otherwise 401 note: use PICOKDT_EPSILON for att 0-4 values outside context 402 */ 403 picoos_uint8 picokdt_dtACCconstructInVec(const picokdt_DtACC this, 404 const picoos_uint8 pre2, 405 const picoos_uint8 pre1, 406 const picoos_uint8 src, 407 const picoos_uint8 fol1, 408 const picoos_uint8 fol2, 409 const picoos_uint16 hist1, 410 const picoos_uint16 hist2, 411 const picoos_uint16 nrwordspre, 412 const picoos_uint16 nrsyllspre, 413 const picoos_uint16 nrwordsfol, 414 const picoos_uint16 nrsyllsfol, 415 const picoos_uint16 footwordsfol, 416 const picoos_uint16 footsyllsfol); 417 418 /* classify a previously constructed input vector using tree 'this' 419 treeout: direct tree output value 420 returns: TRUE if okay, FALSE otherwise 421 */ 422 picoos_uint8 picokdt_dtACCclassify(const picokdt_DtACC this, 423 picoos_uint16 *treeout); 424 425 /* decompose the tree output and return the class vector in dtres 426 dtres: phrasing classification result 427 returns: TRUE if okay, FALSE otherwise 428 */ 429 picoos_uint8 picokdt_dtACCdecomposeOutClass(const picokdt_DtACC this, 430 picokdt_classify_result_t *dtres); 431 432 433 /* ************************************************************/ 434 /* decision tree phono-acoustical model (PAM) functions */ 435 /* ************************************************************/ 436 437 /* construct a Pam input vector and store the tree-specific encoded 438 input vector in the tree object. 439 vec: tree input vector, 60 single-byte-sized attributes 440 veclen: length of vec in number of bytes 441 returns: TRUE if okay, FALSE otherwise 442 */ 443 picoos_uint8 picokdt_dtPAMconstructInVec(const picokdt_DtPAM this, 444 const picoos_uint8 *vec, 445 const picoos_uint8 veclen); 446 447 /* classify a previously constructed input vector using tree 'this' 448 returns: TRUE if okay, FALSE otherwise 449 */ 450 picoos_uint8 picokdt_dtPAMclassify(const picokdt_DtPAM this); 451 452 /* decompose the tree output and return the class in dtres 453 dtres: phones vector classification result 454 returns: TRUE if okay, FALSE otherwise 455 */ 456 picoos_uint8 picokdt_dtPAMdecomposeOutClass(const picokdt_DtPAM this, 457 picokdt_classify_result_t *dtres); 458 459 #ifdef __cplusplus 460 } 461 #endif 462 463 464 465 #endif /*PICOKDT_H_*/ 466