andrewm@0: /*
andrewm@0:   TouchKeys: multi-touch musical keyboard control software
andrewm@0:   Copyright (c) 2013 Andrew McPherson
andrewm@0: 
andrewm@0:   This program is free software: you can redistribute it and/or modify
andrewm@0:   it under the terms of the GNU General Public License as published by
andrewm@0:   the Free Software Foundation, either version 3 of the License, or
andrewm@0:   (at your option) any later version.
andrewm@0:  
andrewm@0:   This program is distributed in the hope that it will be useful,
andrewm@0:   but WITHOUT ANY WARRANTY; without even the implied warranty of
andrewm@0:   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
andrewm@0:   GNU General Public License for more details.
andrewm@0: 
andrewm@0:   You should have received a copy of the GNU General Public License
andrewm@0:   along with this program.  If not, see <http://www.gnu.org/licenses/>.
andrewm@0:  
andrewm@0:   =====================================================================
andrewm@0:  
andrewm@0:   PianoKeyCalibrator.h: handles calibration of continuous key position data
andrewm@0: */
andrewm@0: 
andrewm@0: 
andrewm@0: #ifndef KEYCONTROL_PIANO_KEY_CALIBRATOR_H
andrewm@0: #define KEYCONTROL_PIANO_KEY_CALIBRATOR_H
andrewm@0: 
andrewm@0: #include <iostream>
andrewm@0: #include <boost/circular_buffer.hpp>
andrewm@0: #include "../JuceLibraryCode/JuceHeader.h"
andrewm@0: #include "../Utility/Types.h"
andrewm@0: #include "PianoKeyboard.h"
andrewm@0: 
andrewm@0: // Calibration status of the Piano Bar.  This compensates for variations in mechanical position, light level, etc.
andrewm@0: enum {
andrewm@0: 	kPianoKeyNotCalibrated = 0,
andrewm@0: 	kPianoKeyCalibrated,
andrewm@0: 	kPianoKeyInCalibration
andrewm@0: };
andrewm@0: 
andrewm@0: // Size of the calibration history we keep
andrewm@0: const size_t kPianoKeyCalibrationBufferSize = 32; // 32
andrewm@0: const size_t kPianoKeyCalibrationPressLength = 10; // 10
andrewm@0: 
andrewm@0: // Minimum amount of range between quiescent and press for a note to be calibrated
andrewm@0: const int kPianoKeyCalibrationMinimumRange = 64;
andrewm@0: 
andrewm@0: /*
andrewm@0:  * PianoKeyboardCalibrator
andrewm@0:  *
andrewm@0:  * This class defines a calibration from raw value to normalized value, generically for
andrewm@0:  * any sensor which outputs a continuous value for key position. It allows the calibration 
andrewm@0:  * to be learned and applied. It allows a direction to be set where pressed keys are either
andrewm@0:  * greater or lower in value than unpressed keys, to accommodate different sensor topologies.
andrewm@0:  */
andrewm@0: 
andrewm@0: class PianoKeyCalibrator {
andrewm@0: public:
andrewm@0: 	// ***** Constructor *****
andrewm@0: 	
andrewm@0: 	PianoKeyCalibrator(bool pressValueGoesDown, key_position* warpTable);
andrewm@0: 	
andrewm@0: 	// ***** Destructor *****
andrewm@0: 	
andrewm@0: 	~PianoKeyCalibrator();
andrewm@0: 	
andrewm@0: 	// ***** Evaluator *****
andrewm@0: 	//
andrewm@0: 	// In normal (operational) mode, evaluate() returns the calibrated value for the raw input.
andrewm@0: 	// In other modes, it returns a "missing" value.  Specifically in calibration mode, it updates
andrewm@0: 	// the settings for calibration.
andrewm@0: 	
andrewm@0: 	key_position evaluate(int rawValue);
andrewm@0: 	
andrewm@0: 	// ***** Calibration Methods *****
andrewm@0: 	//
andrewm@0:     // Return the current status
andrewm@0:     int calibrationStatus() { return status_; }
andrewm@0:     
andrewm@0: 	// Manage the calibration state
andrewm@0: 	
andrewm@0: 	void calibrationStart();
andrewm@0: 	bool calibrationFinish();   // Returns true on successful calibration
andrewm@0: 	void calibrationAbort();
andrewm@0: 	void calibrationClear();
andrewm@0: 	
andrewm@0: 	// Learn new quiescent values only.  This needs to be called from a thread other than the data source
andrewm@0: 	// (audio or serial callback) thread, since it waits for the buffer to fill up before calculating the values.
andrewm@0: 	
andrewm@0: 	void calibrationUpdateQuiescent();
andrewm@0: 	
andrewm@0: 	// ***** XML I/O Methods *****
andrewm@0: 	//
andrewm@0: 	// These methods load and save calibration data from an XML string.  The PianoKeyCalibrator object handles
andrewm@0: 	// the relevant file I/O.
andrewm@0: 	
andrewm@0: 	void loadFromXml(const XmlElement& baseElement);
andrewm@0: 	bool saveToXml(XmlElement& baseElement);
andrewm@0: 	
andrewm@0: private:
andrewm@0: 	// ***** Helper Methods *****
andrewm@0: 	
andrewm@0: 	void changeStatus(int newStatus) {
andrewm@0: 		prevStatus_ = status_;
andrewm@0: 		status_ = newStatus;
andrewm@0: 	}
andrewm@0: 	
andrewm@0: 	// Update quiescent values
andrewm@0: 	bool internalUpdateQuiescent();
andrewm@0: 	
andrewm@0: 	// Average position over the history buffer, for finding minima and maxima
andrewm@0: 	int averagePosition(int length);
andrewm@0: 	
andrewm@0: 	// Clean up after a calibration; called by finish() and abort()
andrewm@0: 	void cleanup();
andrewm@0: 	
andrewm@0: 	// ***** Member Variables *****
andrewm@0: 	
andrewm@0: 	int status_, prevStatus_;		// Status of calibration (see enum above), and its previous value
andrewm@0: 	bool pressValueGoesDown_;		// If true, the pressed key value is expected to be lower than the quiescent
andrewm@0: 	int quiescent_;                 // Resting value for the sensor
andrewm@0: 	int press_;                     // Fully pressed value for the sensor
andrewm@0: 	int newPress_;                  // Value-in-training for press
andrewm@0: 	
andrewm@0: 	boost::circular_buffer<int>* history_;  // Buffer holds history of raw values for calibrating
andrewm@0: 	
andrewm@0: 	// Table of warping values to correct for sensor non-linearity
andrewm@0: 	key_position* warpTable_;
andrewm@0:     
andrewm@0: 	CriticalSection calibrationMutex_;	// This mutex protects access to the entire calibration structure
andrewm@0: 	CriticalSection historyMutex_;		// This mutex is specifically tied to the history_ buffers
andrewm@0: };
andrewm@0: 
andrewm@0: #endif /* KEYCONTROL_PIANO_KEY_CALIBRATOR_H */
andrewm@0: