Scripts

stage1.py and stage2.py

These scripts can be used to generate C code representing the required first and second stage filters used by the mic array.

• stage1.py outputs an array for the first stage filter

• stage2.py outputs an array for the second stage filter

Each script takes a Python .pkl file as an input (via the command line), and outputs a simple C-style array initializer in the terminal. That output can be used to overwrite the filter coefficients in an application.

Example

The following is an example of running stage1.py.

lib_mic_array\python>python stage1.py filter_design\good_2_stage_filter_int.pkl
Stage 1 Decimation Factor: 32
Stage 1 Tap Count: 125
Stage 2 Decimation Factor: 6
Stage 2 Tap Count: 256

Filter word count: 128

{
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xEEEEEEEE, 0xEEEEEEEE, 0xEEEEEEEE, 0xEEEEEEEE,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFAFAFAFA, 0xFAFAFAFA, 0xEBEBEBEB, 0xEBEBEBEB,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xF5A0F5A0, 0xE4B1E4B1, 0xF1A4F1A4, 0xE0B5E0B5,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFB51AE04, 0xEF54BA01, 0xF00BA55E, 0xE40EB15B,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFD1353BD, 0xB31809B3, 0xF9B20319, 0xB7B95917,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFE4D120F, 0x584AEB52, 0xA95AEA43, 0x5E09164F,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFF94E621, 0x17931C80, 0x0027193D, 0x108CE53F,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFE6AE34, 0xE549505E, 0xEF415254, 0xE58EACFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFF8CB6C, 0x066D9FCB, 0x1A7F36CC, 0x06DA63FF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFF0C49, 0x52DB4A93, 0xF92A5B69, 0x52461FFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFF071, 0x9B6D931C, 0x071936DB, 0x31C1FFFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFF81, 0xE38E1C1F, 0xFF070E38, 0xF03FFFFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFE, 0x03F01FE0, 0x00FF01F8, 0x0FFFFFFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFC001FFF, 0xFFFF0007, 0xFFFFFFFF,
  0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFE000, 0x0000FFFF, 0xFFFFFFFF,
  0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
}

Here, the input .pkl file good_2_stage_filter_int.pkl was generated using filter_design/design_filter.py. The script outputs some basic information about the filter followed by a C array initializer of 128 words.

The output array can be used to initialize an array of type uint32_t. The values in the array may appear to have little relation to those directly in the .pkl file because the implementation of the first stage filter requires the coefficients to be reordered in a bit-wise manner for run-time optimization.

The following is an example of stage2.py being run with the same input file.

lib_mic_array\python>python stage2.py filter_design\good_2_stage_filter_int.pkl
Stage 1 Decimation Factor: 32
Stage 1 Tap Count: 125
Stage 2 Decimation Factor: 6
Stage 2 Tap Count: 256

Right-shift: 4

{
0x12cbd, 0x1bc68, 0x1e848, 0x16e3b, 0x34fc, -0x19c13, -0x396a4, -0x517d3, -0x572c4, -0x42a99, -0x12b2d, 0x3136a, 0x78fc9, 0xaf0c5, 0xbdfb3, 0x976fb, 0x3a55b, -0x49c82, -0xd5ee1, -0x141f1d, -0x166e07, -0x12b197, -0x8cb56, 0x594d5, 0x151a2b, 0x217aba, 0x268fd9, 0x219572, 0x123738, -0x4ec96, -0x1e8a6b, -0x33c24b, -0x3ddb52, -0x383953, -0x220324, 0x10d0c, 0x290b3c, 0x4b7d38, 0x5df58f, 0x590923, 0x3ad314, 0x83f9d, -0x336a4b, -0x68da62, -0x887959, -0x86bb28, -0x5fdb9e, -0x19e511, 0x3bc670, 0x8b8db4, 0xbedc73, 0xc4446c, 0x94e8ba, 0x379c2f, -0x3f6e52, -0xb2ae73, -0x10257a9, -0x114d20e, -0xde6ae6, -0x66087d, 0x3abb9a, 0xdc9726, 0x153d6f5, 0x17bd0e7, 0x141966a, 0xaae708, -0x28e308, -0x106c5f0, -0x1b3f8e6, -0x1fd12db, -0x1c4a9b6, -0x10d64a6, 0x3a8af, 0x12db80b, 0x2232795, 0x29d2c56, 0x26f81a8, 0x196c603, 0x3d29f5, -0x14cb2a5, -0x2a1db99, -0x3623ba6, -0x34cc828, -0x253b843, -0xa4d6a3, 0x15d59b2, 0x33128a8, 0x45581b2, 0x46c6158, 0x357091a, 0x143e5e3, -0x156ca08, -0x3d3d9c1, -0x586bd77, -0x5e8a05f, -0x4bf99e5, -0x235288f, 0x12b764c, 0x490cfd8, 0x713c998, 0x7f2705a, 0x6c6a6e1, 0x3aa1c29, -0xc38997, -0x578b750, -0x93c3c2b, -0xaf1da5a, -0x9e75bfb, -0x60eaa5b, -0x14591a, 0x6b69c4c, 0xc9ef41c, 0xff16c12, 0xf689a74, 0xa8d3041, 0x1f08228, -0x8cffe95, -0x13445d3b, -0x1a994e72, -0x1c28c7ca, -0x160ef96b, -0x7a3c5f0, 0xe431389, 0x295878fd, 0x4629d110, 0x60af1114, 0x74fe4fe9, 0x7fffffff, 0x7fffffff, 0x74fe4fe9, 0x60af1114, 0x4629d110, 0x295878fd, 0xe431389, -0x7a3c5f0, -0x160ef96b, -0x1c28c7ca, -0x1a994e72, -0x13445d3b, -0x8cffe95, 0x1f08228, 0xa8d3041, 0xf689a74, 0xff16c12, 0xc9ef41c, 0x6b69c4c, -0x14591a, -0x60eaa5b, -0x9e75bfb, -0xaf1da5a, -0x93c3c2b, -0x578b750, -0xc38997, 0x3aa1c29, 0x6c6a6e1, 0x7f2705a, 0x713c998, 0x490cfd8, 0x12b764c, -0x235288f, -0x4bf99e5, -0x5e8a05f, -0x586bd77, -0x3d3d9c1, -0x156ca08, 0x143e5e3, 0x357091a, 0x46c6158, 0x45581b2, 0x33128a8, 0x15d59b2, -0xa4d6a3, -0x253b843, -0x34cc828, -0x3623ba6, -0x2a1db99, -0x14cb2a5, 0x3d29f5, 0x196c603, 0x26f81a8, 0x29d2c56, 0x2232795, 0x12db80b, 0x3a8af, -0x10d64a6, -0x1c4a9b6, -0x1fd12db, -0x1b3f8e6, -0x106c5f0, -0x28e308, 0xaae708, 0x141966a, 0x17bd0e7, 0x153d6f5, 0xdc9726, 0x3abb9a, -0x66087d, -0xde6ae6, -0x114d20e, -0x10257a9, -0xb2ae73, -0x3f6e52, 0x379c2f, 0x94e8ba, 0xc4446c, 0xbedc73, 0x8b8db4, 0x3bc670, -0x19e511, -0x5fdb9e, -0x86bb28, -0x887959, -0x68da62, -0x336a4b, 0x83f9d, 0x3ad314, 0x590923, 0x5df58f, 0x4b7d38, 0x290b3c, 0x10d0c, -0x220324, -0x383953, -0x3ddb52, -0x33c24b, -0x1e8a6b, -0x4ec96, 0x123738, 0x219572, 0x268fd9, 0x217aba, 0x151a2b, 0x594d5, -0x8cb56, -0x12b197, -0x166e07, -0x141f1d, -0xd5ee1, -0x49c82, 0x3a55b, 0x976fb, 0xbdfb3, 0xaf0c5, 0x78fc9, 0x3136a, -0x12b2d, -0x42a99, -0x572c4, -0x517d3, -0x396a4, -0x19c13, 0x34fc, 0x16e3b, 0x1e848, 0x1bc68, 0x12cbd
}

Similar output is produced. In addition to the filter coefficient array, stage2.py outputs a right-shift (here 4) which is needed by the second stage filter.

The simplest way to use these coefficients in an application is to replace the values in ../lib_mic_array/src/etc/stage1_fir_coef.c and ../lib_mic_array/src/etc/stage2_fir_coef.c.

Input pkl File

stage1.py and stage2.py load the contents of the supplied .pkl file using pickle.load()` from the pickle Python module. They expect the result of load() to have type compatible with Tuple[Tuple[numpy.ndarray,int],Tuple[numpy.ndarray,int]]. The following pseudo-code should help clarify this:

stage1, stage2 = pkl.load(filter_coef_pkl_file)
stage1_coef_array, stage1_decimation_factor = stage1
stage2_coef_array, stage2_decimation_factor = stage2

assert stage1_coef_array.dtype == np.int16
assert stage2_coef_array.dtype == np.int32
assert stage1_decimation_factor == 32

Further constraints, as illustrated above, are that the stage1 filter coefficients should be np.int16 (signed 16-bit integers) and stage2 filter coeffiients should be np.int32 (signed 32-bit integers). Further, the first stage filter currently only supports a decimation factor of 32.

Using Custom Coefficients in an Application

The C files ../lib_mic_array/src/etc/stage1_fir_coef.c and ../lib_mic_array/src/etc/stage2_fir_coef.c provide an example of how the outputs of stage1.py and stage2.py may be used.

Note

If the stage 2 decimation factor or tap count changes ../lib_mic_array/api/etc/filters_default.h must also be updated to reflect that change.

The filter coefficients used by the decimator as specified when initializing the decimator (e.g. mic_array::TwoStageDecimator). To use custom coefficients when directly working with the mic array’s C++ objects, simply provide a pointer to your custom coefficients to the decimator’s Init() method.

Alternatively, lib_mic_array’s Vanilla API and the mic_array::prefab::BasicMicArray class template both automatically use the filter coefficients given by the symbols stage1_coef, stage2_coef and stage2_shr when initializing the decimator.

In that case, there are two options to use custom filter. The first and easiest is to simply overwrite the coefficients given in ../lib_mic_array/src/etc/stage1_fir_coef.c and ../lib_mic_array/src/etc/stage2_fir_coef.c. If that is not an option, you may also add your own source files containing your coefficients to your project (using the same symbol names) and exclude stage1_fir_coef.c and stage2_fircoef.c from the project’s source files.