• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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