From 64dbfc52f2df3414fb2cd5e542bc2cd3f3b7bf79 Mon Sep 17 00:00:00 2001 From: tungntEmotiv Date: Wed, 4 Nov 2026 15:27:29 +0700 Subject: [PATCH 1/5] Cor 6536: Python Bridge, Core Helpers & Authorization Test Matlab Example (#246) * COR-6536: add python bridge script and authentication classes * COR-6536: update rework and restructure folder to make clearer for user * COR-6536: add subscribe and plot example * update rework * remove obsolete files * fix timeout for create connectin * COR-6536: remove python script and update java lib to handle wss * COR-6536: separate to parser and buffer classes * update rework --- .gitignore | 1 + octave/README.md | 189 +++++++++++++ octave/config/config.example.json | 4 + octave/examples/authorizeAndShowAccount.m | 22 ++ octave/examples/subscribeAndPlot.m | 170 ++++++++++++ octave/functions/cortexConnect.m | 47 ++++ octave/functions/cortexDisconnect.m | 19 ++ octave/functions/cortexGetData.m | 27 ++ octave/functions/cortexSubscribe.m | 62 +++++ octave/internal/CortexAuth.m | 159 +++++++++++ octave/internal/CortexClient.m | 320 ++++++++++++++++++++++ octave/internal/CortexContext.m | 16 ++ octave/internal/CortexDataBuffer.m | 104 +++++++ octave/internal/CortexHeadset.m | 280 +++++++++++++++++++ octave/internal/CortexManager.m | 72 +++++ octave/internal/CortexStreamParser.m | 77 ++++++ octave/internal/cortexCredentials.m | 32 +++ octave/java/cortex/CortexWsClient.java | 115 ++++++++ octave/lib/cortex-ws-client.jar | Bin 0 -> 3571 bytes octave/lib/nv-websocket-client-2.14.jar | Bin 0 -> 125171 bytes 20 files changed, 1716 insertions(+) create mode 100644 octave/README.md create mode 100644 octave/config/config.example.json create mode 100644 octave/examples/authorizeAndShowAccount.m create mode 100644 octave/examples/subscribeAndPlot.m create mode 100644 octave/functions/cortexConnect.m create mode 100644 octave/functions/cortexDisconnect.m create mode 100644 octave/functions/cortexGetData.m create mode 100644 octave/functions/cortexSubscribe.m create mode 100644 octave/internal/CortexAuth.m create mode 100644 octave/internal/CortexClient.m create mode 100644 octave/internal/CortexContext.m create mode 100644 octave/internal/CortexDataBuffer.m create mode 100644 octave/internal/CortexHeadset.m create mode 100644 octave/internal/CortexManager.m create mode 100644 octave/internal/CortexStreamParser.m create mode 100644 octave/internal/cortexCredentials.m create mode 100644 octave/java/cortex/CortexWsClient.java create mode 100644 octave/lib/cortex-ws-client.jar create mode 100644 octave/lib/nv-websocket-client-2.14.jar diff --git a/.gitignore b/.gitignore index 19d2a95..930f894 100644 --- a/.gitignore +++ b/.gitignore @@ -79,3 +79,4 @@ unity/*.unityproj ### Project-specific cortex_creds *build-* +octave/config/config.json diff --git a/octave/README.md b/octave/README.md new file mode 100644 index 0000000..d1b8b80 --- /dev/null +++ b/octave/README.md @@ -0,0 +1,189 @@ +# Emotiv Cortex Octave/MATLAB Examples + +This folder contains a small MATLAB/GNU Octave client for the Emotiv Cortex API. The first example checks the connection, verifies that an Emotiv user is logged in, requests application access when needed, authorizes the application, and prints basic account and license information. + +The examples are written for researchers and engineers who use MATLAB or GNU Octave for analysis. You do not need to understand the internal classes to run the example. + +## What You Will Run + +The local connection has two parts: + +1. **EMOTIV Launcher**: Provides the local Cortex service and the logged-in Emotiv account. +2. **MATLAB or GNU Octave**: Runs the example and connects directly to Cortex at `wss://localhost:6868` using the bundled Java WebSocket client (`lib/`). No separate process is needed. + +## Folder Structure + +- `functions/`: Public functions (`cortexConnect`, `cortexSubscribe`, `cortexGetData`, `cortexDisconnect`) that hide the internal MATLAB classes. +- `internal/`: Internal SDK classes. Not a public interface; they may change. +- `lib/`: `nv-websocket-client-2.14.jar` and `cortex-ws-client.jar`, the Java WebSocket client used for WSS. +- `java/`: Source of the small Java wrapper (`cortex-ws-client.jar`). +- `config/`: Local configuration. Copy `config/config.example.json` to `config/config.json` to store your Cortex application credentials. `config/config.json` is ignored by Git and must not be committed or shared. +- `examples/`: Beginner-friendly scripts that show complete workflows. + +The public workflow uses `cortexConnect` and `cortexDisconnect`. The underlying `CortexManager` and `CortexAuth` classes are kept inside `internal/` so future examples can extend the SDK without making the user-facing scripts more complicated. + +## Requirements + +### EMOTIV software and account + +- EMOTIV Launcher installed and running. +- An Emotiv account signed in to EMOTIV Launcher. +- A compatible EMOTIV headset, or a virtual headset configured in EMOTIV Launcher. +- A Cortex application with a Client ID and Client Secret. + +Download EMOTIV Launcher from the [EMOTIV website](https://www.emotiv.com/products/emotiv-launcher). Follow the Launcher prompts to accept the current Terms of Use, Privacy Policy, and EULA. + +### Java + +- MATLAB or GNU Octave with a working Java VM. +- The client verifies Cortex TLS certificates using the repository's `certificates/rootCA.pem` CA bundle. +- Keep the repository-level `certificates/rootCA.pem` file when copying the Octave examples; the client reports a clear error if it is missing. +### MATLAB or GNU Octave + +Use a recent MATLAB release or GNU Octave version with: + +- `jsonencode` and `jsondecode` support. +- Java support (the bundled jars in `lib/` are loaded automatically). +- Permission to open a TLS connection to `localhost:6868`. + +The SDK does not require the MATLAB Instrument Control Toolbox, an Octave sockets package, or a separate JSON package. + +## Register a Cortex Application + +The Client ID and Client Secret identify your application. They are different from your Emotiv account password. + +1. Sign in to your Emotiv account. +2. Open the Cortex application management page: [Emotiv Cortex Apps](https://www.emotiv.com/my-account/cortex-apps/). +3. Create a Cortex application, or open an existing application. +4. Copy its **Client ID** and **Client Secret**. +5. Keep the Client Secret private. Do not paste it into source code, commit it to Git, or send it in a public issue. + +You can also follow the application-registration instructions in the repository's [Python examples README](../python/README.md) and the [official Cortex API documentation](https://emotiv.gitbook.io/cortex-api). + +## Configure Your Credentials + +The example reads credentials from `octave/config/config.json`. + +1. Copy `octave/config/config.example.json` to `octave/config/config.json`. +2. Open `octave/config/config.json` and replace the placeholder values with the Client ID and Client Secret from your Cortex application: + +```json +{ + "clientId": "YOUR_CLIENT_ID", + "clientSecret": "YOUR_CLIENT_SECRET" +} +``` + +3. Save the file. + +`cortexConnect` loads `octave/config/config.json` automatically and raises an error if the file does not exist. + +The repository ignores `octave/config/config.json` because it contains a secret. Keep your real credentials only in `octave/config/config.json` and do not commit or share it. + +## Quickstart + +Run these steps in order. + +### 1. Start EMOTIV Launcher + +Open EMOTIV Launcher and sign in. Make sure Cortex is available before running the example. + +If you are testing without a physical headset, create or enable a virtual headset in EMOTIV Launcher according to the [virtual brainwear guide](https://emotiv.gitbook.io/emotiv-launcher/devices-setting-up-virtual-brainwear-r/creating-a-virtual-brainwear-device). + +### 2. Configure `config.json` + +Complete the credential setup described above before running the example. + +### 3. Run the authentication example + +Open MATLAB or GNU Octave from the repository root and run: + +```matlab +run('octave/examples/authorizeAndShowAccount.m') +``` + +The script adds `octave/functions` to the search path automatically (`cortexConnect` adds `octave/internal` internally). It then calls this simple workflow: + +```matlab +cortex = cortexConnect(); +% Use cortex.token, cortex.userInfo, and cortex.licenseInfo here. +cortex = cortexDisconnect(cortex); +``` + +A successful run prints an authorization message, the Cortex token length or token, the logged-in username, and the license name. The example closes the connection before it finishes. + +### 4. Approve application access when prompted + +The first authorization may require approval in EMOTIV Launcher. Keep the application open and approve access when prompted. The example waits for approval for up to 180 seconds. + +## Understanding the Result + +`cortexConnect` returns a plain MATLAB/Octave struct: + +- `cortex.isConnected`: `true` after the Cortex connection and authorization succeed. +- `cortex.token`: The Cortex token for later API requests. +- `cortex.userInfo`: Information returned by `getUserInformation`. +- `cortex.licenseInfo`: License information returned by `getLicenseInfo`. + +The internal manager is stored in the struct only so that `cortexDisconnect(cortex)` can close the WebSocket. Treat that field as internal and do not edit it. + +## Subscribe and Plot + +`examples/subscribeAndPlot.m` demonstrates subscribing to the `eeg` stream and plotting its electrode channels. + +1. Open `examples/subscribeAndPlot.m` and set `headsetId` (shown in EMOTIV Launcher, for example `INSIGHT-A1B2C3D4`). +2. Run `run('octave/examples/subscribeAndPlot.m')`. + +```matlab +cortex = cortexConnect(); +cortex = cortexSubscribe(cortex, 'INSIGHT-A1B2C3D4', {'eeg'}); +[labels, data, time] = cortexGetData(cortex, 'eeg', 256); % newest 256 samples +cortex = cortexDisconnect(cortex); % unsubscribes and closes the socket +``` + +- To subscribe to other supported streams, pass their names instead, for example `{'mot','dev','eq','pow','met'}`. Call `cortexGetData(cortex, streamName)` for each stream you want to consume. +- `labels{j}` names column `j` of `data`; each row is a sample. Use the returned labels to select columns rather than hard-coding positions. For console output, loop over `labels` and print each `data(end,j)`; for plots, plot the desired numeric columns against `time`. +- `met` columns named `.isActive` are 1 when that metric is running. When it is 0 the metric value is `NaN` (Cortex sends `null`). Without a PRO license `met` arrives about every 10 seconds; with a PRO license about 2 samples per second. `pow` does not need a PRO license. +- `cortexSubscribe` scans for the headset, connects it if needed (waiting up to 5 seconds for Cortex warning 104), creates an active session and subscribes. Optional name/value pairs: `'autoRescan'` (default `true`), `'queryInterval'` (default `3` seconds), `'scanTimeout'` (default `15` seconds). +- `cortexGetData` collects the samples that have arrived and returns them from a buffer that keeps the latest 10000 samples per stream. `data` has one row per sample and one column per entry in `labels`; empty values are `NaN`. +- Call `cortexGetData` regularly. Samples are only read from the connection when it runs, and it can take up to about 1 second when no data is arriving. + +## Troubleshooting + +### Could not connect to Cortex at `wss://localhost:6868` + +- Open EMOTIV Launcher and sign in. +- Confirm that Cortex is available in the Launcher. +- If certificate verification fails, confirm that `certificates/rootCA.pem` is present in the repository. +- If a jar is reported missing, restore the `lib/` folder from the repository. +- Restart EMOTIV Launcher and run the example again. +- Check that local security software is not blocking the connection. + +### No user is logged in + +Sign in to EMOTIV Launcher and run `authorizeAndShowAccount.m` again. + +### Application access is not granted + +Approve the application-access request in EMOTIV Launcher. The example waits for up to 180 seconds. If the wait expires, run the example again after approving access. + +### Invalid Client ID or Client Secret + +Open the Cortex application page and copy the credentials again. Make sure `config.json` contains valid JSON and that the property names are exactly `clientId` and `clientSecret`. + +### `jsondecode` or `jsonencode` is unavailable + +Use a recent MATLAB or GNU Octave release with native JSON support. The SDK does not install or use a third-party JSON package. + +### Headset not found or not connected + +- Switch the headset on and make sure it is in range, or enable a virtual headset in EMOTIV Launcher. +- Check that `headsetId` matches the id shown in EMOTIV Launcher exactly. +- Increase `'scanTimeout'` in `cortexSubscribe` if the headset is slow to appear. +- If you see "warning 104 was not received", the headset did not finish connecting in 5 seconds; try again. + +## Next Steps + +Once authentication works, new examples can reuse the same connection pattern and build additional Cortex workflows in `functions/` and `examples/`. Keep transport and authentication details in `internal/`, and keep researcher-facing scripts short and sequential. + +For the full API reference, see the [official Emotiv Cortex API documentation](https://emotiv.gitbook.io/cortex-api). diff --git a/octave/config/config.example.json b/octave/config/config.example.json new file mode 100644 index 0000000..3b734ea --- /dev/null +++ b/octave/config/config.example.json @@ -0,0 +1,4 @@ +{ + "clientId": "YOUR_CLIENT_ID", + "clientSecret": "YOUR_CLIENT_SECRET" +} diff --git a/octave/examples/authorizeAndShowAccount.m b/octave/examples/authorizeAndShowAccount.m new file mode 100644 index 0000000..1326732 --- /dev/null +++ b/octave/examples/authorizeAndShowAccount.m @@ -0,0 +1,22 @@ +% authorizeAndShowAccount Connect to Cortex, authorize this app, show user and license information, and disconnect. + +% 1. Initialization & Configuration: make the SDK functions visible. +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% 2. Connection / Authentication: needs EMOTIV Launcher running with a logged-in user. +% Credentials are loaded from config/config.json. +cortex = cortexConnect(); + +% 3. Action: show the result of the authentication. +if cortex.isConnected + fprintf('[authorizeAndShowAccount] Authorized. cortexToken length: %d\n', numel(cortex.token)); + fprintf('[authorizeAndShowAccount] User: %s\n', cortex.userInfo.username); + fprintf('[authorizeAndShowAccount] License: %s\n', cortex.licenseInfo.licenseName); +else + fprintf('[authorizeAndShowAccount] Authentication failed. See the messages above.\n'); +end + +% 4. Safe Teardown: always release the socket, even after a failed connection. +cortex = cortexDisconnect(cortex); +fprintf('[authorizeAndShowAccount] Done.\n'); diff --git a/octave/examples/subscribeAndPlot.m b/octave/examples/subscribeAndPlot.m new file mode 100644 index 0000000..6c924d9 --- /dev/null +++ b/octave/examples/subscribeAndPlot.m @@ -0,0 +1,170 @@ +function subscribeAndPlot() +% subscribeAndPlot Subscribe to EEG, motion (mot), and performance metrics (met) streams and plot live. + +% 1. Initialization & Configuration: make the SDK functions visible. +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Set your headset id (shown in EMOTIV Launcher, for example 'INSIGHT-A1B2C3D4'). +headsetId = ''; +streams = {'eeg'}; +durationSeconds = 90; + +% 2. Connection / Authentication, then headset connection and subscription. +% Credentials are loaded from config/config.json. +cortex = cortexConnect(); +connectionCleanup = onCleanup(@() cortexDisconnect(cortex)); +if cortex.isConnected + cortex = cortexSubscribe(cortex, headsetId, streams); +end + +% 3. Acquisition Loop: each cortexGetData call collects new samples into the buffer. +try + if cortex.isSubscribed + figs = struct(); + if ismember('eeg', cortex.streams) + figs.eeg = figure('Name', 'Live EEG', 'NumberTitle', 'off'); + end + if ismember('mot', cortex.streams) + figs.mot = figure('Name', 'Live Motion (IMU)', 'NumberTitle', 'off'); + end + if ismember('met', cortex.streams) + figs.met = figure('Name', 'Live Performance Metrics', 'NumberTitle', 'off'); + end + + startedAt = tic(); + while toc(startedAt) < durationSeconds && hasOpenFigure(figs) + if isfield(figs, 'eeg') && ishandle(figs.eeg) + [labels, data, time] = cortexGetData(cortex, 'eeg', 256); + if ~isempty(data) + plotEeg(figs.eeg, labels, data, time); + end + end + + if isfield(figs, 'mot') && ishandle(figs.mot) + [labels, data, time] = cortexGetData(cortex, 'mot', 160); + if ~isempty(data) + plotMotion(figs.mot, labels, data, time); + end + end + + if isfield(figs, 'met') && ishandle(figs.met) + [labels, data, time] = cortexGetData(cortex, 'met', 60); + if ~isempty(data) + plotPm(figs.met, labels, data, time); + end + end + + drawnow; + end + + for index = 1:numel(cortex.streams) + streamName = cortex.streams{index}; + [~, data] = cortexGetData(cortex, streamName); + fprintf('[subscribeAndPlot] %s: %d samples buffered.\n', streamName, size(data, 1)); + end + end +catch failure + fprintf('[subscribeAndPlot] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% 4. Safe Teardown: unsubscribes and releases the socket, even after an error. +clear connectionCleanup; +fprintf('[subscribeAndPlot] Done.\n'); +end + +function open = hasOpenFigure(figs) +fields = fieldnames(figs); +open = false; +for i = 1:numel(fields) + if ishandle(figs.(fields{i})) + open = true; + return; + end +end +end + +function plotEeg(fig, labels, data, time) +% plotEeg Plot multi-channel EEG with +/-100 uV per trace and 200 uV channel spacing. +figure(fig); +channels = find(strcmp(labels, 'INTERPOLATED')) + 1:find(strcmp(labels, 'RAW_CQ')) - 1; +if isempty(channels), return; end + +eeg = data(:, channels); +eeg = eeg - mean(eeg, 1, 'omitnan'); +eeg = max(min(eeg, 100), -100); + +numChannels = numel(channels); +offsets = (numChannels - 1:-1:0) * 200; +t = time - time(end); + +plot(t, bsxfun(@plus, eeg, offsets)); +ylim([-100, (numChannels - 1) * 200 + 100]); +set(gca, 'YTick', fliplr(offsets), 'YTickLabel', fliplr(labels(channels))); +title('EEG (+/-100 uV per trace, 200 uV spacing)'); +xlabel('Seconds'); +ylabel('Channel'); +end + +function plotMotion(fig, labels, data, time) +% plotMotion Plot 9-axis IMU motion stream: +% - Quaternions (Q0..Q3): [-1, 1] (or Gyroscope GYROX..GYROZ: [-100, 100] dps) +% - Accelerometer (ACCX..ACCZ): [-4, 4] g +% - Magnetometer (MAGX..MAGZ): [-4900, 4900] uT +figure(fig); +t = time - time(end); + +quatCols = find(ismember(labels, {'Q0', 'Q1', 'Q2', 'Q3'})); +gyroCols = find(ismember(labels, {'GYROX', 'GYROY', 'GYROZ'})); +accCols = find(ismember(labels, {'ACCX', 'ACCY', 'ACCZ'})); +magCols = find(ismember(labels, {'MAGX', 'MAGY', 'MAGZ'})); + +subplot(3, 1, 1); +if ~isempty(quatCols) + plot(t, data(:, quatCols)); + ylim([-1, 1]); + legend(labels(quatCols), 'Location', 'eastoutside'); + title('Quaternions ([-1, 1])'); + ylabel('Quaternion'); +elseif ~isempty(gyroCols) + plot(t, data(:, gyroCols)); + ylim([-100, 100]); + legend(labels(gyroCols), 'Location', 'eastoutside'); + title('Gyroscope ([-100, 100] dps)'); + ylabel('dps'); +end + +subplot(3, 1, 2); +if ~isempty(accCols) + plot(t, data(:, accCols)); + ylim([-4, 4]); + legend(labels(accCols), 'Location', 'eastoutside'); + title('Accelerometer ([-4, 4] g)'); + ylabel('g'); +end + +subplot(3, 1, 3); +if ~isempty(magCols) + plot(t, data(:, magCols)); + ylim([-4900, 4900]); + legend(labels(magCols), 'Location', 'eastoutside'); + title('Magnetometer ([-4900, 4900] uT)'); + ylabel('uT'); + xlabel('Seconds'); +end +end + +function plotPm(fig, labels, data, time) +% plotPm Plot normalized Performance Metrics (met) in the [0, 1] range. +figure(fig); +metricCols = find(cellfun(@isempty, regexp(labels, '\.isActive$'))); +if isempty(metricCols), return; end + +t = time - time(end); +plot(t, data(:, metricCols), '-o'); +ylim([0, 1]); +legend(labels(metricCols), 'Location', 'eastoutside'); +title('Performance Metrics ([0, 1])'); +xlabel('Seconds'); +ylabel('Normalized Score'); +end diff --git a/octave/functions/cortexConnect.m b/octave/functions/cortexConnect.m new file mode 100644 index 0000000..be15fcd --- /dev/null +++ b/octave/functions/cortexConnect.m @@ -0,0 +1,47 @@ +function cortex = cortexConnect() +% cortexConnect Connect to Cortex over WSS and authorize this app. +% cortex = cortexConnect() loads clientId, clientSecret and the optional port (default 6868) +% from config/config.json +% and returns a struct with the fields: +% isConnected true when the Cortex link is open and the app is authorized +% token cortexToken to use in later Cortex requests ('' on failure) +% userInfo user details returned by Cortex ([] on failure) +% licenseInfo license details returned by Cortex ([] on failure) +% manager internal handle used by cortexDisconnect; do not modify +% isSubscribed, headsetId, sessionId, streams filled in by cortexSubscribe + +functionsDir = fileparts(mfilename('fullpath')); +addpath(fullfile(functionsDir, '..', 'internal')); + +[clientId, clientSecret, port] = cortexCredentials(); + +cortex = struct('isConnected', false, 'token', '', 'userInfo', [], 'licenseInfo', [], 'manager', [], ... + 'isSubscribed', false, 'headsetId', '', 'sessionId', '', 'streams', {{}}); +manager = CortexManager(clientId, clientSecret, 'localhost', port); +cortex.manager = manager; + +try + fprintf('[cortexConnect] Connecting to Cortex at wss://%s:%d...\n', manager.host, manager.port); + try + auth = manager.getAuth(); + catch connectFailure + fprintf(['Could not connect to Cortex at wss://%s:%d. ' ... + 'Make sure EMOTIV Launcher is running.\n'], manager.host, manager.port); + rethrow(connectFailure); + end + + fprintf('[cortexConnect] Checking user login and access right...\n'); + auth.init(); + auth.getUserInformation(); + auth.getLicenseInfo(); + + context = manager.getContext(); + cortex.token = context.token; + cortex.userInfo = context.userInfo; + cortex.licenseInfo = context.licenseInfo; + cortex.isConnected = true; + fprintf('[cortexConnect] Connected and authorized.\n'); +catch failure + fprintf('[cortexConnect] ERROR %s: %s\n', failure.identifier, failure.message); +end +end diff --git a/octave/functions/cortexDisconnect.m b/octave/functions/cortexDisconnect.m new file mode 100644 index 0000000..1c1c121 --- /dev/null +++ b/octave/functions/cortexDisconnect.m @@ -0,0 +1,19 @@ +function cortex = cortexDisconnect(cortex) +% cortexDisconnect Close the Cortex connection opened by cortexConnect. +% cortex = cortexDisconnect(cortex) is safe to call even if cortexConnect failed. + +if isstruct(cortex) && isfield(cortex, 'manager') && ~isempty(cortex.manager) + fprintf('[cortexDisconnect] Closing Cortex connection...\n'); + cortex.manager.close(); + cortex.manager = []; +end + +cortex.isConnected = false; +cortex.isSubscribed = false; +cortex.headsetId = ''; +cortex.sessionId = ''; +cortex.streams = {}; +cortex.token = ''; +cortex.userInfo = []; +cortex.licenseInfo = []; +end diff --git a/octave/functions/cortexGetData.m b/octave/functions/cortexGetData.m new file mode 100644 index 0000000..0564d42 --- /dev/null +++ b/octave/functions/cortexGetData.m @@ -0,0 +1,27 @@ +function [labels, data, time] = cortexGetData(cortex, stream, lastN) +% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow or met). +% [labels, data, time] = cortexGetData(cortex, 'eeg', 256) first collects the data that has +% arrived (this can take up to about 1 second), then returns the newest 256 samples: +% labels cell array with one name per column of data +% data samples-by-columns matrix, oldest sample first (NaN where a value is empty) +% time sample times in seconds +% Omit lastN to get everything in the buffer (the last 10000 samples per stream). + +if nargin < 3, lastN = []; end +labels = {}; +data = []; +time = []; + +if ~isstruct(cortex) || ~isfield(cortex, 'isSubscribed') || ~cortex.isSubscribed + fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); + return; +end + +headset = cortex.manager.getHeadset(); +headset.update(); +if ~headset.isSubscribed + fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); + return; +end +[labels, data, time] = cortex.manager.getContext().buffer.read(stream, lastN); +end diff --git a/octave/functions/cortexSubscribe.m b/octave/functions/cortexSubscribe.m new file mode 100644 index 0000000..4d70173 --- /dev/null +++ b/octave/functions/cortexSubscribe.m @@ -0,0 +1,62 @@ +function cortex = cortexSubscribe(cortex, headsetId, streams, varargin) +% cortexSubscribe Scan for a headset, connect it, open a session and subscribe to data streams. +% cortex = cortexSubscribe(cortex, 'INSIGHT-XXXXXXXX', {'eeg','mot','dev','eq','pow','met'}) +% updates the fields: +% isSubscribed true when the streams are being received +% headsetId the connected headset +% sessionId the Cortex session id +% streams the subscribed stream names +% Optional name/value pairs: +% 'autoRescan' rescan automatically when a scan finishes (default true) +% 'queryInterval' seconds between headset list queries (default 3) +% 'scanTimeout' seconds to wait for the headset to appear (default 30) +% Read the samples with cortexGetData. + +options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30); +for index = 1:2:numel(varargin) - 1 + if ~isfield(options, varargin{index}) + fprintf('[cortexSubscribe] ERROR Unknown option "%s".\n', varargin{index}); + return; + end + options.(varargin{index}) = varargin{index + 1}; +end + +if ~cortex.isConnected + fprintf('[cortexSubscribe] ERROR Call cortexConnect successfully first.\n'); + return; +end +if ischar(streams), streams = {streams}; end +validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met'}; +if ~iscellstr(streams) || isempty(streams) || ~all(ismember(streams, validStreams)) + fprintf('[cortexSubscribe] ERROR streams must be a non-empty list of: %s.\n', strjoin(validStreams, ', ')); + return; +end + +cortex.isSubscribed = false; +try + headset = cortex.manager.getHeadset(); + headset.scanHeadset(options.autoRescan, options.queryInterval); + + if ~headset.waitForHeadset(headsetId, options.scanTimeout) + fprintf(['[cortexSubscribe] Headset %s was not found within %g seconds. ' ... + 'Check that it is switched on and in range.\n'], headsetId, options.scanTimeout); + headset.stopScan(); + return; + end + + [ok, message] = headset.connectToHeadset(headsetId, streams); + if ~ok + fprintf('[cortexSubscribe] ERROR %s\n', message); + return; + end + + context = cortex.manager.getContext(); + cortex.headsetId = context.headsetId; + cortex.sessionId = context.sessionId; + cortex.streams = context.subscribedStreams; + cortex.isSubscribed = true; + fprintf('[cortexSubscribe] Receiving data from %s.\n', headsetId); +catch failure + fprintf('[cortexSubscribe] ERROR %s: %s\n', failure.identifier, failure.message); +end +end diff --git a/octave/internal/CortexAuth.m b/octave/internal/CortexAuth.m new file mode 100644 index 0000000..632f860 --- /dev/null +++ b/octave/internal/CortexAuth.m @@ -0,0 +1,159 @@ +classdef CortexAuth < handle + % CortexAuth Opens the Cortex WSS connection, checks login/access rights and holds the cortexToken. + + properties + license = '' + debit = 100 + end + + properties (SetAccess = private) + isUserLoggedIn = false + isAccessGranted = false + end + + properties + accessWaitTimeout = 180 + end + + properties (Access = private) + client + clientId + clientSecret + context + end + + methods + function obj = CortexAuth(clientId, clientSecret, host, port, context) + if nargin < 3, host = 'localhost'; end + if nargin < 4, port = 6868; end + if nargin < 5, context = CortexContext(); end + obj.clientId = clientId; + obj.clientSecret = clientSecret; + obj.context = context; + obj.client = CortexClient(host, port); + obj.client.onWarning(2, @(warning) obj.handleWarning(warning)); + obj.client.onWarning(3, @(warning) obj.handleWarning(warning)); + obj.client.onWarning(9, @(warning) obj.handleWarning(warning)); + end + + function init(obj) + % Verifies a user is logged in to EMOTIV Launcher and that this app has access. + logins = obj.getUserLogin(); + if isempty(logins) + error('CortexAuth:noUser', 'No user is logged in. Log in via EMOTIV Launcher and run again.'); + end + + if ~obj.hasAccessRight() + fprintf('[CortexAuth] Application access is not granted. Requesting approval from Cortex...\n'); + if ~obj.requestAccess() + fprintf(['[CortexAuth] Application access is not granted yet.\n' ... + '[CortexAuth] Open EMOTIV Launcher, sign in, and approve this application.\n' ... + '[CortexAuth] Waiting for approval for up to %d seconds...\n'], obj.accessWaitTimeout); + grantedWarning = obj.client.waitForWarning(9, obj.accessWaitTimeout); + if isempty(grantedWarning) + error('CortexAuth:accessDenied', ... + ['Application access was not approved within %d seconds. ' ... + 'Open EMOTIV Launcher, approve the application, and try again.'], ... + obj.accessWaitTimeout); + end + end + end + + if isempty(obj.context.token) + fprintf('[CortexAuth] Application access confirmed. Authorizing...\n'); + obj.authorize(); + end + end + + function logins = getUserLogin(obj) + response = obj.client.sendRequest('getUserLogin', struct()); + logins = response.result; + obj.isUserLoggedIn = ~isempty(logins); + end + + function granted = hasAccessRight(obj) + response = obj.client.sendRequest('hasAccessRight', obj.credentialParams()); + granted = isfield(response.result, 'accessGranted') && logical(response.result.accessGranted); + obj.isAccessGranted = granted; + end + + function granted = requestAccess(obj) + response = obj.client.sendRequest('requestAccess', obj.credentialParams()); + granted = isfield(response.result, 'accessGranted') && logical(response.result.accessGranted); + obj.isAccessGranted = granted; + end + + function token = authorize(obj) + params = obj.credentialParams(); + params.license = obj.license; + params.debit = obj.debit; + response = obj.client.sendRequest('authorize', params); + obj.context.token = response.result.cortexToken; + token = obj.context.token; + end + + function userInfo = getUserInformation(obj) + if isempty(obj.context.token) + error('CortexAuth:notAuthorized', 'Authorize before requesting user information.'); + end + + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('getUserInformation', params); + obj.context.userInfo = response.result; + userInfo = obj.context.userInfo; + end + + function licenseInfo = getLicenseInfo(obj) + if isempty(obj.context.token) + error('CortexAuth:notAuthorized', 'Authorize before requesting license information.'); + end + + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('getLicenseInfo', params); + if ~isfield(response.result, 'license') + error('CortexAuth:licenseInfo', 'Cortex returned no license information.'); + end + obj.context.licenseInfo = response.result.license; + licenseInfo = obj.context.licenseInfo; + end + + function client = getClient(obj) + client = obj.client; + end + + function context = getContext(obj) + context = obj.context; + end + + function close(obj) + obj.client.close(); + end + end + + methods (Access = private) + function handleWarning(obj, warning) + switch warning.code + case 2 + obj.isUserLoggedIn = true; + description = 'User logged in.'; + case 3 + obj.isUserLoggedIn = false; + obj.isAccessGranted = false; + obj.context.token = ''; + obj.context.userInfo = []; + obj.context.licenseInfo = []; + description = 'User logged out.'; + case 9 + obj.isAccessGranted = true; + description = 'Application access approved.'; + otherwise + description = 'Unhandled authentication warning.'; + end + fprintf('[CortexAuth] Warning %d: %s\n', warning.code, description); + end + + function params = credentialParams(obj) + params = struct('clientId', obj.clientId, 'clientSecret', obj.clientSecret); + end + end +end diff --git a/octave/internal/CortexClient.m b/octave/internal/CortexClient.m new file mode 100644 index 0000000..c3f3279 --- /dev/null +++ b/octave/internal/CortexClient.m @@ -0,0 +1,320 @@ +classdef CortexClient < handle + % CortexClient JSON-RPC client that connects straight to Cortex over WSS. + % Works in GNU Octave (with Java) and MATLAB via lib/cortex-ws-client.jar (nv-websocket-client). + + properties (Access = private) + ws + nextId = 1 + pendingResponses = {} + streamMessages = {} + warningMessages = {} + warningHandlers = {} + end + + properties (SetAccess = private) + lastWarning = [] + end + + properties + requestTimeout = 60 + end + + methods + function obj = CortexClient(host, port, requestTimeout) + if nargin < 1, host = 'localhost'; end + if nargin < 2, port = 6868; end + if nargin < 3, requestTimeout = 60; end + + obj.requestTimeout = requestTimeout; + obj.validateRequestTimeout(); + + internalDir = fileparts(mfilename('fullpath')); + libDir = fullfile(internalDir, '..', 'lib'); + CortexClient.addJars(libDir); + caPath = fullfile(internalDir, '..', '..', 'certificates', 'rootCA.pem'); + if ~exist(caPath, 'file') + error('CortexClient:certificate', ... + 'Required Cortex CA certificate not found: %s', caPath); + end + + url = sprintf('wss://%s:%d', host, port); + obj.ws = javaObject('cortex.CortexWsClient'); + obj.ws.connect(url, caPath, int32(10000)); + end + + function response = sendRequest(obj, method, params) + if nargin < 3, params = struct(); end + + obj.validateRequestTimeout(); + requestStartedAt = tic(); + id = obj.nextId; + obj.nextId = id + 1; + request = struct('jsonrpc', '2.0', 'id', id, 'method', method, 'params', params); + obj.ws.sendText(jsonencode(request)); + + queued = obj.takeResponse(id, method); + if ~isempty(queued) + response = queued; + return; + end + + while true + obj.checkRequestDeadline(requestStartedAt, method); + [messageType, msg] = obj.readMessage(); + obj.checkRequestDeadline(requestStartedAt, method); + if strcmp(messageType, 'timeout'), continue; end + + switch messageType + case 'result' + if obj.hasResponseId(msg, id) + response = msg; + return; + end + obj.pendingResponses{end + 1} = msg; + case 'error' + if obj.hasResponseId(msg, id) + obj.raiseRpcError(method, msg.error); + end + obj.pendingResponses{end + 1} = msg; + case 'warning' + obj.handleWarning(msg.warning); + case 'stream' + obj.streamMessages{end + 1} = msg; + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + end + + function line = readLine(obj) + % Returns '' when no data arrives within the 1 s socket timeout. + line = obj.readSocketLine(); + end + + function stream = readStreamData(obj) + if ~isempty(obj.streamMessages) + stream = obj.streamMessages{1}; + obj.streamMessages(1) = []; + return; + end + + while true + [messageType, msg] = obj.readMessage(); + if strcmp(messageType, 'timeout') + stream = []; + return; + end + + switch messageType + case 'stream' + stream = msg; + return; + case 'warning' + obj.handleWarning(msg.warning); + case 'result' + obj.pendingResponses{end + 1} = msg; + case 'error' + obj.raiseRpcError('unsolicited message', msg.error); + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + end + + function onWarning(obj, warningCode, handler) + if ~isnumeric(warningCode) || ~isscalar(warningCode) + error('CortexClient:warningHandler', 'Warning code must be a numeric scalar.'); + end + if ~isa(handler, 'function_handle') + error('CortexClient:warningHandler', 'Warning handler must be a function handle.'); + end + + registration = struct('code', warningCode, 'handler', handler); + obj.warningHandlers{end + 1} = registration; + end + + function warning = waitForWarning(obj, warningCode, timeoutSeconds) + if nargin < 3, timeoutSeconds = 60; end + if ~isnumeric(warningCode) || ~isscalar(warningCode) + error('CortexClient:warningWait', 'Warning code must be a numeric scalar.'); + end + if ~isnumeric(timeoutSeconds) || ~isscalar(timeoutSeconds) || timeoutSeconds < 0 + error('CortexClient:warningWait', 'Timeout must be a non-negative numeric scalar.'); + end + + warning = obj.takeWarning(warningCode); + if ~isempty(warning), return; end + + startedAt = tic(); + while toc(startedAt) < timeoutSeconds + [messageType, msg] = obj.readMessage(); + if strcmp(messageType, 'timeout'), continue; end + + switch messageType + case 'warning' + obj.handleWarning(msg.warning); + warning = obj.takeWarning(warningCode); + if ~isempty(warning), return; end + case 'stream' + obj.streamMessages{end + 1} = msg; + case 'result' + obj.pendingResponses{end + 1} = msg; + case 'error' + obj.raiseRpcError('unsolicited message', msg.error); + otherwise + error('CortexClient:message', 'Unsupported Cortex message type: %s', messageType); + end + end + warning = []; + end + + function close(obj) + if isempty(obj.ws), return; end + try + obj.ws.close(); + catch + end + obj.ws = []; + end + end + + methods (Static, Access = private) + function addJars(libDir) + loaded = javaclasspath('-all'); + [status, libInfo] = fileattrib(libDir); + if status + libDir = libInfo.Name; + end + for jarName = {'nv-websocket-client-2.14.jar', 'cortex-ws-client.jar'} + jarPath = fullfile(libDir, jarName{1}); + if ~exist(jarPath, 'file') + error('CortexClient:jar', 'Missing %s. Restore the lib folder from the repository.', jarPath); + end + if ~any(strcmp(loaded, jarPath)) + javaaddpath(jarPath); + end + end + end + end + + methods (Access = private) + function validateRequestTimeout(obj) + if ~isnumeric(obj.requestTimeout) || ~isscalar(obj.requestTimeout) || ... + ~isfinite(obj.requestTimeout) || obj.requestTimeout <= 0 + error('CortexClient:requestTimeoutConfig', ... + 'requestTimeout must be a finite, positive numeric scalar.'); + end + end + + function checkRequestDeadline(obj, requestStartedAt, method) + if toc(requestStartedAt) >= obj.requestTimeout + error('CortexClient:requestTimeout', ... + 'Timed out waiting for a response to "%s" after %.3g seconds.', ... + method, obj.requestTimeout); + end + end + + function [messageType, msg] = readMessage(obj) + line = obj.readSocketLine(); + if isempty(line) + messageType = 'timeout'; + msg = []; + return; + end + + msg = jsondecode(line); + messageType = obj.classifyMessage(msg); + end + + function messageType = classifyMessage(obj, msg) + if ~isstruct(msg) + error('CortexClient:message', 'Cortex returned a non-object JSON message.'); + elseif isfield(msg, 'sid') + messageType = 'stream'; + elseif isfield(msg, 'result') + messageType = 'result'; + elseif isfield(msg, 'error') + messageType = 'error'; + elseif isfield(msg, 'warning') + messageType = 'warning'; + else + error('CortexClient:message', 'Cortex returned an object with no sid, result, error, or warning field.'); + end + end + + function matched = hasResponseId(obj, msg, requestId) + matched = isfield(msg, 'id') && isequal(msg.id, requestId); + end + + function response = takeResponse(obj, requestId, method) + response = []; + for index = 1:numel(obj.pendingResponses) + candidate = obj.pendingResponses{index}; + if obj.hasResponseId(candidate, requestId) + response = candidate; + obj.pendingResponses(index) = []; + if strcmp(obj.classifyMessage(candidate), 'error') + obj.raiseRpcError(method, candidate.error); + end + return; + end + end + end + + function warning = takeWarning(obj, warningCode) + warning = []; + for index = 1:numel(obj.warningMessages) + candidate = obj.warningMessages{index}; + if isequal(candidate.code, warningCode) + warning = candidate; + obj.warningMessages(index) = []; + return; + end + end + end + + function raiseRpcError(obj, method, rpcError) + code = 'unknown'; + message = jsonencode(rpcError); + if isstruct(rpcError) + if isfield(rpcError, 'code') + code = num2str(rpcError.code); + end + if isfield(rpcError, 'message') + message = char(rpcError.message); + end + end + error('CortexClient:rpc', '%s failed (code %s): %s', method, code, message); + end + + function handleWarning(obj, warning) + if ~isstruct(warning) || ~isfield(warning, 'code') + error('CortexClient:warning', 'Cortex returned an invalid warning object.'); + end + + obj.lastWarning = warning; + obj.warningMessages{end + 1} = warning; + + for index = 1:numel(obj.warningHandlers) + registration = obj.warningHandlers{index}; + if isequal(registration.code, warning.code) + registration.handler(warning); + end + end + end + + function line = readSocketLine(obj) + % Java returns null (empty in Octave) on timeout; a closed link throws. + try + line = obj.ws.poll(int32(1000)); + catch err + error('CortexClient:closed', 'Connection to Cortex closed: %s', err.message); + end + if isempty(line) + line = ''; + else + line = char(line); + end + end + end +end diff --git a/octave/internal/CortexContext.m b/octave/internal/CortexContext.m new file mode 100644 index 0000000..3324c31 --- /dev/null +++ b/octave/internal/CortexContext.m @@ -0,0 +1,16 @@ +classdef CortexContext < handle + % CortexContext Shared authentication data for one Cortex connection. + + properties + token = '' + userInfo = [] + licenseInfo = [] + + headsets = {} % cell array of headset structs from the last queryHeadsets + headsetId = '' + sessionId = '' + subscribedStreams = {} + streamLabels = struct() % one field per stream, each a cell array of column labels + buffer = [] % CortexDataBuffer holding the received samples + end +end diff --git a/octave/internal/CortexDataBuffer.m b/octave/internal/CortexDataBuffer.m new file mode 100644 index 0000000..ccb57c2 --- /dev/null +++ b/octave/internal/CortexDataBuffer.m @@ -0,0 +1,104 @@ +classdef CortexDataBuffer < handle + % CortexDataBuffer Fixed-size ring buffer that keeps the latest samples of each data stream. + % Rows are samples (oldest first when read) and columns follow the stream labels. + + properties (SetAccess = private) + capacity + end + + properties (Access = private) + names = {} + labels = {} + samples = {} + times = {} + nextRow = [] + count = [] + end + + methods + function obj = CortexDataBuffer(capacity) + if nargin < 1, capacity = 10000; end + if ~isnumeric(capacity) || ~isscalar(capacity) || capacity < 1 + error('CortexDataBuffer:capacity', 'Capacity must be a positive numeric scalar.'); + end + obj.capacity = floor(capacity); + end + + function configure(obj, stream, labels) + % Resets one stream and stores its column labels. + idx = obj.indexOf(stream); + obj.labels{idx} = labels; + obj.samples{idx} = []; + obj.times{idx} = []; + obj.nextRow(idx) = 1; + obj.count(idx) = 0; + end + + function append(obj, stream, row, time) + idx = obj.indexOf(stream); + width = numel(row); + if isempty(obj.samples{idx}) + obj.samples{idx} = NaN(obj.capacity, width); + obj.times{idx} = NaN(obj.capacity, 1); + end + + columns = size(obj.samples{idx}, 2); + if width < columns + row(end + 1:columns) = NaN; + elseif width > columns + row = row(1:columns); + end + + r = obj.nextRow(idx); + obj.samples{idx}(r, :) = row; + obj.times{idx}(r) = time; + obj.nextRow(idx) = mod(r, obj.capacity) + 1; + obj.count(idx) = min(obj.count(idx) + 1, obj.capacity); + end + + function [labels, data, time] = read(obj, stream, lastN) + % Returns the newest lastN samples (all buffered samples when lastN is omitted). + labels = {}; + data = []; + time = []; + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx), return; end + + labels = obj.labels{idx}; + n = obj.count(idx); + if nargin >= 3 && ~isempty(lastN) + n = min(n, lastN); + end + if n == 0, return; end + + newest = mod(obj.nextRow(idx) - 2, obj.capacity) + 1; + rows = mod((newest - n + 1:newest) - 1, obj.capacity) + 1; + data = obj.samples{idx}(rows, :); + time = obj.times{idx}(rows); + end + + function n = numSamples(obj, stream) + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx) + n = 0; + else + n = obj.count(idx); + end + end + end + + methods (Access = private) + function idx = indexOf(obj, stream) + idx = find(strcmp(obj.names, stream), 1); + if isempty(idx) + idx = numel(obj.names) + 1; + obj.names{idx} = stream; + obj.labels{idx} = {}; + obj.samples{idx} = []; + obj.times{idx} = []; + obj.nextRow(idx) = 1; + obj.count(idx) = 0; + end + end + end +end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m new file mode 100644 index 0000000..4b8811b --- /dev/null +++ b/octave/internal/CortexHeadset.m @@ -0,0 +1,280 @@ +classdef CortexHeadset < handle + % CortexHeadset Scans for headsets, connects one, opens a session and subscribes to data streams. + % The client is single-threaded, so the scan "timer" runs inside update(), which also reads + % the incoming data samples into the context buffer. + + properties + connectTimeout = 5 % seconds to wait for warning 104 (headset connected) + end + + properties (SetAccess = private) + isScanning = false + isSubscribed = false + autoRescan = true + queryInterval = 3 + end + + properties (Access = private) + client + context + scanFinished = false + lastQueryAt = [] + parser + end + + methods + function obj = CortexHeadset(client, context) + obj.client = client; + obj.context = context; + obj.parser = CortexStreamParser(); + if isempty(context.buffer) + context.buffer = CortexDataBuffer(10000); + end + obj.client.onWarning(1, @(warning) obj.onSessionClosed(warning)); + obj.client.onWarning(142, @(warning) obj.onScanFinished(warning)); + end + + function scanHeadset(obj, autoRescan, queryInterval) + % Starts a scan and queries the headset list every queryInterval seconds (see update()). + if nargin < 2, autoRescan = true; end + if nargin < 3, queryInterval = 3; end + if ~(islogical(autoRescan) || isnumeric(autoRescan)) || ~isscalar(autoRescan) + error('CortexHeadset:scanOptions', 'autoRescan must be true or false.'); + end + if ~isnumeric(queryInterval) || ~isscalar(queryInterval) || queryInterval <= 0 + error('CortexHeadset:scanOptions', 'queryInterval must be a positive number of seconds.'); + end + + obj.autoRescan = logical(autoRescan); + obj.queryInterval = double(queryInterval); + fprintf('[CortexHeadset] Scanning for headsets...\n'); + obj.refreshHeadsets(); + obj.isScanning = true; + obj.queryHeadsets(); + end + + function stopScan(obj) + obj.isScanning = false; + end + + function headsets = queryHeadsets(obj) + response = obj.client.sendRequest('queryHeadsets', struct()); + obj.context.headsets = CortexHeadset.toCell(response.result); + obj.lastQueryAt = tic(); + headsets = obj.context.headsets; + if isempty(headsets) + fprintf('[CortexHeadset] No headsets found.\n'); + else + fprintf('[CortexHeadset] Headsets (id | status):\n'); + for index = 1:numel(headsets) + fprintf(' %s | %s\n', CortexHeadset.textField(headsets{index}, 'id'), ... + CortexHeadset.textField(headsets{index}, 'status')); + end + end + end + + function headset = findHeadset(obj, headsetId) + headset = []; + for index = 1:numel(obj.context.headsets) + candidate = obj.context.headsets{index}; + if isfield(candidate, 'id') && strcmp(candidate.id, headsetId) + headset = candidate; + return; + end + end + end + + function found = waitForHeadset(obj, headsetId, timeoutSeconds) + % Keeps scanning until headsetId shows up in the list or the timeout expires. + startedAt = tic(); + found = false; + while true + if ~isempty(obj.findHeadset(headsetId)) + found = true; + return; + end + if toc(startedAt) >= timeoutSeconds, return; end + obj.update(0.5); + end + end + + function [ok, message] = connectToHeadset(obj, headsetId, streams) + % Connects the headset if needed, creates an active session, then subscribes to streams. + if nargin < 3, streams = {}; end + ok = false; + message = ''; + + try + headset = obj.findHeadset(headsetId); + if isempty(headset) + message = sprintf('Headset %s is not in the scanned headset list.', headsetId); + return; + end + + if ~strcmp(headset.status, 'connected') + if ~strcmp(headset.status, 'connecting') + fprintf('[CortexHeadset] Connecting to %s...\n', headsetId); + obj.client.sendRequest('controlDevice', ... + struct('command', 'connect', 'headset', headsetId)); + end + if isempty(obj.client.waitForWarning(104, obj.connectTimeout)) + message = sprintf(['Connection to %s was not successful: warning 104 ' ... + '(headset connected) was not received within %g seconds.'], ... + headsetId, obj.connectTimeout); + return; + end + end + + obj.isScanning = false; + obj.createSession(headsetId); + if ~isempty(streams) + obj.subscribe(streams); + end + ok = true; + catch failure + message = failure.message; + end + end + + function sessionId = createSession(obj, headsetId) + fprintf('[CortexHeadset] Creating an active session for %s...\n', headsetId); + params = struct('cortexToken', obj.context.token, 'status', 'active', 'headset', headsetId); + response = obj.client.sendRequest('createSession', params); + sessionId = response.result.id; + obj.context.sessionId = sessionId; + obj.context.headsetId = headsetId; + end + + function subscribe(obj, streams) + if isempty(obj.context.sessionId) + error('CortexHeadset:noSession', 'Create a session before subscribing.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'streams', {streams}); + response = obj.client.sendRequest('subscribe', params); + + failures = CortexHeadset.toCell(response.result.failure); + for index = 1:numel(failures) + item = failures{index}; + fprintf('[CortexHeadset] Subscribe failed for %s (code %s): %s\n', ... + CortexHeadset.textField(item, 'streamName'), ... + CortexHeadset.textField(item, 'code'), CortexHeadset.textField(item, 'message')); + end + + successes = CortexHeadset.toCell(response.result.success); + for index = 1:numel(successes) + item = successes{index}; + name = item.streamName; + labels = CortexStreamParser.flattenLabels(item.cols); + obj.parser.register(item.sid, name); + obj.context.streamLabels.(name) = labels; + obj.context.subscribedStreams{end + 1} = name; + obj.context.buffer.configure(name, labels); + fprintf('[CortexHeadset] Subscribed to %s (%d columns).\n', name, numel(labels)); + end + obj.isSubscribed = ~isempty(successes); + if ~obj.isSubscribed + error('CortexHeadset:subscribe', 'Cortex did not accept any data stream.'); + end + end + + function unsubscribe(obj) + if ~obj.isSubscribed, return; end + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'streams', {obj.context.subscribedStreams}); + obj.isSubscribed = false; + obj.parser.reset(); + obj.context.subscribedStreams = {}; + obj.client.sendRequest('unsubscribe', params); + end + + function update(obj, maxSeconds) + % Reads incoming messages into the buffer for about maxSeconds, then runs the scan timer. + % It can block up to 1 s when no data is arriving. + if nargin < 2, maxSeconds = 0.25; end + startedAt = tic(); + while true + stream = obj.client.readStreamData(); + if isempty(stream), break; end + obj.storeSample(stream); + if toc(startedAt) >= maxSeconds, break; end + end + obj.runScanTimer(); + end + end + + methods (Access = private) + function refreshHeadsets(obj) + % Cortex answers with warning 142 when the scan finishes. + obj.scanFinished = false; + obj.client.sendRequest('controlDevice', struct('command', 'refresh')); + end + + function onScanFinished(obj, warning) + obj.scanFinished = true; + if ~obj.autoRescan + fprintf(['[CortexHeadset] Headset scan finished (warning 142). ' ... + 'Call scanHeadset again to rescan.\n']); + end + end + + function onSessionClosed(obj, warning) + if ~isfield(warning, 'message') || ~isstruct(warning.message) || ... + ~isfield(warning.message, 'sessionId') || ... + ~strcmp(warning.message.sessionId, obj.context.sessionId) + return; + end + + obj.isScanning = false; + obj.isSubscribed = false; + obj.context.sessionId = ''; + obj.context.headsetId = ''; + obj.context.subscribedStreams = {}; + obj.parser.reset(); + fprintf('[CortexHeadset] Session %s was closed by Cortex.\n', warning.message.sessionId); + end + + function runScanTimer(obj) + if ~obj.isScanning, return; end + if obj.autoRescan && obj.scanFinished + obj.refreshHeadsets(); + end + if isempty(obj.lastQueryAt) || toc(obj.lastQueryAt) >= obj.queryInterval + obj.queryHeadsets(); + end + end + + function storeSample(obj, msg) + [stream, row, time] = obj.parser.parse(msg); + if isempty(stream), return; end + obj.context.buffer.append(stream, row, time); + end + end + + methods (Static, Access = private) + function items = toCell(value) + % jsondecode returns a struct array or a cell array depending on the content. + if isempty(value) + items = {}; + elseif iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + else + items = {value}; + end + end + end + + methods (Static, Access = private) + function text = textField(item, name) + text = '?'; + if isstruct(item) && isfield(item, name) + value = item.(name); + if isnumeric(value), value = num2str(value); end + text = char(value); + end + end + end +end diff --git a/octave/internal/CortexManager.m b/octave/internal/CortexManager.m new file mode 100644 index 0000000..5ae25d3 --- /dev/null +++ b/octave/internal/CortexManager.m @@ -0,0 +1,72 @@ +classdef CortexManager < handle + % CortexManager Owns the Cortex objects and creates each one lazily on first use. + % The TCP connection (CortexClient) is opened by CortexAuth, so nothing connects until getAuth(). + + properties (SetAccess = private) + host + port + clientId + clientSecret + context + end + + properties (Access = private) + auth = [] + headset = [] + end + + methods + function obj = CortexManager(clientId, clientSecret, host, port) + if nargin < 2 + [clientId, clientSecret, configPort] = cortexCredentials(); + else + configPort = 6868; + end + if nargin < 3, host = 'localhost'; end + if nargin < 4, port = configPort; end + obj.clientId = clientId; + obj.clientSecret = clientSecret; + obj.host = host; + obj.port = port; + obj.context = CortexContext(); + end + + function auth = getAuth(obj) + if isempty(obj.auth) + obj.auth = CortexAuth(obj.clientId, obj.clientSecret, obj.host, obj.port, obj.context); + end + auth = obj.auth; + end + + function context = getContext(obj) + context = obj.context; + end + + function client = getClient(obj) + client = obj.getAuth().getClient(); + end + + function headset = getHeadset(obj) + if isempty(obj.headset) + obj.headset = CortexHeadset(obj.getClient(), obj.context); + end + headset = obj.headset; + end + + % Future getRecord/getBCI follow the getAuth pattern: create lazily with getClient() and getAuth(). + + function close(obj) + % Only closes what was actually created. + if ~isempty(obj.headset) + try + obj.headset.unsubscribe(); + catch + end + obj.headset = []; + end + if ~isempty(obj.auth) + obj.auth.close(); + end + end + end +end diff --git a/octave/internal/CortexStreamParser.m b/octave/internal/CortexStreamParser.m new file mode 100644 index 0000000..2804cd7 --- /dev/null +++ b/octave/internal/CortexStreamParser.m @@ -0,0 +1,77 @@ +classdef CortexStreamParser < handle + % CortexStreamParser Turns decoded Cortex subscribe/stream messages into labels and numeric rows. + % It maps each subscription id (sid) to its stream name; storage is left to CortexDataBuffer. + + properties (Access = private) + sids = {} + streams = {} + end + + methods + function register(obj, sid, streamName) + obj.sids{end + 1} = sid; + obj.streams{end + 1} = streamName; + end + + function reset(obj) + obj.sids = {}; + obj.streams = {}; + end + + function [stream, row, time] = parse(obj, msg) + % stream is '' when the message does not belong to a registered stream. + stream = ''; + row = []; + time = NaN; + if isfield(msg, 'sid') && ischar(msg.sid) + index = find(strcmp(obj.sids, msg.sid), 1); + if ~isempty(index), stream = obj.streams{index}; end + end + if isempty(stream) || ~isfield(msg, stream) + stream = ''; + return; + end + + if isfield(msg, 'time') && isnumeric(msg.time) && ~isempty(msg.time) + time = double(msg.time); + end + row = CortexStreamParser.flattenSample(msg.(stream)); + end + end + + methods (Static) + function labels = flattenLabels(cols) + % The dev stream nests the contact-quality labels in a sub-array. + if ischar(cols) + labels = {cols}; + elseif iscell(cols) + labels = {}; + for index = 1:numel(cols) + labels = [labels, CortexStreamParser.flattenLabels(cols{index})]; %#ok + end + else + labels = {}; + end + end + + function row = flattenSample(values) + % Empty entries (null, no markers) become NaN so every row keeps the same width. + % jsondecode returns numeric, logical or cell values depending on the tool and content. + if isnumeric(values) || islogical(values) + if isempty(values) + row = NaN; + else + row = double(values(:))'; + end + elseif iscell(values) + row = []; + for index = 1:numel(values) + row = [row, CortexStreamParser.flattenSample(values{index})]; %#ok + end + if isempty(row), row = NaN; end + else + row = NaN; + end + end + end +end diff --git a/octave/internal/cortexCredentials.m b/octave/internal/cortexCredentials.m new file mode 100644 index 0000000..e12d63b --- /dev/null +++ b/octave/internal/cortexCredentials.m @@ -0,0 +1,32 @@ +function [clientId, clientSecret, port] = cortexCredentials() +% cortexCredentials Load clientId, clientSecret and the optional port from config/config.json. +% port defaults to 6868 (production) when config.json has no "port" field. +% Internal: the dev environment uses port 7070; set "port": 7070 in config.json. + +configFile = fullfile(fileparts(mfilename('fullpath')), '..', 'config', 'config.json'); +if ~exist(configFile, 'file') + error('cortexCredentials:configNotFound', ... + ['Config file not found: %s. ' ... + 'Copy octave/config/config.example.json to octave/config/config.json ' ... + 'and set your clientId and clientSecret.'], configFile); +end + +config = jsondecode(fileread(configFile)); +if ~isfield(config, 'clientId') || ~isfield(config, 'clientSecret') || ... + isempty(config.clientId) || isempty(config.clientSecret) + error('cortexCredentials:invalidConfig', ... + 'octave/config/config.json must contain non-empty clientId and clientSecret fields.'); +end + +clientId = config.clientId; +clientSecret = config.clientSecret; + +port = 6868; +if isfield(config, 'port') && ~isempty(config.port) + port = config.port; + if ~isnumeric(port) || ~isscalar(port) || ~isfinite(port) || port ~= fix(port) || port < 1 || port > 65535 + error('cortexCredentials:invalidConfig', ... + 'octave/config/config.json "port" must be an integer between 1 and 65535.'); + end +end +end diff --git a/octave/java/cortex/CortexWsClient.java b/octave/java/cortex/CortexWsClient.java new file mode 100644 index 0000000..16204c6 --- /dev/null +++ b/octave/java/cortex/CortexWsClient.java @@ -0,0 +1,115 @@ +package cortex; + +import java.io.FileInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.security.KeyStore; +import java.security.cert.Certificate; +import java.security.cert.CertificateFactory; +import java.util.Collection; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; + +import javax.net.ssl.SSLContext; +import javax.net.ssl.TrustManagerFactory; + +import com.neovisionaries.ws.client.WebSocket; +import com.neovisionaries.ws.client.WebSocketAdapter; +import com.neovisionaries.ws.client.WebSocketFactory; +import com.neovisionaries.ws.client.WebSocketFrame; +import com.neovisionaries.ws.client.WebSocketState; + +/** Polling WebSocket client for Octave/MATLAB, which cannot receive Java callbacks. */ +public class CortexWsClient { + private final BlockingQueue messages = new LinkedBlockingQueue(); + private volatile boolean closed = true; + private WebSocket socket; + + /** An empty caPath uses the JVM default trust store. */ + public void connect(String url, String caPath, int timeoutMs) throws Exception { + WebSocketFactory factory = new WebSocketFactory(); + factory.setConnectionTimeout(timeoutMs); + factory.setSocketTimeout(timeoutMs); + factory.setVerifyHostname(true); + if (caPath != null && !caPath.isEmpty()) { + factory.setSSLContext(sslContextFor(caPath)); + } + + socket = factory.createSocket(url); + socket.addListener(new WebSocketAdapter() { + @Override + public void onTextMessage(WebSocket ws, String text) { + messages.add(text); + } + + @Override + public void onStateChanged(WebSocket ws, WebSocketState newState) throws Exception { + // Runs before the reader thread starts, so idle reads must block again. + if (newState == WebSocketState.OPEN) { + ws.getSocket().setSoTimeout(0); + } + } + + @Override + public void onDisconnected(WebSocket ws, WebSocketFrame serverFrame, + WebSocketFrame clientFrame, boolean closedByServer) { + closed = true; + } + }); + + closed = false; + try { + socket.connect(); + } catch (Exception e) { + closed = true; + throw e; + } + } + + public void sendText(String text) { + if (closed) { + throw new IllegalStateException("Connection to Cortex closed."); + } + socket.sendText(text); + } + + /** Returns null on timeout; throws once the link is closed and the queue is drained. */ + public String poll(int timeoutMs) throws Exception { + String message = messages.poll(timeoutMs, TimeUnit.MILLISECONDS); + if (message == null && closed) { + throw new IOException("Connection to Cortex closed."); + } + return message; + } + + public boolean isOpen() { + return !closed; + } + + public void close() { + closed = true; + if (socket != null) { + socket.disconnect(); + } + } + + private static SSLContext sslContextFor(String caPath) throws Exception { + KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType()); + trustStore.load(null, null); + CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509"); + try (InputStream in = new FileInputStream(caPath)) { + Collection certificates = certificateFactory.generateCertificates(in); + int index = 0; + for (Certificate certificate : certificates) { + trustStore.setCertificateEntry("ca" + index++, certificate); + } + } + + TrustManagerFactory trustManagers = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); + trustManagers.init(trustStore); + SSLContext context = SSLContext.getInstance("TLS"); + context.init(null, trustManagers.getTrustManagers(), null); + return context; + } +} diff --git a/octave/lib/cortex-ws-client.jar b/octave/lib/cortex-ws-client.jar new file mode 100644 index 0000000000000000000000000000000000000000..261d6ebcf64e67c4d84fdce2f5d81505eec6b68a GIT binary patch literal 3571 zcmZ`+2T)U47Y+z0A%Z~Y9i)X$7<%X+5_%84LnzV(1eGGaBa0MqfzXv8JygLEs)B$5 zf+$iAy=oAVA9nX&-JSK^c{AtD{myyk-g)25_Zh-3kbnV~E?ok68=2bzehP8`2|!QN zR8{1l%` zi$F$Rj5ZjHzlP2)2Z-wE318P63$7*s=B_h+Vqy~T!0@fQ(1R-=vgJz**)BONo_hhi z0YrbyFmNLo{)$3kO6x`<_An6*fpi;Jm4**?Mz6QvjoSYQ)$(2!x)ney% z4Krnd-5beP5iK~V(`ooXD|yLS;Y|hiB5@Xt3#p(0h&FCw%zJAi?-72w%`3nld=aVj z>50#t+nmHrOs+4!J-Quyx35u8qW_9TAdBSqfc5|clK=-@sBm-12*%E{*Fk7%5r-hB z)|uw63a>74k(Ykn*pRu%=h2!Zy6q=Jt4g({eoPl=&;pFTW^tK!)f1}Tds53C3Urmt z`uNnezPzmSR@>hirFDqwfTVQ#~(zrt0`R*A;XriX+t-3&rk z!5BAcT$Sl14l1nrNJfg57xC0DcbkcLvn|!yj+POb!3S;xcZrz`B)(r6yZ))1FyuS* zCKf&vmpGor*4)^pNv2QpY)ffA3``MlIQDuPF&2WdTEg9q*#;7a(+rgkNMP-AGCopF zpzb3lkQ9tvCm%o$Y&x-{tM4wYWv-`fGe-=9lJKV{xWOWN8ox1V;eOPOTEDvGMzCVP zVhs2N`J%bV+&<=-vPz05SEOr0Pq0=4NvEKPgTT1=y$uQG<%o~8 zmfxYJU!r7m4mQiE4e<)G7c=j2VOWtbmXxE}N_@Xje082yBpYq!L|dc-mI=D?pJ}e@Jm6a5vBLF8hO*YXg{p0vm~!(uldO~H(cbUn z0`hBTXI?#(b$bqO$fZ~;-33t;Q&Dt&IwC)3>(#=pwYD?5ek1*pDgRA%mS2(JPYM)T z9EH+D9IUy~T-JC(@xFB81f}AKn{`!04hX=I>9ht(ulCp)e0tFZ}8* zI>VVJI4^0LCYaqQ`7y6XE5;ZHc|xB%ieu+-f5a^BqJS>D%sg(l-QLndzYczfa)L?g zCisrOl+Y(m!Z%)ao8uDe?o?foEGeO8A@yYA$J#CdpbvjGUF+p!Un@y`bcznrXhGH97Ub)RM?GsgCQ! zq+bovN%)xODTJ|i@W(A6T6hx*6Rr<3-}2(MAM#ph;W&ls z?=x@aEPCeX@0KGAhD^QKb36XJc+&|hF)jM zJ@;KMI*z_;j7@hCVWu4Mz0e?&vLcd#@@BAkPChUOm*$Ny@&hg>&CQl=trCA8U|hUnhh`(S=YJ zMvJAydE4|_@4NB&EJcUXHxWf#cgR5x-t8(`2(xkUovcSpZdyKtxOhQqbk!pC)FKLD z8th9UG!d#e8CNC}n|6#q9-$=3cTquDM2;Q5AyP~|%GmPTQ8+8k09bRgj6o3D?KF*y0 zu`}9nrmG!FML!Bv3|ZYvn=M8>+z41+vlKV~dMtS&-6AC};0UZALQ}kxi3uwv_S1EG zXSmC(r7bwI{uGX#Xd*$ZC@*h}7iyFF)A|Y!@}x$0%N*Ot)fZ0HaALbclp61_p&XWh zLfA~&kR3_BmmPw0$4x2_MMQR5D)2qE>-e3ly?B4!hH>fP_G?9a$j{dK1rK01S3!Ju zTNCF_{yqY3Q;K>eKwesYKjyX;+M4fS%!|eY*3&ZEHsfIv3+0JoS9o>L9?`;pNs}7> zm0uG+s7_e01}{I@f^Ka^IDBcuj_8U~I6GM9x7;eN1WmHw%RI(MR)f@~?TmvG^XfqF99e&FiD8c3 zj!m7CX!j@CPq*)n_A+F?J;jL*P@NBn7%66a1>mR!2iD!QpWTt>;_bC3m@zXls=}HW znh0uL%cR2kVYOuuM?lL=&$igF<;0UVDn0{KQYn5!dR2WHzRpB1r=E81nt5~dj4U3Y z$|C2g`XKV0%Jf$ZY&Cq6KLiRcJq!D7GTk32ml$)Pa;qg?iAbom$?V;(|2zhU_`4RWo?v&De-k0BMOGLu_uZ(?W9?caC}$ z5|wj^L!+Z5JE)@t;J@D@9b}Q+!m?P-jver=4L7qNdLv~D(7N?wxGymsIc&>z_aCJK zdKIRN#K{(A_W02ZGUG2=bi->%o&j(n)LqrXuG5~r63ePb5?-I}1Wy9;q-wxIS$!5d z<04u8!)70{0S`H!^JFYK!D8%yDlowzFDnTEw`vc7!HzXfA_bb5ss?tLlEV&!q|8eU zCQ=1S`#|PnM7pZOPq;o@Rup|@%vRkMl}_;}+URI~BAV;iCb{09WHc*&^v&(MNHMVk zWjz111qI>k-=4Q-@O`HDaNABpJ-L>k?!)CUVBfu*vArUW1}$2x@|6c*w)nB3wpj?n zomG-nx;@+C{$U4BtjUlXWms2ofsboYq>`I8|ATQ$l`2<7_o*z$b&2j<60NuL?MDq~ zyB9b14QLmcrb8(a9o;>KWbR_szC6I#Ruey+9t5eFV5pivcHgtQ#mH!Q3zNvHMijiL zx2*f_Cq22vePROiaYJsya#_kT?;tvxqCFQ+mh_$Ou23RcxXuP?Gc)|n?vd~d+_UiO z-!Fb2Z1I*>_;_+cb*@!brc0Zh&vbku^|@9dA_fEgsaF2)I?j#BKjUwwac)!oUHY?G zIJYG~0(O@EUHX$rIqv`j{MuCf=+JYP{%tY-Iq}cR>)d4gh?TSSucH699REJS&lhtp f)qceKgK|8tJt$AVJdZYTJ9I33JKlUD-Wo*|$&`2NKqb zk&lmNMM3<4T8SI4bdmtLh%|sf8WV|roB}%a7^adNapr);jw<Klb1mXO*ECYmxr22sq3FxM z^S1WqmYQ1H%&`!b)$kW#2jL&}p;YT&=QUsBdK-KWxa>B@JKhTMoO?On?+J@CG(s+ zB}}j9`89Yn*5dnY*8#<%`*MT9Q(mgSSXZv*ovsZ|(HWYk^S%f6oRLtG{~U3bUCS1z zk}Na~gW=IlIw%N88yE!3;Im!Rs+|e1ev-UDdj;$Uh6bfq`7wF26^ z{*d=x z-Pv~K_3ub@SZaw(bfwtneE`52X2lOdSKr0{Lk)Vvb*{P6g)d-#O|^`7 zZGYgO5heWj{_m+?`G*yN|Nm*so_4l}+PV(w92kDrH7Jo?2<3w-+F|`lAx+wF#j=c+ zYd?B(EhAEKWQ&DVnu7{HeZz{cQq?M*5)k20g!W!MJw3Z!3M>WD-%^9eR?A?Mrip4& z#xP+@JZ00vSn+>EjEF~X^>_#Q-A;8jj9|8{$m$e$bmX+~a<;y#t|It)x%h&kt6r#3 z0L+O4v=bSMaXOEPHIf@hFu82rnM(Y`2|}6C3ort`IQiVRPQ@IlJpkR3MAYZ!ZRgsR@s&9zXGh+yZkI3Y zcQTA^=Rj|2ylJ?#PDl{ZEw!Xo7+2FhVvFD#bwN#(#k`X`J}rx@*|3OjHBC3kDZL|! zEmsRDY>KC157I8zQy?T0%Oh^m%HH6U9>h#UBA+2fgUAuZ5)aRz+x2MPn4S$t&}aR! z0)?+v>Lj5hrnPd^fqQjTY75!IJ-@qjh5#s^1%=aVp;Vi(Tg)&&-m01>IKze^wgnR} zo-3%x(-kkWvoS43wLtNr&2$aYL4LRyB35+075IYCEYzY!pk*1{GE4DnbHwj`*AVy1 z#hV5<^E@l~bT*BgTZsXg9MP(021LgGOX?Vuks?ya7U<*JYqeJcbhNHz;tt{R88$_8 z2_%}G_`V(j*N-j}3}wUt=}<@o@F&^6;eP!}wg3RH|1NMA^;|?6_jVtg8wV}@jSKl4 zjd>akyb zKMBPcSk$rKPGppPz8KQB`cYk2FY18x7EvJ7d4Lt!MAtnt+RxnJqc3a=YP7vl!@UI{ zw2)b}bje}I!Of~%3f;;Uh!m|u{lJYyv4EmqKc&`UEgxooa^Us{75hpxmn}RT#q_W4 ze4qUiC*9HR*yCr>^SZfwbwbug*U zJMZ_N&PU(Pw1><^8zsAnIiV#^`))uxCT>?H`aAiUtZy!WsZ%?UA*4p^Dx9V*5!}1 z6h(BfGPYwTXl~eS;xA}jl`u+cxt`7$5eD6#BT!+Q)C~Elbr+@@`Hf;TjOAgCeWJWBILVja}y~ccO`n z-LFs2`9@AKziFN&BaTbib6AlD4z`k9rk`@IdD~uI&d)tSI#w17Ok7}PsiI0qQgyv- ztyY$l#pOrr7TDRaowvrnMB>QgpnIF>{j~UfLI4N#%eknCsoO}56)oc-#<+6A| zWf_ukfB0Ug>a0BtG-=2*D%IS++Q@Msv}#m-*+SX{rNR@MACv1^jZqERFF11}$$IjM zO~Etifa2g~CsJ^_Z(Pv!=KeTK^HX8>JW0J{$Z8WR3{QyGikLF({Nj$eBImgzf+3!& zn0Kk@aZd%ipzl7&)2=M@3YdtwrsDJ^s%w3G{lvZ8-&t5>Cg;!(sOT21{O z!nf+TQWLTi09l%ryu8}8dLeF>QAz#GW&ZQWrV^~q;?m1y_A0jvuj%LAF*24Io0toO zvudxn@4|H_P{~<>bG4hMTvM>lp=+YY3EVKjk8hJ^v}v|=z9!*mdj?YR#d29 zK}~4cR}iOKO~~)F?Uq7Wqb@u%N~bp`*`F0NaBk*XbIL0Z%FkoC%_B_0o&6@N#u`l9 z(wyhD9!6QX&4WhQVJ7|ARiXpLB%(+go{Tkgu{%Op^&LODks8~|t+0Uf^10V^II6Ey zQCMt=wzD~!u*ZE#49Vx&X6KZ-#J1w3FjR_K1(!mi`-PI36(8scr;6t(x(5h`tAHez z^@2C-cN+IUD<_H1!+PdFa`nx#vXsJ_ z!P|z~`xSA?+*xsai(#eha>I<8(r%2~i}#LnRkhmTXF{zw_?Amz|Kr!!G_o8O-%k&+ z<#o}#9*W~(3y#xYmo@J--&xM=-ZNYC%4Dsbem{DY>!+Q{>%7B!>GCVa64Mqv(S!kK zmGQ$Z0?qWN2#kQ8<&&Tgc1a$*XQtOG5px=gYi>-07T{4X#!8I2>U*`56=9}Yh@OM7 z!*c~gHLvA~4;sgxbiV!8yB2#aOv~#s9{@kic~H&;ueZ{WTl3Q@Dpv*AYr2gfuG?mX z%>RPf3`^rX!DUcoP{p*Q(u?kle?Kvb1Mw0Mt=M_TyqxW0azzk^&wX3(N|*9jnsIrd zuNYcw)fN{eW#p{E%!=%IY13MaXlAGJfx2ZIh_hB=VKx)H7=@Z`DMqomV0!4H^kY4_ zQ)3h9Yb*kP_`Je7ke71v#T#u1OXHnP;BYlBn;LJLT-806Toox-v6Rd}s?^Ltt~9$d zS*~vII)G&xJf{;uAc(_Vm=S$VKnoY_(yeH1 z?s6a076{%8>dGK>Z3a;geU*Q8HWYt0Xje9*Ljzp%Eo*H~OE1zE6t6aThbQ#KQCuJ4 zR6tiJ{FX7nFDJrZ_k`Fx$3{e0y?zXV9;+bGoQ zDk7OY7-Dcte7re*Fh{&nJ}%}XSQbNvs|TzSdo{aX<9DLP->9Z`@)a-hPF1E-!`8n? z3<)H2obWB)fDdu|(Xsm@L~ha3+)vJJO6jLe+1>)%$6kWds~(?E`yC)iJLVvMdN4cG zX5-2s+N%c#OxFY1M2fFUF!|vsAos1<{#fwNPRbmz^6h9r5ky z)|0@yYJOSr`OK?i-ro}&u2vGg-fT(Z$!K6YY^$!ZdHXMo)Jm&qqZwt#7L*hHO4cOf z8E4&ZW;EUm>OX(h@qbS-XAuvu+&1%TX16$EG>^>iiS?c^ITxvOW65H6A&1=5rz%bj zzsQrDETLd6AqVB>St|N6|6N5U-?l2uwVs1fu`%Mzt8_9^JjUiLMH&YdBv@Be(ve<- zP%y{DP@5V`axWgzMuf)RRBkDEXiD@i~wpmFQX<&da zkrtj!Pfc=~s`zMw^jUt=k2ffaiBmZStAt01q@}9uiIPihk{51i z+tT<^e(?hFlJK@UPNHpGOUpZuiQ3MS*iv= zi@piD=^MTHSH)S025Rr98l%!VxM&6yOQ31;9)0@I3!O#CV9S$K#741Er+5~rlVk~6 zE-d#Q?a+dVky6I1nFN&LOr2R&v#SPBY0KmCYna)73l#H@JD8&VKunVxZPI+ zoCtbDoa9k9P_g*~y)8Gjwg&7oF%EcK;bD-tf?BrNC;b9mSL~~uBw5RdKG2lF>(&4R zK9hX?v1>^Bmh}>S4jYBC`puBj7wt$_>J~#9%^kvqB4hT(ZifPeMHe5Xu4@CLYl^7nnCVs7cmDh}kKX80S5c=+*6OQYNgZ zH_G~5jUrPf6E3%A+lFO>$V>a!Ol@ck)8(0iW5r&VYTRQVsy%Eh=3hPP@a-KnhQEKC zqK02zI_oHu;%hGm%{tY`+FT$buAH&0uP8J7Rn^q1QfD?*pZvXK^bJ4FboR+6d&5Wu zP@Z`rfx9S~l;tP}&PXU&BaM7DV8C`K;T2!RBK9)fsOD=<(bJ?CWlFS;89U|J9ld?F zVi&G;f;48|hkm~i_?XHwPqXYP8c@cb%j#JlN%`br-r<(0c`xdJMxgdn<%3xFBcHxU zV$`7?Y3BGXAa)Ri0sVivYsDXpaDizW|8s z@MAtdPbsb-S9?8>I1TDD7V2_AA@hW)%4U1~fnfwklS`#E)$b&YYJ4Rz-q1a8z{#f6 znTs%CKr6dck9|+!49q9_YiTVcdT{O_gGO{$dg-SHMo#+WD1c{Dii(G4-Bgc$e>CSA zMUrsJop(_$`#Nkfc~-wMR>)Duff7MO2LtZp_=vJ=w zptk$aamg@z%rINbddi?Oxra3ZqMX`{n6-((I&*Qmj^ORONE{_fhuMK~hV1+xbh0T? zILeb92!d>b>_(?Y7xAmRVHlOCAU7P3u>)Kh&3Y~$g4-5U-0w)u-_tu}>yeN;}QgM8<*J709r^$Z)bT&`6G<)EABvDp0<2l@^T_gXam z#*2TC%oXwG8z}Qt^701QHNTYzb*i$+m=iAE|4TXyvvT=DXENqtO+RGn8rNr>?wbhY zhulO@{D7fySPygE$5i|WwEV4N=vI-~KeIcidmM4}$iPN%w59FtK$M6m;QvZ0&iGpp=l0OU7g-BnvF8CYxeiP$cJB5akRJ67UsuP~p+EP{&D5shg++hb<=3Zo?R_Wp!*T z+(dWSj8NUy&EVCPW1W(qdD*U+KGIH0w&gTe=Y3eh=h|+nCD!MB)C0LW5*igv-qJ{r z;gQ=1oS~Z@X&W=lA!>m0>c-Cb*)KRPZO9|t^n<}%+3vA1-axbAcofsl=S!yyH5F%g z&`s1pImTtANRZo4&>ti>UXj083e0wM<)6Q6%$TKI^)W+;DbojKHh#k83I9n%tZu(t=Ax~f?^1C7o8gKed#*{RM8 zq4@ovFO~3QS*ZZN0xeyhHl~_+eJPk!@M9NQ<5RSW2h(B zQVk^r)`JBZdrqRper6Y_G1;})z+7GN@{a&gk8g6FW>_y`2SOZd@0Ut#z8&}hjiZRw z-8{Gk(obQwPCRrsY;>xTv|Z<$s;4l;W%*f3-}K8yYPr%2&fxm&dfLvNY|8rMx$@Ij zw3(?43>WAnnaJQ-Bqb(jnFnn0Y`c$>pm)tY= zU@IqK%lWWJT)zrnZB&MRB!{)1KJsVvxCVCTo+`WqH90UxXEW1iEm@*mSz-72B35E+ z-Utnd@|iGwG(aIPGga?0=TdoA6p*B_%dukY6A=@5@+}Eo-Ggt6)*K!4pAB2O70s5b zXI*F37%VRtGSMN}Us=&TJoxq{U$XL~THUnLKfCa~taD}v!1?J>^`t{9_# zUk-sE`|bVvf#c~jgE;gs3S~-hbBC38B)(*QYZYY{I4eqz8`K-l*Cl{^kOmP$Cm|i1 zpdk(itJ5H!lhRG%6n#Ma9afLzJCtrxqrxuByL|AEnFRR!`qn@vFq1}B9MEoZqSF$r z9%8rPf=kAq=|gkO$)a~4a~SOSyNX8PX1TTvW;qFp6t@#Oj#iC=A(g_}gmn}LIpM8a z@u|h^Sk5KqQ6;2i#Y&1%Gv7sKOtXg37WFAMVPNizPo$Z-^^nWW0y!O%3UTZqsb2o3 zf{Zm4g1Y`uLAL)$kpJ7I`bQOn;lGGzV-s88-**ox`ikpJ82k$Jp`o_PnAqz^`!-dG zb99ezA|jT2>g%GEkF{kB4ZZPesscuW@WnCGd>7Cck_Gx@>Y4yp@dSeHeV1we<;U&U z4nYw2*<0lS83OgH-<~1M0@X`=Ro*K%wWB-8-9P=N!{IZS8$0?DT2qfyO2$s8lvxfn zsj=!3dG<|@2u1A-tx^b>E|L|_vYA>XkFw0t&uQodkAk}81SH?n?L zV0KJ-dlAkEx1cPG0QnJ^o2IMxB(qkp2$gZaEp`rZv56=}&%Y(WHqJFOnsj9222qA~ z*GVY0LV;Pb***Q5p>2F*mUR)DWyb#vBKU@gdG!|PBAO6H$tFn7Pz#EcmE0!IT+3!= ziiDW2H91d6`%Aacf_)o{nF;+P*d=Q0L90$<$G89kft$1h5|@EEDn?XA2bcObL500D zgqOa7g;+Hw(Mw|DFz^$fG4gZ#+h1DQQH&PC*dM?9uKJpUdgZuYJ~XC-4VTL)t^ zNuWK@+1S;=`9Bbo^9L~tLKyrWJ#Y;G6bL~fNHI&z0%m2?LS|GnxlC~>Ap@UG`hAw- z9O<a@QO4e=yVL^6l;Ik)Rjc7AAVP-9HEq>|P6{ zH9~hkdka%*Ffj-S?SWr~f;*aenUO6-OgY^+`{E+9c#jO*MDJY;lVoSNP-!ryd>U{u z7%kUgN477TaYjNE*z~4l5j=AFlOjO5xrWsa(M1ijb3Bl0Y3x9FRldagj;;Cbq=bbg zrA^G02!F$^ zE|MKO7oLb73rrsRNpE9>XLt8=g=He}QBZdXpm5hAtC=rDU@ zBBQ91{CsY_Y4Sa^{j{dNUA>;E$24>Hv z4&&i^G_dlzbiW)qADy=_T7bxCamEi9#;!w|Xt6oMrp9ImK-|e-Bx|uSMFSzJ&T3QY z3X6(OQ;6Fbe2DW{2CFv&f|>yf+yheL&pu^~<+nE_s`o!xHDL8d);&ZDF1l5d9K;7} zRh)uCFYkAx#7J&n2S{JJ>h%>J4cFG+nvSKq0c@GXafM%eCgPo6G1ZL-Y>$vQaM1c4 zn#n}vaC9bNPncA>U1RZeAs&w+4)BamvM-v+`X0@G=7gG5Je`P!ekW`t53%UMn!F#R zG3@-Ya>NMoCSt|seSBA1tU*HXC%M8vAl1z;#b$TNpa8spte!cX4#}K3aG1nW&yPTj zW|??v;zrk=U^e^IZz$}rF+qHi+ZZX2fR^DKB&FGzo}~%2rvKO;Vvcq{{?Oe1g$u{V#m>_d>f}DE}D>kLoBS>o??3`%&pt{KS z9psr4NVu|ab>47I0a0(KNU^5c1z~3kZldYDrUJ&61RZPB@|n~qu;#<vkZ)UA>_oj;|K{g1Tv&r9Q9(U`xSxqook{#ayx zH@E(dT`}OFr~VK0HfieH;%NguC%SBKV)9QuI@Ub1`Xp$hzW(Hv>RO0u*ix-D9Okw0D%@{ggcPA zFxy?Za%(8~TzKTbp$3nN7F*y_#Svf7a;Sd1HlBOrY8gPUf;&*|l2}hU|1jg5i!kPMW}C?) zkGXMy#~A%;2xO_K+XPEefgWm;fqtP*1J*L+NF%(1h2wgX< zRtTg=LOy{5+SDp=na)i6d(hLVX9pm=oSimCxAd+0)p=YtHV0UW@oR9-y8_r{lZshI zABlIk=S*$$va4wbcZNJ)cOun%sz;S-=LFK$R&iywRCZuJfk|I(mv)tiA;)opB!-wR z)YA83y=+$-e7Vkgr|3C7z+<;DpuxlwtPJqWA~vl?B5YF6bsX+p0&>47hf>j9LZ0)C zK}R`vww$kFc51(EsyMLplGVlUDl>&Vc;s;no}JHP$7^He#tA&Hmy+FQthdZbRrm>9 zJ_aD`HUF@l-23`R+j1Q5wYcR5&l|yF^O@~Uy8$8^qE6S~dUA$h@ae#Vvu$wPfElpe zu>0t1y@m!j?CC;v$D|=dlhT_pCMh;0_*a*jWwaS*QNsuq~?5qCY-MwBaod+)44EmGf>9zSQ)j z(BB^-uJ|I&-;}v6`_7VhQuxf44-c;E%hU#qHy2Kv@SDEpak{*vz1=6;%1bY-!yM&M zvk2+7B~Fk-lgcx^!9V~Y5Ok}V{}!FZ!#BZ977}&?BUx18FX^ObFBqU;9Wkj$(urPfR0{;WbI1BgH+QZavpEi2PDA*miR+1lvSpk0UTUTiBk9 zYNkrD%#SGB8TmPc8owGE;9JS(>>Y;FYB zJCp)@#%xX(rnVM!L_rg)Oq$0taZg76F}^71*nO{U?crrilivgwNTP5KoI*T~)%l=R z%`M|G>&4!9l?p}m8>7bK87NP$NFLy2}CO+hfYD{7~g=doumaTaW^Yxn!&l=3h$ya4Y>JF zLuq#h0mNu5H<8NJ%`Z6A4f5x)yvXcD^%_Z{|Li=8B!d2Yu!g%by!$;)XA%$Steh=b za!Sg0^3%Y+RzcG1+-wuAk zzeX)~P=q8E);M_$oGk-O*uh0o@twv6P7lCc#Zw zs_XW$;5{NEh4hm-7qqz3Ht&>)tGONQo?7vf$NUIA{T4LzMxXJ@8*xn1G?0ume#aMU zUe8DEMO12_qGGZk$$M2q@H7*-N;Pc8KWyb@3vKg)dQkVs00etd;*8tg+2!43wH`^x z_RoWZ442}46Xjb#g{>AwFLY0VAtiS9{9RhQfk1tp_3g@@vM25m;>{cC1G@b;DZv)` z3Fj)!$Kca9V8bh3)@0Vf{ZAi=M$r9J2yH7L-1z1I)og;VMk7?`=(WZ3W-$9_9eI@S2>1cv%`PY)!c>&Z}q7k;A0`Ft40R zFbRE{q_IVKh_T~FcuT|}{#YSpS(^RE9|R}vp_&x!^JGKxL8D^r{LI;j(*g_5@87G0 z#ATfw^C|WbVvFm)_aUrvt!C0Tu#dWqjUHIz=4`o=9P4Gvme@dE7*o#9w=yJQOObCH zbM=nhna0(c=}&3%@nvgiuCH!*U6hV5Jw76lu{1fe&L?ijMJ1h%Ka6G*pyNJxLjOIRHCxJi5Z-_ER5T;gWDS)cukB2X;`CX0 zeqXTSakq4~m^FFd+LK0n?tY(_xb4~VZHv!oNayw zs*ob*=dZ=a!%)=>f!t870k_!esIH{2AGg7xftIadFH9%iy0i|t1GTfzE@*ys=&so<4ffsjiziRi-%}+`;Qm z%SeS90Aa9A)P+I?qa!i%B!VQ=>;P8M6VR~SWo}w;?bSrF zIJ`ojmB%r#!Qx?pLH1zG`CS30p?X4ICr!hJeV-x5qsA$b#hdagLB>f;KJq(-3Tjm! zfMO06!T(s#ZGt!z2??3ZnWp)W1Bx^~coYnN0mf0OfKjF18GBbp)taQu6dm zXH~<9whP7auTcyZNi(oP?+n+8>eM2g1;Qgc2db;m<%iH-?n6n%g;i%W&jr6L=fb>s z4+Y+_FWaLatU~Q+W5vvC(h9{DyEQvC26Y5`sF8ef##XI25XrUCo`_6<`DeU-*W`Kt zZ`AsWOkDh?vNFy_D4%ZlkFSc>`pngZbHywjChhE}qc1YTN$xkupK-+cA(u zM@SGR1!$zWkx={R@^vo_f`XvcMT09yz6IKU46ewrL?hUB9D8vkjo?CDoBk@;xaDA= zyq|hL*@8w%%0WwvLum>xw1TjJxzq6>S4Kx}h!@?lDd<#x8yBAJ%SIrNUp!qu4P9su z1wsK1DHqYQW3Yn>cXv?K4S$s*@*x98oddDLo~3ZC(Ot2{jpG<|66>U+;tNvt7-g$9 z=CncU8Qa8B`yICl_c~;2p$&7G%)S(9dH&q$SD2IwV@Ljn@_xP87P#a5OuC=#+Ip{g zQyl#Q_domb>GOz;T(qZ->2Qx}$PT*>I;^oI5$lgqgyf>E)fF9jf3yKo){TaL38`&| zODk{Etc6Rdt3{pNPPPhGe2V>eBgqt}EtPlMhvZ6&Y0N!KH&FgQA19$Xu@b%H@58a+ z()DUPic)*0ucD66mMcWoK*0@)VyTlqsMi%XRu72vvGH*XU!Qmv`hSO7hWSoid+S0D9juB^4*IZ z**Tg0JidQ9zSKqX)W5Qp&~OCNb^7Z@3|<{9=f3eq;N_byT+1$GY**G)T7ypt^R~iB zj<_ZczLi`IjT`4Os;N@O$^^d7PN*nz^IX7OTNd^ggANb__aO14SmnOENVrtZ+IX62 zbru+~Fzz%5YQc!(x)@uBH~giAGkQt0TV&)>6L7;lAC{%cmKRS;9iQqRZkgG4Gh>u;#Q!hD*c7ApERTVr-2-TJ*BHqq(V4 z`ds^cqiIaq9)l>Wth!~In?b_LpXfE(&6Ec96pQC77mW(P203gpDGBQp9tSDT7ru%{ zdRNIPZkXrnMr2j#DC*g;FJ!6cSv7f)n3D7FYH2H0)jRq6DpdeDIKEnE#2oXhJDAp# zO*M*drJB6nP~}}gd*$oE;heVPowi5+iX1B+Mu<2qQSP$Ya3YNl`!t2xFPgX*apXmQ zFo4>Rs|_-Kfv*_3MaVUJ=8M>75!&vbUl|eIR{ZV27d3s84YTKEyq{)5;~tUWDXg|H zUI)S$LGGzdH)LOj--F5jCcn!`615#wc^is=aZBOywvG@kes$?eYgdO?xUG2s9l2Sy z0yRXabRj%MsBBwl5=Z-(Y%)#z7--S~@K&!|26(I12~t054sB^%5DaZ;Uih03Q9qty zqkEakokSkeYLu^-4JoKykPVqrY5dSCF}Vlu%GU7=O{voz8d9~(&DTW*j`dKLr`GBd zzH6O4rHq|>vwO3*Vog6EqVAQf9F+99``?ec@+lp5BcI7`>VoW*-F%Enb>6~stokMe ze55JENl>4N?}!T?ZWq4CJQ7}_3vRw3VN%Z1ysJ6n4_W0j3h1P|BVOt@@>=1^HvOQN zqopr(z&zG1t-;hTNH3KIG{E_&16P?R0GZu~-A1xrfb!h@Q>ruF&ewe(l{>#*ZB-awDT z0WGijPtH?ftSNc~8YU;Xw;bwEhHcl+9q)bq?w&1+JHOt_qr8=&U@rjC9&+c<(_Q9j z+~>{bH*pZ62ofK<(p_|Byu3)(8^O>kVJA=l^t79E7V2PZ46i*JRFrL$%vSxAJptoz z=n(4WD6rcqDzut=kGR?)0aU1=Bd&oe;w#B4J^#XC|qkP2>!&|q`1LIYw4jJ&8OnJ^?UODY499I`^k_5;q)XFen z1yrio=9<7`RH{}f*8wBxHEl~wDlyJgstoHIO}K|7038~250RTyE7g&kB`aN#b}AR3 zLw=;AdcbJAQ9ReHhnwss;xBug?KjF(fIRV}6egjy;{jHT_?v zRKFo??)XIn7=pY7m5>@~-y%)c?-R7E<6kp@-6GAy4f6)3;#}7v&<@TuBBTn_POuE} z(Apk0Or+71XaoZTY?UklwRCgZS{lT%x~9sufFYughw#_q)#s-*jMVXs3EL0Bzi6vn zU4oP@90-UG;9t?!e=D+!S-H4c*;}|-xmW_t6pZbFO2*DE!2c<-Yk50ns{=lB%#t>3 zIW9TubWY5(P-K2Ktfw|M%4c%O9pU3wu&teN3lF+NXh|K&Ay9fQG(3P*OFk2RWIe&0#EP}Bpsr!|dX!Jm7K{ZP zlB=_17U6>FW#BN6=uRtTg;NS)){WW}KmGR|sz+>`6I z{A~P4Xj2T1!M1Qr`6;`saB7bQw`EoVj$z5TS=40yMhSKs$SGs~lWRnA(~f~mMWQ9& zz_s>iyu44oEiKzPPL#4p7I)I$N_?dciov70qmGT zYcDTZJoXo7dL8bY>PUk#`@M%+r@esi%F?9(TJ`yG3g|N>+VZiLZ2}le(yiXBbk5RC z>?f<;V#QQ_&we{6{+(r*of2>ay3K(Vb@b)Mg59%A->eD(u4rC-?2*N>J6Pzm6q4f* zlZ69R=;p$K00zB%p`dzOJRS)6uU!GVN@mf{NnqE5`bbqHi(uw=P~@IP*3IQd_HuAK zA4Fou*i9}cD2gT^mWpU()&+g&q(fVdD^i5;$@pk$2kRBCiv%YZR~lV& zTIEUX1*B-V3RIp;m18>#_Ho|evsVd5RE2I|i`K-+E=R02%5hWWXvfqSR%tbvDe0Ar zIW2Rf&*j&QR7e6FA^3>@EH?4$aUxS7<9O!8h%tvD7Dn7Lg`uHXO0G~tWybFXbskLx zqy3LE%`sX++G#3NxUqEdGQB!_kl0k8hVFR%0-$d?}>PG@1uBs@~>~tJ=v|yznF4 z+Q})5TtOkD0}OoN$8?xo))lnV%#2(_Df4-n89H1skQuC#K%rchsa-l?)uw|lCi)SN z_pMQs%Ocw^jP1P*?htVt2DX?j42#{hD{8u_qX#RtvS*UJ^@bzBb)G~6*$ICVx#)JQKx-g3zNLWq|_3oW(~eZ&c|JM8?HXl;rXuQ?F*f zePW^Sw9#fPLjnK}t5*E7P!T|9vqG!cbvO8O`x4@5|JiIxtV`gIUs&c~iUy^PE%M76 zg7YSo%b&~McoAs_X(NQxGx>5^TdODN^@gH5{gzrl>ebbh#}_L<{9C*-FwgDg+h`G= z6>mx?=JXm@NCm=jGAMPMMhb^H4~3&cY>>{pS0<(Y;{jdQW4|kN8IQSA&ThMcS-)HS zD^wh!+4XwDqj%OgM-W;X@D9(Vtydkxb9G5~C0DNE0n=licBHOxbW_PVV`y&VHBJXE z7E@;LEo}AH?QqadaGdrAn7nJ8x>>`-631+lYo^vSOjQBnhmO39!x!Li>wsIc53x1U z@Qe-nhDVtpx{XEY_oectvvEhVo`6w`=+s~Wm)XHMM1NWqh|b!ew5GkFyV_8$Md>62 zE70g9*V+@(zHX%*(4IEw^ZJwSQnJ2bA~glbTHZ|=SNIG_^ukT7hS zr@YhWj$F6iJsoWI8QwB{gm@HVe@oWrq0&zB zQ;!<}P4SYFkq~!V$$WZ9(bZp!NMXljl_aezzh*u+Nnyu%Dx9=cVX5;XZL*)3Wc5T( znHIbps0>$yKX_xDvJ6pwJBX(W0hB6E~1olWb0W zx`Pp!qpM)xcs-l`I1!&kAvc$Qppw?$xpBF{!oA|Y(9iP=!S29vjVSB{H5`##C2&Y3 z@^H^zcWmZoV!Z}tf%w=gMbs>{Y^^BG%s9jrb=u9?j{~>M;qa{6@G(*cFkhc8tFT7FZ%5!dI$%~ae2@@sP9{5kB;;J<`c1>@Nj;nsD;pz=XNSMPk0)LqwX-pD=+kG>=2TkLmd~}_LddK>IVj|J z%$>3ihsM-(S=;KDv`cX<0i*S+hmVTq@(&aIw`ccr+WK zaGdIm)87l{c&-R1#OA0F>OtLC!+BD@;%tR0ZGi_o*mZU*v^h7o&aE-iWzZ#fBL_S_ zx<5udO2V)t8Cmm@1(R|-b?tj4>5y%r)z~^S{hq#!Jul)4d?VPDFpD*gM-~Kd?l$}w zi5|&Iyp7Kc6$zOYaRXvh>}izCINxE9E21wnI6iQ^>%Buz)m)6LVLl{%>G*2P$ryvX zZzw&QST{?DN?;yw!XzsO9n$`a=2JUq0%>IxsA8eKxV+*DwWwHB{-SoYHl|T5^SqRu zChY{4o1H13Im2pYMQ9s~7;#^6`b^LV_w_;}lkF$=*E*%pS}~t;G(=ipIx~TA5WYwQ zL~THccTzBF5)1`dWCvNS_aRg4SdORA)$o9`U^k6qMhvo%M0YUy9f}_f@;>Jsj6mwh zjiMKR-Y7Gwmq^9IsB2Xg&aT175uI9{tawhBKrC#J%fx6(qh{@R?Q7_NoEp@qcBmWt z6GYqobI9+Xdz1e*h$iM{Y^&;OY-%I#VD|UmPKv6X!<-U^9|H!QzE@@IXtsk3kCClg zq@OYIMB5NKmmH6DIFX#@`30RF82tzR2$}_3rthO9&U6B4#_K2ZvOTnsMg!;32BlvZR=-X!$WL=vTbfUxT=Tz zwH9Y!?moe?OoQ8OW;d|iF3{=D33`;ZgJb%ANCDlBI~RQc=ZMj&+t6Co?PjYWA}Q46 zB13qEwA31!PL`^TReDk6IYKgAmoJ^GYt=3}I8)>;x{*aTaDU$YW?m)d=8X0Ho zQ?aJdUy{atFEtXOp2m5@@+V7inKIHxtxR};B<>?>HJ3%D2MtU*PDK*OFG6G>9aT4Ig1eFIJV{G*f z(1IC_oT6(;NVaG))jk4OAjx9m6k@2M&mr~u9p{YG z(&oB>nhqS>1O#%&$Orv7=!d8xnN)Nvl}$_yCXUvZ4YQCAqjGzVAs*&B#50HDB0t7?p8_{y*uUAj<*_akXB`?jcFrjn=+&>}07xhTxsKWR@{1IeA?+ztmyNy?*4I zqUaV#A}8UsA=j&%KcOI(BR`++F7TB;83=Uc;&_dMFX%%k6zX!uI(^ZB+Mxyf#33Ei zwHdTo8oFs4?dY+!#m4YgCr`2V%@Aon{HD$UfTO_IPO{f1(@%=7}62*RUCHqYYN+qP}nwr$(C zZM#-gtzQ4`b2_3=MDN`fc{L+%X1+5rbIfOqSAD)dJUEa9eoCCN8ZvdJ9!>g=&AW!K zJF1d*dlCL{WYMC+(OZFsmy45~Sm8V8gNDS4*2&~<(sL?a&2ywBqm^IP*3A#WHj{7qov!>E7xzrB=aHFV0 zeu(*6VTdUZ7;X*`e~ox04-an;UD^Zi>U;I}67 znZHVbBY~h`NO(9oj-p5bI4aSBQg)2(X(f+*IS%ZVr!8?gVEL-xkcj zl6d@39Zf1QAbr`5RdePdO+Bem1|Q8ShZ=IPp;Mem9hli;+P9n$JG%)uVniLpf6Gz| z#Bxf;dDQ3sNg+ybRjG}tUvmC?g-|u~{q@TWNscVwT%4ximF#OL?I+?+A6Ny_$()^h zh|v1)lP-@93hQ4^_Mu;qGeNan!a;m>!+cWeYhE0T3iHC+751)qOonzXyn(dx>}Tyj zVKp;&8_Kv(I2;@ZYK-VwdrU{}z(hleK%U2I#*n81DaH1tV?ok0Ug&mNv09 zb2k4!s%GcEn6Ofv)*Dyw$ozG}RCDPq%*q9%KzIRY_z@YFRAvTkn>I*xQ@_Mp^pjo4 zd#vsU^kq0c7GlHzKWI)SZt&)^1wiM{5CJ-L|HTRdqA6jb)sZBxsXcmbNtbV7s9 zcH}#~m&UL498le}1!EhME@dL)ToQp}jy944p6=%_AZh%RePo5H_@b?M^e2)fo*oPv z5Evwm(X#Y7?1dC7xlezsHN9={*GWm~EeOLJBj6f?OQvk{$>9cb{<_9lLK~&zsJ28g z`jyZ2$&gnbTw91!5Q;wH&^QQNH?`2^qZG$($PFB?=|{C!1yfyTNZ^hdp$kO-9I^>< z*LtbtKe8UEcgWH1e?UjAN+zzK+=TJ{zRA&`pcA|JO;L!Q0+Rn;SK{W_H4QoiP+Dmm zPrNbAw1$hR>w~*(>>fpind@iVP_EVol&u^70m*uJT}u}W3jrxLMAK@Y#2HRYKhQ2T zqE#Ko_zZql@MdDsh+ANN)8^~jyiuo%{|j@o0zJx0xCzT8Z(bpf}8J+3)!$$!P2+|fsvTl~(z^3tE7yhj*+1gw3SN$0 zVhr&~ddc-5d6E?lt{v0@=g>}AaoRAk7*!9iadG?nb75sujO6oqRBsDLRorFy$yaNu2fZz;iK_HJ{epmu-A%9|ip`Az2kY5sY$v@~yBEskO__o!S~(tt(X>mz5eFoxQ5-JMXvI9IlDrz&~QWcUfL@ zZ$5obpE*uX*ZBB8+2NV)9eLf)#?UoIbW``qa2O`;n__?WOQd)`N5%f0mw`W{@$pFM zrKss89po9mcj6E6O=$8tGe`7Zl-PY(Q1WO<{uQO0xNn53 z8z0z9Jy7BE3H#B>?Kv&E`>fCu?h~W?pb*?k8~PFQ?WG=~V*JWa_7&$#JmBkjHcI%6 zzgi0UOjza$g?u}|xLwZ$*7-_}9D{HL>HA{E?`-^r=C|%{jKwyb z*p>FP&g(U0X8d`ZaIOG`~nQF`%&oR144I%sWp}@-qy8vE%#8$>;^=JBgQaE|u#J8jP)x zmW~IZIM|b;5@Adv|1h99ioW|*(i{UFVRZ~DYYn4~@Z9a%A<1ME6sB0``aYGz7#S=n zDru@GmSFK@m63=Qstr=4PT+`_G*BxIe!S)Kin|d)fw(-0DWN$MREuO6~LRxpRE$fKbr2DD76lwc! zC>502;v{YMoUhq%O#;pO4tj~@-Ipb2Gc-JqrPL@c%)*HC`D^lRj^%eJvh6X8et%@8 zUtUIv&(Lj_B&(;#*U`+6mS_CXs<5w;1lN(q)Y8B^#*6+rca3pfk^%Ij*e;*X8MkNH z4i`8v&BVkwF*%ixjO%r}%<1yPMxJuV55SHEM3183+&_ZF1aT`AwJmJ1L{3n6k=HI@ zoJRq61bqNGrDDvI;0F`d-uPy7hJ8h@h2$}c;vHS4>#xc z?MbmWi^2>Gj482JAj29Vg|JLQ=L3XW`B3lTN{k+;vr#08g*N`h9*rJ&nu{3^1ct~I zSWDKVwidlH5WtN80l5EM50W+b(;v4LA8rfYq&CcK;=}>K+NF z)FF9f!6-C(8}a!y;JEvV?X25iU4f(L`%zp6ke`rHF&eHWs4D8hM`eq z(Lx2~L{^3w!ra9VAhwT>f-x8mhB14DnY0Hb(hF9XW&ZVWd5E#6NZC_U!$WW8&*VD% zjrm$~gpFu;cd-S%&eEQviJ+gk(TYG6%H{L2U=fL~%rqeLT8b9~n8m3W2i{(*0BGgx z0~Rl|k&K6Cys1kMUYh*C1(LRE|H^~{b3#!U$BwQAL-)lFQL?0V8MU1J?QqvxIZl;0 z;z7#`?JL$ z_>R$=Bv{U%m{X^5urc10Si;l`ejY{Fb()>LPlffO^wl6{Kpw&hp65KuaB-%p9`bdn zFlnsNTj{TQ#i$w6>c__&Af#gy8}?mYSZ_ zQ|+ZYgC}c>5hkLb?F&$Nz9kNBiVd;?7e(-#4;^yK0&@XQbt&{!xknktT_N^>F^@Wz zInR%L=`tV%#z{UhCDV@8Y#Hx`x73%b7{tJ@PV?$r2)EJq?TF6cPfwbuK~Ee6J;LF{ z&@lnq>B@oA@WF-IIC3qY(5(G4T*shFEz>aqBv01OXtUDgJMpN7*rZ{XxWa>P8bF`v+*Lr($=sB*iWlHE` zwJKKmiF_5cs%#5jbh5<%jx8WBG+O*dxt~anFid~!8udM0rx4h*?c84jR6Jv9Rz73; zgh<&TbkYP1vjEzR{P)y8lnl4fKsPJAa%2N|TODzXssf3Q98>-nPJU$>%X~4K-0C8! zWsuPt#SJO;KZ)FR5xDxEM51j`0OhZO`RQOcBcou7Sot-G%q6reub5IU)SI;jC7kyh z&^CDHrc-Ps7+J3H>=HBNO=X{Zwm0qzMv+|hphyys0R@7lFrK@!hHqYTQgq?k_gyB>iCGK2?vI@R_xnJy?jRqak;Y(+2~fl zArjJdf$g%gyJ{xeXGs&&-AA@XUg|x`W7yo{G|{nZZoEj8(@FFN;$rrFbQ81H$~6BA zC@K_A<_FM+S?v7v5TR>YP@LXR>s7GJU+!&5XN>wC_|UgFxqmmE<%F zS~DK7DtsH+RRBTSpj6MEDGeDnjMSTD$- z7xDuCH?MDS_XmSbe%_+1CvNly#N^^!!bKmy@Aof`cdJjR?^IryzNScZ*habOlh9(* z+R~ugy|_%OZKr9*D~9Vd`}h0_l2B#7V$2L4S~Kw4+$P$jsD;UMkm@Y2E(BFj-pmt`0TA2`O2^Z z{82~}h4JeyT_wk^OLx)hALSLtN8!H;W?rEvMTJ%1)+#)UmFgX&+RKEP5zyuJ<#XHd zi@ANhwnE91@}pmC#S@Z&`|eN!sD^cVd@Gr zy3t*=5p!7QO?S;NK&(?CZb~54|tn1J@I4mZnwU zGt>Xb1iFtiJ_!{;4aRR)K^>wTp$OksLI*NIT^Jw@`?mk(R|sUcM(fp0`c0WaMPyzH zD|MH0>w$605$tu_&vVym;#*Q;RdV^Lv6C(p*=2y$;h-x_BG{FII1pm{@?kK{)62#= zxX{#WzWfH!2kEver0a{%{pL$~hNuvJSJd%^T&0k>O6m5O`+XPc!h;;~*CIi^tf-G2 zy^p206<6Kv<{RjOf%*Yd_5DQQDsSXJ;(V#xT7Y<3xzusnfn=Q2^ulqf@xMW0Q)!>dSHas#1+UfYDFxF(*TrZ0OUnu z1rCie%wOSuqIWr%H(u%yLo$E+0-_X_vM#JHC^lw zGZ)#0wRkF|TC}{BF1LO-c1@6scL@O=CdqBL@RSKi4sPja_B|z(Uj9|VEd0QVnMI6v zv^)taGPD!b}zOlnA*bLCF@9?dc^$m6lrNLZ)3S;< zx`muCYM<;r(XtPY&hfdWxpxuQ`?mIIy;(2RkX8D=xSrn$yx1X_a<7_tfAhrpoU(s5 z?U6SH%PIxCq;p!AkFrc;?0G_U5(X);BQ(9QD(f6MFe3LM;8bYW1g(}HrsmeLt2{A@ z>;9c=>VRk85@7j?Aw-i#_yh(#ayUQWsf4imCkEpatGed<_sR#I(<+kVS_}PrG57h* zMRsdJUSxkC_xXqJ$=@N_rupZgiINSFo&3wOEj+=ov5wR4sF)|XlnV6=ss4ta{JE=0 z{0nq3)w-M^;uj{TJfY9WOL16Q@O0;Vm1Aqb8M0S)fsC>Q<&1K(dQ7hZTdFzG+`&_A z-CMHT{BixMZMKBm!Jm+O&S5#1GOT9PzH$}|x_xnGA}9SZ)*=$ z)41!OpM);LZUgTF?TR)G|4x5NH7~mRqILI4V>2t5<&?@wHe=VOqE;~ToXskOn{WO5!8M%mS;K+4puum>y&%6m@R2WEftsRRv zXp2@Iry(*7W!?-*8sqFQ8mQHUS3q(aRP(5hjYrLbZ=D92<6eKAT)0w9$xwI;7k?w& zuKg4B)-L!q{C_7-JSuZho&EDMD3JVjI?DejX8k`pisHY-iT^F5jA+3AOMXw`6-y=2 zz)KR2KuJa_ooT< z=Qqpa^qs@Usb@HWoeJg;Uhx(M}YP(d0O7&iJ9X^hqf<4njYtc%V$c? z&xEWU>U`aW4A*y4Qt7-Ef~VANpF^VHU&5L_&WiA#6$y-`zKQ-lj`O{eGrsF*FS40Z z6xUC=i@$V`JvL>3Y5Uvx*e&qB6*&Kn3EYia-c3ILb(#OmaW1#WO%W)^o_^m?jUh#F z*03`B;o8bkk*S+x=0!kb0I7NaB5qKY151#C28kg6ly_2m!Y#5Z9m2vrGfN98m&U<# zt$lr*!96u#Hr1q6I^%keli?8iJWX@#!r*x4hNMe1jR=xD z(LLRFgj5r6S{zVu)jiy|gv`4;2IyWM!@6fQr*e6K>ybOEPL8V}ymGp?Bz=0saO)lK zw>;W6B+(hVWGb@@Ie%;l@Ry^b^C^O^1k`-B2da6}&E@G${U06C1AFrjRg!I2wN@U` zvOu4}xK`v)43!oVd(IF@XOUIf2~jh|L)coj`@K|%r(WoQUYP5-D6t2KJQXnpTm(vt zn@wJ+y!B(-%Xt1KIj2vFp(8g&7;*NBGxd_p$E{kQUYNg?Fy7Z;^E}T~s+k7NW6G2` zMXN{go#U?KDxg@HL&L)eF5F@|OBqIJ{pij6;%DZPI768fc%K+EbEB-O|7mu?>@(D< zGVksz*bugE*{HL~+Tjy9vgOQC&wH@lIc~<4f|e?V1Q3X=b3qpRAk7@}f;VV>qlN0d z0at(Wdb5%s%a$%9~S4qDTwrmrhFX<4-zb90lgg)!1uHo7i9R@Foq9)sIOJG$f959%zZFr&={j!^pbc zj}tPo7ZD=LG-Vz>l`xs16AZb_#K!EjVqeJrcFXbM*QoxdSPqa-XjTeM`1 z-sFswiwe@Ls9{XxorfSx%Av9n4X#Rs-59C8{$5Hbsc4(4{aN;f3u1~vZ!DC7)nQij zb0Ce46wk+2B1-ITSTN@FL6$g|mPtZf$oA-8+#6w5^Gj1C0-Z4TlygbSlnm)w=`?Sv zETPs)Tm9ASN|v7)$CM8j53jLH< zxSIi!JnTD5;rV&=oujbKnVE{cR~97J3Wz!X?xZq#x{TXreJ1d@@(CbKm7eKeO^hx( zN?=bv6Hk{hBj=5eE`L#|5I2jiI7thKfVnwg4XG`;Lha1Cl|Q%LteZc24i=nSWC+oX zpNe{h59y_;!Cz$HvQu#j5UDCju`a>lMo4n*}T+i`~c-zfmI_kC$9`LSqD2?iz@^BVJy#Z3su?%c^ZEJdecRuNe{(j zcmjt~Ag?++{CiEkH8mqe7(V=}Q^UDB2Gli?nui#_WgyReLyEl76c19ixWUzw^@Bn| zJ+YjP>juB!gpRgt&8U4?hC0k*VuRt>HN)sK;O-K1LzJSYfbNvtF>u7f&gqvT9TesBMx_RccAk-0yY-VdR2s%a~d{@2t}FC<|3*u6VT*TNXM9u$KnAMj894_ zx|-zPS>mv{4W=EzCN!!Zq-C`4oSL29CjDx6TDoZJDoxdv8zC;el`2!;y_A0)^=>{~ zep05atSs*{&@}I=DjS~8(0X(3>Yp%Bdz1Rg=h;4Jx%O)AeSZ=M-^Af|tTanf+yuWJ zRM1b|MBJ|BljiM+hfHDc<+w`+E1SfkFex}te;D`5?twL43KLZ1z%7j>Bh11wp1D-w zUNb1MLhsU!9pn!n-vzk%itmR62LuwlEwV}z2?&m0Rh~M`y*f)8tx@qyA$~=;GuG6- zhFiz&72Q#Nk@LAibY*Gi)!?~_MrATjN+xqb-%CK4%+Ycnibt=58M==;4@~3wEQoIg zc`qL+3?<;n;jF?;H7<%eovGX>55_&A!1#&GXL0~yrGF{CO8`GpB>m2CJnXrjhQdUg z5o-K6Ns&BJbQ;yu9Azv0QQ$3Vre5<98Ugzz!p2z&JWb`VCupxV>Y-B)Ti?JuH-`__ z%nT~v7wf4ja8R=HudpmE$rw+b3$zD`0NDdkDJkQzp7Qv0Jj`aSR7&qseDvv6`Wlgo zbOFe&CB%IKr{VP{yT{_7Sw6MeLcKJ%hJxS(k)g5C%COwK%Ovb&#{kL-@z8)>{k-J7 z%+kv8wsAjr1O9;M$A@ESX0b+aW^P*r*E~sgDJG5Qhb9}cfVXzDxMgdccCJw8T!r*T zVmOr5DkjT*E|{)QWljDF@Kls}4k4q=SNIr|4Wb=iEhc<498JYX9 zh!pjb@2A*u{KLm-#Nu`pV6k;DYjdLOrWw2oK?ZenjIvX(VsYfbY@R<={=N-X>pN+Q zmG>0P^yw0om9%u!Z0v1g0*2mjU}Zm#pPIXKkI4>NH4DT7T=iSXXw0x%7j0VLIZdz~ z4Vi6<>wsT0+N>uLY~(ECpAxgB#mqI77Oea?n)RK=N>g2G^a}^XO09UQuUdvW%{5m* zzzb9|ebTq}pNEXsDtaFK;_WHJd&H)2(|TjoM>;f5&2Zr_XD@O_Y+4qt0fE%)#3VeYBXCtj$Zc$Ulw(+Eq%L zR@69Z<}~%X4RAv%>cUZX8H{vkQP!PN@fob(pjw*#I{CKV?T;-$1~A9LhtqL6k)T?e z#%BIgn%*_*6d*MG)Am69XT8IX| zxuqk9)iTb!8|NUDg=ossRp&UGLa-NxmHC>QlEBZ^Yt8?BMpl+>p|+)Rf@~H(Fy`vN zO~8FJc|kWslx6;$H_gAGcdOA$-gThy{D=MtfD`|>dNUj-TUSY8b*H#f?#%&|WRA7-FnN#bPo}DDf{Fn4{8D!Qmi%0tQ zG-m#)y3ThNPhey#I@*!0T>%^K0J#1*_Am6^6p!)ecT?oh=5NNjs~z5=0kXoLDWL+I zaZLvdoa;v4mXXd2{?>&3mr3@6!ORY04!k3wH|&Ix6Sb<7Iprk-mQA1(-VP#efm{6mtMo$#2i3cKRe-<_p&V}yA6Xd-(9IT&g$;iw{@v`O^H>gSl1#6 z*1icTw+jXxNg;raZkYlODfg<1w+NSxz)A%%MJtqrL=_SqLul{GnNE)q&5PY#0iw6+ zj{&bQgyLSG(kpE6$vAQWRB{fyDG}uV$^i5NCdwO<5C(j_V~kQ1Kmly(G1sY@J09&p- zt0Ahk8}gN7g|4mBSw2ZAnq}Yh=oOOrkaKoxAK;B6l1#yL>AeDv=QZUBxi7#cu*ZcR zQUhP1=_eO_#!IJc=?zWhNOcQ>WwMk0H0bm1)$|Z?Kk+6XJY$|{Ro-J-5ZyR`-?sFR z3X!3p7`M2?oY*m=cOC?~3y({IYU*}6P&vBvN<1Lc{V95yC(XD8$9Wf#&{~W@Ma<@3 z+Lh&~fEv%;=8ck*z&xU4T`}?>z?_}QNuf!p&Qx>vkfzjIMf32SM|zWgub`aihcbT3 zRGHj?8x-7vf z@VNn7hevE_Eu@bvRFX0&)Eq-fwh=i;;e56N4DQIC2B#@;Ga9`>dw1R9$rL$iaBqe(&fx`;jGk4MZwkk>ac2 zOH_FVT`Bn=@)4J0(LVrPF)xoGEHi~^uYYrepH=49kbzm1fu^Fx16xQn|46sqGObtY zpB#lZbyu@*nb|A*y^-(6m{eJ7(;W-8cyKFgX{Y(hmw(EJSyoXcqpaNUx1f|)^0#1A zjrm)Gl#>Qr0?Eq&t?cl>Y$9Tgl_TyESwFOvoQ`mrvN6r0vZ%a|YTRjQ^XDPZs-KVskp|0tT=2=8NU>m>}|A z;qvV4oYPk#=oJ7|51e%>^{h6ok_G(CmJkF}FN)U#XMVFB!9p@ml61o&uxl0Ay(Zo4 z)$%A8*&7VehBj+EdP(IsG+v!mb2e*7L8*o`)8Xyz~=&^d5J?n?WD-U%Bg zU#8|jRVN-o^b>B}T1{I~5987Xm{kiEe?d>-lSw7mJfH;>-hO9T@MKshWT-N`ZmO)m zqWLuSEkuxa+TIgSdfJd(qj@Mgy~HE~*D!;McZc$SLW5kCF=zP+z<#(qK49N}Wi5~N z73luZki5G&WB19pJ>Xl!@0HkTP(N3a)mm)`gma944^9Me9xmP{u160vp1cWs(IaX&L!GN=ji#K-~8q!jH}H z->G}N|05-3=j3er&*`aR>uTa?VQOJw{C{9;Im%Z5(q&P3U}-2wpjI*HNXpH%@E&T^ z@j%c8CWTfN{YT{EVQmPI?VhX;PLfy%8XOFqxky4?n+fr6bn~XZN zG6a#Qy;MW;dYR9`&NaWx#LL;6%sZ+~bw6XfB!OLmVz0&xLVu16On#=NXc&Y?dq7nF zHO!#R+aafM@*B{kt>n%9r@b>H*HC34cbr0nc5!S`DZtt-L6eqX(oU}pHb)`2m2^P5 zF6GrXcURtK$V@Q=qQB8z_pj-R~P~y zIXCGmj+kf9%>}50luInq7ax$80FIod^i>A3W88~yWP<5N#Y)>Bdqbx5ane46X;ay1 zCeL3cp?6-q2D#Z&bkni3#(LDVv?lm+GSVgyhrLB7A65y|bi%1|X~La{AI>0fpc8zE ze?4y9PKUrbQoqQ4A7DIB6L6A%Lu8%`lJ9Z~qUpT;N=_Z}X68xBAbU{R>F&8QfU&iE zkM%aX+Ece}*}ir3B%ue&^6w;X$Jvu?CspKoz& zK-|G^GQ#vGh5!wexq}ba=YwqTnTZ`(QhYiGjinqTp?s%lTC8pYCBO^Nf^^y=qo`f&xRVF$!bbyB})jBj-HBH>xc()_cYUgiQ%S zcGYs0Q(}}cgFpi)h6UB-jxa$hv5gEmMfDxv2&nCeX)3dWG^yv0AvaADW>7c1{_N~i zr?3%_pZ$Yv@KcBV&A5v2to;6JIisTjl+Nt;Bp&yduR*$x09s_n_PD2J=0@5br8l9^ zV&$q4H0R}J7a|B%*)6ew%k6d9bH9=>PJt(y21a(@y!}cEKp3SPPl2(`Qu?yvxkEu& zW0OLPvE1#LkbAmh<g+;-g@q2ZwaKUoLMc|cOBQW%4(o;EFeT{p zi#{lMwbFZvR-v|Gdj8l3%@_l5FNZO`>l{J`q^#SYCT`xo^LV-ACUys)jdgO;I8$uE z7I)0ur|DRRn@9fkbEYk&;nljuzA9C@3&4xp@ii=)*rBNH8QLhoa;=SX$l6|i{20rg9|nG=)^jj%#&s84>V7_`9%NvR5fKBADCr}0+(B}* zZE)254=d$!g4z4+;YOc9VKnLf+9T4Z@Uz8InwNINWKQrE>WK2N|3(K~9I??Bk@2Sg z3wEP9RWd99KAzL^f2Mksd&&@ioMpTxRx%#vt?K6C1}8l*$O2uUPRVfPXKR7 zMfWk-sux*B|4P(E3UMZv5F+=Q_#LM7p2o1U&mF|?Yl=9CO>PDCJA6^t+e)lx;@~G>h zu*hAk(rbcz25{?eGg*5K(_k=J%5|{i%XHJXx+}$uN{pZ%cautFS&*&7Or7 znz|qj9$#>;y8hW2nB3IwUE#TBmgiYgzy995ww50w*)uYna=D7Tx$?=miDOvVi#6eI zc&$%d4qK#`F?V#eja)0#5f#)87>z6^>!KM;5@p=j`!8sf5{1^A;!4GE6sFbeAj_-M z@ zI{kBLSs4ANy|b`^v%&v))Kt>4`z3(-6KYk#pP*=0bJO|)g1M27X{2bhC@8UtgaYbP&-)uoAy(Fz@f4I;~h4#f#AApo96=!F&Tsr@zC6L?ba= z(pNJHnNOxFwb9};T#DV=2SR9tmvH(GM-aIpGF+$~KV#okcGE^oF zfKvpPk=i=-G2wsh23E-u0b;A^5SqU)j>D-}53^Sr$@3FM5I(3=<1ySH{hE;G>A-u7 zeaBjM6FdFg@6(|E^-ai4TDZkw%@XzL+ws|1zqy6s?*2M7#d>djo%{=C9`dw;s}%bj z`)JLvS@E3zuq68=6mx`*9uK^SF2rP&XT&~U0WxY-rBx(W*8%6OMfn>{A=*cv zyVEmN*yRRpA`W@TF<7R4M}Jr5bp3FfRWf^_RK0p%^EoToKIe+?(Y7AL=r1W%=55In zU^Q`NPTc!lBsVhgB%GehhMf#mJqK3y2cdQbyiP=?&F{Y~UK#aq}r#2myF_hmmzbAo&LizYTN0; ztaDTJHe&_EoykKp-p&{nKC=f{^fsp@uJ%84Ob%^KQH|wmVs4K^I$!o|QM~AH_3I;t zy69aR+hd2m=!o_1@gqXic%}_uBSh4ACJS?i4Crx9?tvq^=yHwkXi;VAUzsCz>fAGj zSm<+~=N$MvbmUD=HM^VEV62x40wVChMNNdo*jYgd`N)fd0z8ThB#OxAP?rVfAv=wk ze^|hX6nKimhyon}v&*bjXgdq~V&GK|zUof)LgG=bVJ-r&D7tIx*{1rTmmiq)RZSjR zHlA6(9bimvs+l?iJ+-n!Q%jej0#Ed+wh9i7uoxs1 zI~=lBO*+KpsY+w(M)g6AoY%mmWt;e;qe%Vh3L+7$kElbO5L(A0T|QcC{#REhU7hz( za;${aZh)*8fi~kYs(yOH`2wp0Oc71wH=MA32g25{7rigN0b04(*x6|91Iyl_S> z+iE}T7Fv$3I-RvmX;_q97|maG6%hf}v7tc)@GBC)QkD#Qr5Dg5V&>$cvoTH8yf~~# zM;o%ZdVMVUZXyeUu_y56JIL;CqLV!~u_6QF`tuVsvK;7PEwVkFC8K5Z4zj|CcB?}! zxT3;omS+_Pv4I5B7!5-D0{aCv2d${l&E&8%hdxjJ^PxK?6R05}(`Yc4B! zDj~HCt)f)Z;tCDSVX!S~o!AvVh}Fw>5Q&6*2J4yefdT9naj-6CRSgA4#R-;qj(I}1 z4q$2u%{F;o@y+IPQgMwoq%Cdg3Z8-f)cml`#Pws8U11y63Ju&y@f?=l=zOb2xWUt< zAA0+4O&oUxD-T>y&5O;`*!5Mcq#F(gI8j8l}~t2rVhz;Z-WF60X+y11+CEDXCp@!VsyXi!AH@Ir|y)B7>kB zCgQoBho$VL_G#e+4rUYzF`b2i=8zd8Eshk^=yEl}g;v+`s^!IrYoju3i_5u7yVVK^ zb`6`960L9O*EyrJ?l$M?2I0-7Xmx&t(DiR26Jb^Lz2zFQLT#r)HN)^#_!kEh<(H8n z#2ppR&W&>f$mbCO+7eMR)bf*Ui4uV2=q4_Xg8+NA%~2^Ou9%bZCyYu3bCl_ybMTbc zg(%7%VY)x(XeqiSdzH_CZ-f*FOIg(m7rZn0&mKv?eAARlk3xW_Qi+Ok-J;g>7;y1B zf4MV>PRXM0XOg7d5*HH=t~2d$&DNgH(hnpiw+oxRY#RFk<9u@V}qyw zZh{YbPyP7yhb58;WI z8z`azdF~f+qcM!+bh_T(+<(RA&RXrCH$v8sP0T`;WW7aaHy zQj*WpqEmN*DbbQS_j6b!svYCHkk)3cD9iZH-Rph+{_7z0y;F`JL4}fo7q}F`h}58# zK^Q#6WLQ;>DCT(5Livxpic(D$8mb=62|!3$GA68nG08_Z$sA&am=N*AF(9x@n^r@7 zUVEELIf74_?y;9smJjWXg&EP2mzgFRf@a}8QHNOamh9wMCwWyY_m>>Lht!u(@-EdM zT*M49-EkxOGqA~05P*yld0uRZ=7(&oAgnn-LU$EtN`Ie-^1qvkT8KAkv=^I)>*i3Y zlt}}QC=0gwQ2KaOftH{Y&AwB?!@lPEo>ZH_p)WSwG=$x2mw z=}{*kIut!tVCJMN%49LV0<-0sK6j|MDj4Y*Oh%xjc*@{Di$?&q{|crp%``iBjV!o6 z?6a9XvIPS$d84N=$j})sVX+11y1El47s#2w+MLp zvB6_B2Q7Yo_naO<36K=VHI``j#)=m8^`WAd3|txY&-K1cS#hBAci^TNk%K;3H*&L`Ft6uc~y5MNATf8L zh{>N?xTL(+Q6oZg)3@t{i0wuH@ZtIO06}~ZbMBFZTPwmm4YS4^Y{U{cd{M3?iWofQ zJ;rsrAKC&TVH0}g89nsJl*DyCVR3#`acX{W5m+c|azE6W*v1y{60dneK{54qUAVvl zsdqcV4z7;m8%*SSunlp8JHHpg##Ir0D@=b2A&^&02keBknIlYgR13s~y)|H=WKpI= za;-y#u~c!Njn&PiREX>JZ-2nt{FCnk_37Ka0oo`g@CVZzUoN0EL^e)~xSC@~ml$xX zNwGh9uV=NiCQ&QtnC6Jf zipTw_=T}FwK3mKSh^M=Xr^Nq7-a7`_)@;#&r)=A&Y}==7+qUhhQ?_l}wr$(C?XK^> z+b^PD^t<;(|Lq@ZM@FpJdq=L!l{x2_Bgg1s<<*ks9bbsA1(=k~@y1zW&GiAZdGdd; zQv3yW^Q9%mjW_PZlEkf0oL|@~RQqghb*66V$angv&Vl3-*0CM}NeHtBYw2VC!8296 zz3utn-7RzB3clyQy`c6#|z(+NyV@w z=h9w`bBnwZ9d<1?XAq1p0`L-jCJzyDUvtL#=T0xZ6@V$JzcZ$3@n2^OQz$--13#9F zxF@pV2BVxzfHn4P!P0bZgeB#>OP zs5Hc5&pZ1$Bbl=LvjDDH&sYOoE+LyX&o2{QF8}34z2?y+eUuq3=w)F}Ct^dg{}belHpp7J*1;vK=A5*hqzARB&96)9oX#J^P5&ma zhUT^$?sekJ+9)#{Fe_TqYk*6woJ*ifnwhP0zo&FIz|;np9A-Q-b4&I2n!RXFwY0%i z>$J1j#?)q_?fC1&0b06SLAQf2Qtud&Fp)p+z=`4BX*9US; zK0p^XzMnWX*I@7Ky1c)hT;Re#`IAXw2!=7D#8q<;QA+|qDD-^))ht!)10szHw@q<5 zJ=H(X`idZ-@cR(wNTf7l(z=x|+{-s7CIpd5AMiwrD~99SF1%JVS>i6OOU6#)KH4aQ z274E+IrjBJUK#%DMYS^As^6{p4yPa+})RVZ%#X9v9UYibt(bVeC zKLD(t`FFxzJnHHIJ{1NxB39Y99w%^aIv^{qK~h+OBsTepYw#6T=FBO}mo`XQ2Y#dZ z3$2H-SZYOO`}U~x{>duRHq$|ktRc5=&9vt*A_u_CHBG2&SnZz8?dFz5>6PSe14qjTpfUxgZf_@f#6V2)Te&+q~D3nB$q{=WTipwa95#-ugWF z{s%R{<>fk8fcf=n@<+7ie}9ml^uLv;q|6)){w?dG0^zEugz|MgVc66`m04g`FW1&< z80Y+#Ut=wX1%@2jkX((7xPc?JgJ_@>7<8TZ}n(JghK-zON)JyupMSma^2o~GX02X$X z8;v|~q7U}h+6pMC8==CKPiMI9D z;e($?+j%G1`UA3hBwDBa7VBflSEW$P1N$ZOFX0wy#DgFh2t^tTSTpFS9d|-RAkzBh zrF{-oIVH$NnDEvqER%}R}?d&>YAYMRVR+azSEFvI}8`%OI_EZ1@Q0&dF zQQJO1xNeMkA_ZE|{b6^>Ft5=?iV5R1G}-{= z@-p%qVhwR;_%H6M!~;|d!CTEPfV4OT;^bE5#pR;G!43>M5`sd&fkv=t?G_?-frPPp zy+fTyV$5I0A~27GR)~s+qEECCXksMfC4Ya)dN!_f;aMpe$Lt{yHvWx@GIYJ%FI`Ct zvvXMCQ5R`-Sxi~HaFFJC?o^EpGrU2Z7j6M-S-=C=c0i?vc<}j@%3j|BJ4Aq1TO! z6&|KE*g`dWb1x^vBJK?|2$B?c!1B6u0+3>}$<_FHlZ5St&H>A5xhvdkuFB2yRuK{* z8#dHrde7P(_G^S|vLbkfWOjI{AjD(g!Yj9;t&pr6mnM)pEDNJu#1TB&(Uubx3JM0~ zsz@QQ^Z3xOk_yLjKYE(%gvtp+0Xq;8Rt8v5|4>;UVQjK{efMmh3mcZC7K10?gCS7@ z?0HTUwWT)DAUA>}XyUwu`IJCml_ACcKXkZwB2-1s;wEp53l)+k`Eer^Y*jIex{6^R zxw;WR!VM8pB=IH;h|E%HOn{Fcr*w&V3Ng$Lhr$n508=1@_zW87nSDJ~qrR$%)GQ7H zsZ*JZh3gw;$ul@YYO?5I^Yo;2fdKO6Z7eP5gp(WwRU$dm;q%d~y3m<(Cw$BdetGvV z@KMe)X7Cm@I7vcF;*N1t$FurROg1iO4XFyMVaCTU z;}F8+183LxWHoAdsaUYZYI> znk45$?bN*7^WfW?kjLB6W~VOKsNw#KA~aUPfl< zpqa9Zbg3VXdpUcFbUr8S2BIlN<{PxA_GjO;1@Z2~_;QtYRW_O_u8?d4CJuKj;kYXF zYrKR9b&n0NzoZ9s?_>I6q@t3ja-^2jN7;v(qW2luZ*#(a2=w#b(t>?e?()7=2Yv5q z!HB5F2hIe5T$}cdf$@Y{FlmzdinF+(y(_C!-Z@*T*VeX;weQ7cos}s;VfPh7UG#?U$zS$LGSdMiPQv&S%{ObSSn=7O6E{UQ8R(_l$m;=}1*fcTe!pa!&T-T=?8t zqtw{8+st<(VEB>8rQdP}G?A8jt~WG$yTT^qTq0obHWVoPs?nWW+1njY31MG9fqP8` zdX33(Xy8L5dooti%Bbwz5ninUQF^4s*enSEJmPA0Cz+lj{_J&yqO~3j&y1wb;~C12 zPR!n!iNVc92rpU`j(7}FH?HSb%u1iVMYdf)-B9LTvYbd;(W`(W5oIONxH#E~DbpGL zo81w6Bf)TpwNlc2o=oDj)vM+l$;=d=!W7-aXDl#KGkzK_6fe+V&?m%)AslD7OqJ26 zmQOu`czxUOCvg~A*WRPpqqTzPs))+#eu8IhEg-;MW*Jvn5GM?vCTfK9Z@#|jfz&`M zs5kYl#!cq_I^4K6EEQY24D0qE7)#Xv;V32na0@%wZJLbmzok2f;^M3P+wmg^ zr4|WiNGM+6D_a=6fbAX7QvcSoi{oJ7;@%1?Y+_|3$~Gr#R#KS;-A+$#i+`OV7tr(G zlF}R9WE_u5xZNpa`6U$79j3D7c2v#Tb2g-Tm9(H7hbbE6zB{kD>{pES zb*#r|D73;Qwnul65ht%1uaQ|y<$4xPCS>Lsn;WksTzD}rzT5Vt;8;<3;Q1kerO?4K z!oo4C;|j264QX=ugSevdaDnk=6;IOYvTN^=cSsIZ)2Znc9_tu%bV^%n9gKDfwQore zo8WfBAA}{gA29}TD)B%39>7}=J@(#;iTJBM)CBTL!2oQqAvA48pRXT6$xtVAlc8$C zUEb&7iWcUD5vlgMBQRBP1bq)(MtQav?@+7=ne2DZdx=&D#3AVVPDmvC0px*o~*k6i2_4)U{w_(_>gN zVj!m^bBJY_#nmt(H84Rea);nBxsXm8&7!o&kX}i~kBtXOSqOmi~FB;213UV&1qk;GCMhL~s zo`^d>b;WIr5jB1y`6PAS)5#%cC9n=hHhmeKN^0F3`l=q>VPC8XMvOm!JB4O%1M(`aD4PuXE$%_^}G|ZTlD8 zKS{=QM8qLH^sirRSpO->_^(=$(l$~y_C~_?KUBE?r7D>yuO)%Shs?b!XfUVB{8Qo4 zc%r9h3!w!Ox*_yUBJwkvAEr~Q=4j(2tdBq0E~EAPm$kYpD{8H5!Bqd}UWS9oRc8Bp zy2dYy7x@8?i3o$H069;x9RmP|fYO9aWxHUlvdY(2tLQ)55J>Gy1=<+fa(3Awx2_>{ zO{I}f8UdP4wE`p8YXT&aEDgKLyr;GAx$d=!6fjt!6^M4D-^ll0g2e%k!iMoPH8>{~ zrMhe|v~zS}%vg9$mh&7{oQbxV40{f=DKPw{R_`=>ZBq$HUm)t-NBvm~gE5UceGm3|%(Z|0>ZKpU^1uVMP zH+V~&&cW6vG4&1)XFsKqb1xNjgiH;QpbdloL4GfGqr$QY zA%>1dwMg=>VHtvd%uXQ{F^Wd3g{q>P2=zj=rrDxa<^*2jw)RAMPSX45%if++&>n_dzYVIf?r(B> zzS<&e!1vhEKnFXf13&e>MTY=b{rqI%;lg(j=(*1N4EA1f&~aUM)Ahaip=H8$HTVZ` z_!|Xiuu<2%G=>xyvXXWnMe@qi2qwpgGv+WQtRRRR7g)ISi{s4Iml<-y8FN+nm*a#@ z50C2QF$hboXE_=gwn{Bdi4iF{ld`e2YmE&Q91U8$3=|~BTgUU|AhMRi7p%<5EKWjY z)z9bL1uo0t{8H-8yVN;zLPw z>wu5txl6IeiB>uqaS$&iOIt|v)XTFL2v(`n8y+Z}6#QbsmJ}tW9A!ajr-3eoo3rpE zt@uAK5&5+x#sbnVAccO+s4mp?`Q6Qc2@^(%_-9Qm6vx3Ws7kdYV)fP6a?a=%XGG1W zIKux3ha1he)p8R>2~760EhrQ0s~MEiTt}L52jxh#wwbBm-=mumjbMa#24EnCljz+F zmPN!}egwS@5*{LnCq~MO_jQbF#@j|14HQYX6qDo1D8NG~?Stc^OV-ogguz8Bu5!J!;t*vd8!#rIRC!#~H(8hpTI z#_vsUw&t^8wr~t~$2vO?ynDP9NGVW2%xBfy1Ywx6W}c5jR+n3bWR49nX4NVfj41MB z2=9o$8&pjkH;u84P9r6BHcZ%NH>z98l~PEm-$pBjfL5L@#4vDVx01*1 z+b1JD?xgJPwU67fCMWvcmyB2x9Yc`ugINjsrlyg{<*-R9r-=-tC1FsTJc0wHDTD&U zRVtSHBxhKu%wwqMknu&v0>Y+Gl2#mGB*!{APrWlP0e`W%^%3D^+Sx}dSz!>TTACDZ zjo;}}=LP+oTpev$!jgtH@v|Ve=ulGKoKsgC!q;|Tr%+YgQ^kcD@ISVEsD6Nc){(W-3Np84mnn>-!=%B*Zp0-!_QT{ zBjV~CXw=Y)+z|r9pe=u6&{45N`ck^%6X=({ivj_)9jgPCDTJuTJzqH(NG@~(UZnS- z*-LvP0XkV@kv?bU)P7UV=A+bGeUs*=v(L()t#YIBAw6`B(&5W$)KRzt=PKQc@DYn4 zi;Z2;X>cdln;qciGqjF)wx!`p`2v+?a#^NuqhhJ+RK9;^qp!rcCU0W=D5y#I&iREO z}^DHmLTr8>UGOuebO&?ED(B%K$y zEP0cpmt`dvsoJdDscUG>;!=KE(!^X&Y%n;u)V5`;g&A$X4&TXj81Xu%W)bB{x>^!= zQZIm#-vXW#Uzj!$&>mOXuvB5(fKRDjOV~!rM|>;^AaZ;Fw0 zN+j1mk-Q;_Mtyfox=XBMw??#9zKe*#jU^wkvZt6T*SLa&!g|aSf!ny<6D)A}6(Tn) z@zzmP6_k@JPxvmHQJ{g_!CDw`X~d(l^oMb6;lGiVzrp%c06_gL>6~( zB?G80%wJx%PkgtpK>jf<`3ssYppau~1mF?@!^k$daG+#0Q#2a5th$J)bzs zE|j9QQZC_?SDy{kAz<^kf(_nwYTz`@lAZCq7D-Z8C5;&+365tyaUy~iZ|0f!s?cPO z@p~Au+U3F{BY-#?v-?G)peCsu(dQa{kLn$*M$RenVbkFWqg}Njpz;vp3AWUd5aY6$ zjPxy^u7!l6WVF`n{`#*mtyzU*j5dI0Mj1ZZF>`d!2$mfxm)1r{&vhp(vfmIK9w^br9+vHJL$>B=b6tuo z+{g|Ep4WxCRdCdSL)nDHQJZHvmm54{+Wo;L+> z=&*%nB;?~aPSkaxi^+bDu>W#y`vC>s5GIU--)`hG!p0?Gyinm3#NjDLDF?{rkuxMU z2FS)Wg9euT@`VspRn-9`D0Lx@izmsZWDR&?sI>~p*^&{v6he4IR;?yN_6d6XbBu?t z^<=Yu=g!jP=|u(bSR$6U0<&{P`LoSFT+c3ZNh=r(bviuHqH#%U@Q5EVkKw-7{NlNa zbzn0)!eN`*r#cYIAK&KyCf>2T9QMRCd7l01$qL!AFt#MFDne9xNnqCy4yU{J9d~ml zR_X|YeIuf;GS=z@E!G30JZh|f;!KrTrvFuC;=0kJ+Y)=WCCIoPL1_zRvoVI{)iJ9B zUP#q%hXvFxL{Zt2BJ30={HwFb|4eO;CN~_rD4(V<-m=4r^ns!N?qY&dtb)gQ$r8w!WO_GYsi&mBC#1jWuM*lCAWHF3 zO%7h6H!dwUxFS=G*w4B8F|Q|V)Wi+zx?EuXFfDzB+23^3ry=(019(iU2e&P^Lujkz z7tMNY-5ph9*3ri|0O3(yEvTgQ@%x)pd(U*`*Mqk$aN)MR7X7$ML&2vPBBoEnrhER5 z3-L@>dToc~ZJ$CLp~-e=-3A^v6i;`5g&8gSYIS zuui%uw|!tYx!BJ{xe4kRF;GL!M~2f!>zg*umQNoakDp+FF{p&#hxWmdC!k{<1gYxv zQx)i{b$#_#cAIjS!#A9v$35#Cr+Ts&p{vx2_Roqm7S5?@`oHOeO!Ifntj9;ONK8Zz z$CU*bTN^FF9X457@;hA`>^FCc%5emeG2XD!HLGQ@gK|GOy;PRftK^ooPo&)0W$DUD ze68%?E)LdFd^DCPDcBoe>f1H|MzEsRfojElKwD$$DLkOP*4cw@!t^k&DEfyFPAj(W zwQTZy|`aZ~i@%J1ZedReh zR%+wLE|{YcU!BF6zmJa)Ode0`FpW5m8^uR0wm!cr9eLh+DO@;3gh<@7^bqjRpIXrI z=dXNg7c1L)Qe??ec*zP3#UsK*d(Bskz82ssIlq>tE!1Da^^oKB)gtuZRrJyOY@t=` zBK3B+yVOB1Bfz{ZW7|#R3&K)zJos|SX?H>2=zo;~UB1B!X&MUKYZ8gPA;{nr^B#)T zwcrWU3%8vUu^)(-=ABL`vf$SW)KoXX@D(!i|Nbp7O->}5cAtxUSL8A%Xb06y9uPBR zH!L7xm)sZ3W#$Ji+9G04^+yUGhCIh{n~(tm{#BAi&%I3W0N(5L0)YQC!0{J(W(?eK zyn4)g)d@uREH0XuW}&;91A5IzuLg`Vt043A+%@A8Q0TyizhQ(fwn{R#UZQOxqH`22 z<`2l|?48jwXmGzn0=W;{L|-pZ&xD zQDA)j5~zCm0*c3wmBKoNVPk023Bc>*?*MQ?#)d>uE0@nsz2AERs2a%UkjWyBsdork z2j-xT&j-F3=)M|CY8npW6xm}Q=f~YsMefvgtZ99VPG?33ip*HDY1O50;Q9A0SgH% zUXURK^a1)FWAtj6bUXZ+Jmmd-R!Iy5m4FKIsO;F7?;JJ;xuw?f*HZ zYEYgUi*Da|orK#vBKoA#7lIIOY;kxHaKT*RI%2?07wY1E^t#)sthIlVG{u4fDsiwZ zD?AGFad6D^{AZ@H3?oGBB!P0zo8}sgwA#TgO^4SaE6-Or+ME+2ncsaxmg_9Tb@q%wbXtiwtU34KdU-F=Rj*f2%89Xs`$os=z z?ioB$eDM31J6_x|lJ;mjUnpO{8nHjH_}s*TY({RR@V=I!?K>{|n>}BeGF~|Gv~TyW zlXo~@s?ff7M7Y0ZgH;aSWf(r{@yc(x*?`-_;uf0EheeVvQ^M3_v ze-z_IzQjWFqK^2CUcm5r`>}Su*zmpJ;ceaRGkjFfe3n}3?Bx9RCjdLVp)9r^otV5I z+gH$5dpYPqOno&{Ch^Dbm&c%qjkL$0Ff4f}rRY{KN>boZx>REJcHD=uw++;(RBZHa z{L%gPchXk6RbN2ygXsG#DDbKPL@f1(oY1~_uo#lRLsB^b;oW|xLzp41mKs%% zI;oDF$01`vkSyBtkg|{UK+aH-O8F9ci?QpH$iLDln-&<;NpybA!J{8}>cD+sziIeP>soaSCwES&B*Ba7W)@Kiq(`Fh)`ump*l*!MxO ziZ*jnhG~FRVv{?I35iRSMZbu{IJYl8NZWeICTrw~0}`5JGDGZe;Bi<)DNw=gyv2}4 z+vc<+^%4_nI@469NW>c9x0qte{=PDWHnfepqaa++;K0>|=^ojjc3dYhz4g4Q8yXX6 zb#i+Px(0iwJt&M*?sccqE+YOKY4|e%j?E=o+)Ue&yDf>(ecDmifE}gvd&o|^K3+Ds~UlX_zen>63Gz!W0 zg4#Foq^c^G5A^phGgch&Fk-k&H|K1lT3Ak7SM9RRnUx)9kOEqz>L|(+-5T$L1Q^9N z3)~Pooih{w7Q(#%vDpCWFe#-yf)t$eJXuo*6|TCTMSm}#(aqc2#$-7cq~#Ucp*@jF zVLnK%l-S_08Ufq1f#*bku$=GH1zBQ5PwgAyLma3UJPwR4h)ha0&7*Ul%9N|! zvvaFZy)Cx!cd=R^1R|0LK^ioRCuJ|o`g_=TbW5Z+E|s)EuN2;mJIt&@=@z_aUxK_y z{K;@f3W4emiDU9pLtA>w58^0F`Rzi@5bHRx)j-BaZ8WcV5^>^?2%~ZI z~a;J)yLKlDEPK+f4>1-N1N*s?MhxzsrvzK0G<+ChnvfOpmq`ExQ zEBc_TqhsS!QSMMuUD;h(Oi4o9R1~gK)S4jl<_VRr;UDO=2^f<(TA+J8=QiUxh^(D< zc`ZA9JSyJ?@`SyZHBl@9@d_$I)|^1pi}(g50^4}I+HwP;!7lN8Lf&3dJVeH&Pje0f z({cM~VY29oSZJ(Zlh(5HB=XXHO-)ozf8!)?J##P%DKyE+8Krxm{q6k_;i@?NX`VN?}}zsA}Lm!E%6!=#hD>#3yT=C;WCq+^Y}Smg(hs5i|Ni> zH39&Rp>WPo|JQpUe7z26t;_w8n&)@b&zW8Qh$@=;RFUyJl$a(b zT$Z?!U%GTaZ&k+7u0@IXf)RE(^WcLeJt7ke=BIGO?N1Cj-BUe-;|^*BSzHr}B(UqC zx`t%w37S08kP#2b%^p5B3PlUzpY2;b7r0w2M=a0YsK}fEb~508(XX@;t))2Yt*H=W z$vvDsIBkXjx5BWccTUj#e82Gya^SO~IoZu=mt2{M`bkK>Lvn0n0vUE=s%sM~z6p}} zr7w1HcpnRwB=|+Vp#`|gi04*AbVr*k_%tQLBJrE^Akb9ftUMsBaHy4P4j`>6tJAq0GCUss)2Oj>b zTtmEk`)eWYed-Xfh7J|mYFvp{#+>~2+TS(?d|SdA+HfqZcc>DhXmyv)*$3jL6;PeO zn)fA5F*Tkf`;hE1O3QD!1Bg)$or;a}ub>gQB=M7FBRWFTO>K7c@_f=bOf+@Ay}XJ92*I(^W>B*Q4y|=yBe(yjZRQ=+)=%cuj}x zB{MS07*Mu)A7(A;p*eR_IZTOidaaz*>@q~08+#zaY+=jtX}DO_wsOk~3s(WH@nwaG97m*=K%l8h5OR>zWWji1T%}&zE^Py4{gWnLB|JjnZT5=Nj;_Z zu0&f<=PkMBr)x->B_$|S&F_5J-$r#oxO|0mCFQ{8i|CKcQ88nB(QQDNXH$Mx1$#d7 z&8(oC7xPRk*^3p&-Qi;L6@#!JxZd4lbM0>VA~z+K?d=dq2G`*1>6D)P9%s0V$-}5x ziTB@DGbp6rk7KMS8T=k2ZUXf`vnteW?31qJjEAWVtVW7EpnTypZ=*{f9E=<3b|rdF zY06aQaU4#_SrINilg^!J(#s?Fv3;0AhCs5o+bgeHjDurpi#y9Mxl4*lxcYx(G zT7tYTzY=$Z;Du$nlCG%q1qpPe?E&EK=JI5_WOtC~lIuN#Go_8{u3)f5i@=fY%(OUU zT2ME^VU`D~YMIo~R^mY)NS~3ibHf_XfL0X(9~g&Iq=43Aw*L5uF*g&}7`jn1&cm*) z-LPy=Q@DFCdz%_>$XIdB7ug!^3?&&gBavV=l}tqquSScOKGwDNoQ^U)1uz?ii*5dy z+?fMggZ6%nkTWCCp&6X)`6_f`IGda z_hYyGd{o$B3gxoJ8$0cz5=uy?{GRn1H#7^Qww~dJ^%9haq_3j}eDbnOo%4fP@6xi*x6L!o?>>M?{ z2*UaKSjn93GiM>l7kl|f+4FBC_kJtuP&`dI$G06zyUtG!)6-%!JRfqqf%AFfH+@?s zUO>_&mOX>K&4esFb^}@bqQHtmpBJEUA04P~(W{7lZL$|8T@i5ZNgsIsfK}`kfuQC; zD*0-J{|T((_&)$O%xnzJ4D>Aj#UWBKvi{M^C!+ti^F?Bk)D-o zhcB6Gh#zUlDj%U8;Aojk{mn02@raeRmms(Po?(ya%@k<~3@6p8Kf613I45a*_u${fua3Sc|Htu89~V`%`UU#{AUm zBihsDYdl^6$6D&!U$jRf9SJ3RO8PM8JS?7;kPAbkLyZK!+PqV9GiR3O8KV_rkoUq*|8-|2Psr95-a1@|rs-&?ATU%zjRi=lO0$Yi-kgw=I(Z7ROF#G;*e zWQQS)P~R~U;X(&)sniaA%`nJZNZ>u|l#jte?WGldG7b!NNdn?TPyNxW3s^5ph=Rh0 z1om!?4L=uz+Ed7jWPk9He9O4ux0xI6$_p9bpESn&ntRAt%+#C)eS^{z`EwzQcL=H!*p*Lb#Q6 zo2|afT|$SHLb!l+%w+&Hw;`6YFNpW96HHWj?1UHdV;+xBtghQ~pX;jk5`8eY1{{dZ!dnxP!sGCDzp-q8BQ{N?#*T5W2G`#??yy1L_N8|K7V^ zvbjNYJ^VB3`qX3V*vka()8kp?7xfEU(D98j^tc_#*rFQ7R?=>UrYeKuC=0a!NswEO z(W5l<=1FKzY&;`FM)VFpw9-hJcr`S8?C5xzOi;KT@{aIMsG|=s5Q1jdjyc zdwUJ3MQhci`OG@?vtN+vwOD&Ob#|Ao2PUTcsizHt$uSuA^5}7epF#Vmgf&B^(?v!y zG*NT7cKf^qntG+ShJe&r2eU45y>b=j>JdtYCM)rn7X-}WmsR(%Vf>kBX>*~+g{05Y zlQof{<*S;#$(^wh1h`N-6Zl)^Th zM0F&Nppy)bz@MYyjEv2-?R6uxwaTgrKeFtmIvgf~_r2V!M>fg9BNMhdC~2O3SuY=7 z+ve5Qh(0=ZGXe)W8v?A^D~N->AGIG>ou!;ShfdGzAlK$gshmm5JscN_>4%_x0-ar8 z(#8e1yFpBKOiYu^G<6pa39RhcVzXHmbVUdlG`cji5Yv|U0#p`B6hwo=)D9iQTgToe zE)8F)EAI190RIHQPocLDRptQcYZA1u)0${*o+T{ILw*Bo)TDvAErk&sMEx1zKn*H5 zm`WIhGZR?P(&T0<-i;CYc~eKX&~2nocD?DYakKX6eC{?l5AV~nEPliD3>-)y>FX?N zKYGf{CavZ!qkd2rjjX{4vvC0i%r?nKRgJFhn5Jh=zr#ASz-1^@&?kd%UlI)EJrJPs znzg^70lt+h#=4x&=q1CLKo+%AJ?#X`e}}-g7;kuZbhENY;#Ss%Z;rt;OMFas$f7XV z{`!N0-p2Ya$HrNS0IR@g3WOap!T1VZa_GE2VAt;$<0S``L4=F6Ppz9VxZY!LE%%vA zXtXv=4%ImuFXRO6<6hP~lt4|v89KX(t^czQ=w~pUw z9(VL$3yerc zi*QqTbNBGakoNnHSHUmsIm1--KUgTDh=$Uy;1m>(yGuAI6cM>o&qLI;c3eRSuvz8J z8TTR@<0A7=*J~m=^Kd!E{nU_v`<3OPkAN>F=#&O^_d;*+5)1*Y+o-K9KinS6gCto3lT3@+l5npp`q(S|UP{yMb6(&^?|>Ybh3oC7!S zvq}cth)f?i$szqFpqTzlSM30uNLbPmiP;#RPCs!Bp)#wXsvkDSt>~1thF*5=Eeu2d zh!c29CduXmsv%(y&X-i`hJk9*J_4eyO)fy0){3 zm#zz*1-G}!Bg>qYnoeP4ZkI{tZ?~DV!6Pi&p#0n+2pQ5*pCR73*3K-6siB~ ze)mIx_#ffnzc)Dr4H={#)vF@Qc1LpMa@Src5IkV>jh*yTdIZ2B)sWf(lDj`e>+u|Q zne_DvA>ZQJOgt|@A96$W3hKC$IVn<8R@1LjPTt?IuTVXpxIwBJgPY(&8{xKiaQsvd zg74KX&D%Ivog15|C5=3z1{lTi&-+dF;?L=T_Zq?`(&o#tr!m0d(}~Jgfjz;C%KD(S zBn}k}Mhy*NbuUEW@rtp|w;pFrQucyXZe80Nuf)uC&tXhzrx8|FPQZTD^ZSO2NplUX z*p8!DzKQcV-jrb#oXC z{TR;hlPFbt{d(r_=|?E$6*>@gcF}1vzgWK5TfbY9hKPek95Ai$uU9l=gLhN_io(h8 z4SB}Zdwn|W1tpJH?mz*IQ<9gl8vFLIQ(liYDI^Jxc5J=%QvUHv96(V7pw${=4jL`Q ztg3hUi>1m2;yuI_P0Ql_`-KC5`t`37oU6kD9RO9`A?i0;%jM_w$GWd zn`iAUQ13E?=_nYLM^8FoFobR_b@NMikJYu$G3`IAhIN(3_kW)n|5dk4*51a|?SC?- z{>}WTRDp8DR>Jr)u3z1}l3sIsCtwN$cpLFp_v4xai<_BSAt{w2E1=$SbcuuBoS zHyhLVqunK|m;;F{YaoOWKmr5)2%z{!4j4rdSP_{|?k3PZ>hawKZ;I_6?o~WuRE#MG~C#$M!OCgGht3|AmSNt#`78 z*iWOD((mV>Lky?iizhH<7yJO45jO0e1j58{6})rsjS;(Z@yT1*L>FeC7QQESM7v#d z%9B&9Pj$>Y{|X^$G%!78-xgiepep$D_$V0vi!eCc*h4P-Q{b(XCuN9D@J%M2GWc>o zq$d^!vfy%NIow%of%W5Ho924MTM~JRsgzn&xyF?+cPc${0$ha{dsW1_0*gqYRBwVW zO~2FVHJPa@nheYU6(O@Jhw<2))x53#dZsFu8D)Pt8Vyq)VY+QrhU+ z`c`DcS|sF0Wht;#M$=S7MASr&a{tv*GYO0xHOg{47CGP7G3uvvw^(>OEZ;chra0T@ z8%uxDWr#nNddT|^MipV_me zh*WGe*7~9*#WH`~WIf7~w1&;NO+>~=LH)?wd$>mxnJM)wg%4`H3BMtmQy^@>&n@<< z>N-siuuJoLs{f0ycM1|M*t&Gfwr$(CZQHiB%eHOXwr$(Cy{qp2yE{5=znt^7BG%hl znUOQ+{KgnVcCweT#JkgzP*d$@OslnJXWlwf!*!4wTM4t~^*zf0CrN*(jkL|V>>y)P zz83&KPfxy*qqp)JXP#Uo!G~qn-Ml3ao z4rN@bB%nF5&p;l^BmchJA;eX9;K+kK@S^UGB~khMi(B*qm3aadsd3ubpRGE_v||s$ ztMY{4S9oB}QKUbyDHLwi|7a3XQtNgcV}%)#j6BEia-i5 zm)MHxh$@ZCkHna(@`UAqJ~*TH^*;%ID~&*VFovh8d_(oAJz#fF_oww|NA69koebcW zzvooT=Y;cv<`WkFqGlHzzImvQSaXo0Q=Zz^n!6o=ps-ofb{dbi5d7pH#(C(DSv!2>t$DrSTAWt88oqbiaw+j&wXu7^lCWnwst=XLXD^&_is9>+5UlHPd5ui4 z9f74CBdm*}X-COc8H_pn%%~Bcl4>3C&y{0lg~E~^ImG2M9hWstLs`cC6b@z02%t&6 zzxcp7g^ul>Afu5`kH=a*;iVy~clU&kiiCtVF%P%hk=;P*FnVp>=9&{BuVXs=+qq;2 z(}9=ECaL}QBjY1?EHu%+5YqzI^NNP2q*Z(s=~M+_>l}H{*&rBJENHHM+qhWsf#5nzWtt7JB}pzjT3fo@ z)YfWZ4S)Y}+QUvZK27Yd>^MX3wn$%lKV*c)?+L&UH%4h;_-lE>k8egyRg?2n?&5B5 z5_E<^CXc-<-kJKFc>Lm=t;r5mQtJ!vpf2~zshw6+evhYVoO-<0M9x?8r)7;b`jCN86?S(J0KkK) z3v0|Fc{J9j83)dpewsr~>LZhu8SM zA9)DeO=@+L=NBZ}KnHz(aD*W}fzPb}SPBUf=KjOv0H_!Wb32?kA>SR)sgBSOx~a)O z{`v$nVlX7+Tkrg%c3)>!HCD6M_V{t4i79Pjj6&I=fekw*^EFf)(GElKMo#aa9!^*M z$QPs#n!E62!-Sn-DJJpA%rNrs=ei2MG+H=kr=OAZx@v&pMB;59#~xjHOSgH4&pG zzHTGBbkw2713>Ie1Ri_j+qHE#o;*eN{KC7!#|?+j>QmdXh*&Klw69@w?((@lSKw(5 za!0D{G1eQ|Kgt2(dh2`xH+qhtZpu!rm0Oeh?jWQ+tpcCA(rqFzOmdFCRbi0wNYtIL zfHnLkTBM;)7*v1nFm`-hsWtFHx7R7xKFy<}ki63gh5Rl{9rN_pN>E`V@&K5Ax~jSz zRk`+_atJ(^FZ{QM)7O5F-DiJyuwn;vkF6mZ@az4~aI+o%5tkiXesQcUy~f-DC6_ca z*BB;O99WNpNss7J&#b~Dq~xBJ=*o4{GibMWV(BIih6@Zrp^uq(BqbVpm@ryQO z+-5>_R2+Nu?X%y5M}X#R$}qafCCZ61=%|I7AWABvOk{@XSmeutJ47$|M~8dKf%y|i z`F~qDUz)LUQ$PU#fTR4U+bhF=y}kZV9ja{V;_~kn>-@hjuqEn{J}4)szjN1iZcP~^ zS)hRd4qo*eJN2NHqCgf9fM~+`8xWv1Og5qQ?c&)v01Z@DH8nleHN5kiT3b@uwy3NT z;e|c*Ev>sPFP8;9^4iw+TW@A&Wg?{@i)r{qDZS+T(j3^%4W1L9qJL zj09+92he*yoM_1ms((8iu<3Q|MAdyBu(tM{k~@JXabGzgxIb*}$lMw-O`1eca3p#6 za2${Q;h3&|dny1=$9XssVte=YKjp1IlE|O1X*9c@z@WrX_F5<{~0kO`0|}(j;x;PLV%pY|K=8Y~cOSV9HTy z)SC9q7xt%bQcD0wVWrP+Fi-2&j)k?ZaIxv(5y@(aST;~w4OJEG&s^Lw9W~dQg&Rf6 z%$$UCLt%U_e#`_OgZf0C&!z-SP+*B+gX}LfE^_A)eeBK%PF!Y$(gyWlvUc{A6{y$Y zwYQtDXr>$nZD)D_WMXVmoIQIxR>_nmk=Usz?{N|%x+hG9=jUdoby@XLy_vo(+O7m2H}D9YT@K8(W+ap36F z3SXfxa`y4OdL)CT(()9bgJ@C3O~g|rYydjNzpLJH(5KQ52T?DNF)BzsMo}{=s8Nlq zn#dCGG08+!NrFrimhpH3{TG^X@}*kodbdp4phT=O@o)Gr^d1{>xDtu82=669GS*FQ zA8iyVfqT`UluxJseS+Os3fsI;LIq61M_P8#`-MaEXQ>q%eUwwe48DpIa7u<%Q#2}P zX-&CCAfVP>tRdLLh@@)5yX%cCg)j!h(rwq6I)8&nS<1w3UlxXdzRXY zr;C_efRm6swN3>az^8^<9Er@IQch56L#NI;$G8AF?A76VoU#*^|4g7jnFVz*zg&Iz z#@fD6czF^SIFxBIF9oy7ye%8=G%;Py(GA3=u)QW(Z9btu2$lClWI0iyabB&bG>h$K zrEWp54Ctc~*jfnnqpG_h)tKT`DNEvc-DQpzFl(;N*bR>_)17M*n`?K1YGIC#FVSl# zyjDj|`E@a-m1}_AojZD+#!UYTprc=xRKvcJz-6-mA^vJnYSH%yHYg<0v=^&1coSz2 z7S1+6%WCNgwRB~{#gWib0af5a>_5??U9bh{b?sSgT%l0(ma;=QDg z)S&MG?E%>U@qw9-oWT3AaoKPUcI#bX|0+J#GH7NO7xE7Jus8BfPlSh`kMbKR_NSWb zn`1yu|3=Cb%tWQk+EfeGad**Ma$>H4u7icfm5g#9Y^V)wa7Wag7fBr@<}K)TqKRF2 zBCXDLJIpe!V^|5t)Fa7KqztSG6&wIiyb7wOa=RW^NnVX5I)16fvjwNF1cAz^r&2@v zPmYxxygU9*rB*GX+1<(6sz?|t1v>1KH5Fg_OodchcHMIJhr6sVMNXkK6zBC=jaEbYaITd5lmL~&uMoR1-u~7zk5#F* z$QJ%p*_K!Y%Y+?}K&JYQPhb_J^Zft-8i1*K!O+@&f;`HA9ejGTRC6Yj1_W+2~iJnY8 zKR1r6@Q$b_EfJianEDm*atd)2RU@2w;!Hh3zm6>WZUnSltj(k~V4=|@%XEUxrjRw^ zH0uFwsT3oo`;749Femj8>(2w1ZoUaaIuNKG$LT>f9gGEZ*ScE(Ec%93fGpV}$|^2P zh!pG}&>>`~(?RiPMx-x}Zx5gt52U0A6s>!f8(!hJN1KF4HtCNJjyXWjzc*~hbsR)~ zd4@St_Xi8m6dgc0>$ zHWI;>_YgIx@h}Rd^=6kja1vOye27M|5@3{wI6jLSp(dz=n!13JkxuEXcTUfe{kKWZ zxCuJv*GU4HNGb6asPV;hcQDerl98@jT+`3!{Xh8>z(?@WrlD&pFI^B%)bKdJ&goRcDSxAmkG& z%_UZxEl~6X1Ux1hsRUZwF}hq&Xj322t_Sp#Kf)`%#S({6y>kn)UFLM;P1NWUHl%k% z&S+kPi*9IdDRUjCbL!p5I`E#GougpO5wjG?!4MJ13pBH%)fzOz8V3<<0n^1-^<^Tj z=A}kbadGm&93f|POq7yxE$lX{mVkGJzn+y?17hdVF=HyWQRLu~^yMJioXO-J)65cX zu^UkF9KpU1WmqDc7(}y+fVE7*>j7j}3?V+Rk#G^_z+41)j4`$$FKTQCF&K&r-0oE# zXDq)e_#I{W{7d(Fj0e!k1YW>xJx&YMY=o0A23Q(!n}#(MJ*Hdlr`aCDzZuwBpjv`M z6v@v+x50@A;>}@fuZqO&mYm@_L0b1!oOh92X|H2C(dk_A1%T&3b35Q$;|P6#W3F2S z+Cv1`Wc_s{*#R99cTSC*wlT}m(}+oOL(119Ko6y8kh&T~bYkEfVb#K~97@~qszzWn zh+hlDW%A{(*I>Egfas-Y$!oeC0RQS2>|G#5f*98fX%Q#U3?X-ZU2MocOL@hIt00nP zk$aeBBi!3r4I628R5YBlQE(??AB8;QX?1N@qPQn{fHm?sq5Op363hxDVsHkBhle5D z*!p28!x!b`azA;$KF39K(!B*?=GRxh?+9x@6plV|J&_6>fDJtha2lr zJ2pnWuc;Dx265n7PLwNu{&^u@%ADJ_`M`4-Zq9F4?r-jhnR^B~7lnGi9WH;BXy15i z-SCl^q=Cm@K6=l_U78lfAc|BD(W>)KmQB7TuqisXC}k0=o+VE?SfJ2I{yf6?g!OAzRo_>|g&Lj1=fibrTM-q?Quu@U>>W z?)b5i;q9tsxj*_BzWrU?bXrRX%Id!=}^EbBK^CL)G3Y?;@oePBR) zgLbb4SZB=<_Js8>3-17k&Z<3_9pv>f+3K2{y^_gwHK;`lWpu}|18et~A?JiiI;LdS zsGdb5lSW-bCbdl?Rg)$ajSeb1pSaSFzwpwm@AC~&waqsFU+hYTB+{!@!`@xkp8zMd ze61c#FyH{=U;cvrhhLbVH)yQA`y*Gq*XQp+*DK1>+%hTI3l}WdCNqh(s;gQ$het|f zltsLi+p!_~Aifk#<=XR9&9}`@R_P1ZIVO{(9wG+Hlr^Q+16G?J)A`L>rQ8w|XKJPW zeKk(9wIwEs@60s?H#A1#l;>SWo0E-D<8^AWoi3Zs*nS&vEc>>YOljUCVIXDP4w@C! ziwZZ{6-z@~4ga;p9Md4BSwuGNW&+uA%8Sj(O)AG<2_-xxQ*n3M%KeG=>sGl6ojNnh zuq3>9bLTCkSexNuP}{Dh)9upY%$H8eETAsglLY`B?krEQaeX5!pFguk;J6cpIE4I> z%pB6aBJP4Y+XC2d9Z~Lx@$Qb;e;xsM$H0&A59#=belha)l^^HsL2r}%LhkN)Kj7aX z`ICMF^&hZ5?mU9WjyZYc$M|N$^1S{3EYB`5hyEQ}1;inlJ3_cX;w6pT5{`9x_+P`E zK#9(Jt$#DVU(o-wbN?$W`2X%)VHLvCvC00aV(vb-4yJQn9&Fk`OlV(=m80ej@$0@qDf)9z0krYG^heuMA zecBzaViXwc8A~|@go>hrx-fWXV6B+?Np9d5)@M0G^3kO3R2D|^Ej|tS{BPcEZu|`K z7^~Q<%(RBbmZg>P{2ZR#pY)#nBSWT9zvwHL#LqU*R*B9aWW1bxr=pKB(E{$jSy6@~ zXtaVcxkkCUWYj6c1Q4bK5gq;qJU5@sNfxRvtL74)j7-p*k`#$EN-)Rl6o{)JWTC1$ z2sZ8EQiBX7sthVG!V+QearH*6|DbeS!Y{POj&SBFlsb}b>|vM>T&PEHloNQ0DQK1B zIE^&^5pz|FT7k|r#Te(RDP?J)5izGr$^kC z=DH+4gBXQaUk#%k5+tdPy#F~;w5cyn8UG2)H~u4w_g}j^|IfnwKiwTJNDq~jm9yQq z#0(idwQ(tbK%!ttA&4x5)oO%kF(fw@nZz^`2Iiz$83+Q6E2SE3ZT4s_ZCl&wLYfo+ zCBYG+7OgF-ol4sqvntm*wW_}Fv+cLjnJh^OGSXOD-Z#12pT`4a0EKCG z&2=SeZM3n}CR8?#Nh#XuX)wlW9=OPc${;F)PiS zkd-ZhkQ8lA;1+9}_;IX?HIpEcRT=Bm#Y0t%HG&BJv)=P^$m9o+?K~*ERVp{T~T_sWcR{Y9|3)ESRWB7JK{Hg z)mr1g@blBaYi#&2?*wpgjKL!UgxPR@DnfWg=wnzO7#ug{4C4C{fy5zki0>H!jzClj z-S>J6)$K3l9Kz`m z4e6N?sCe~I(f4dyx>NrPb2!=6^L$0BhBW^vnfx8JLbTH)j+BL=x^ z_{0%3m2rG7O36OTyw;c?&3ntyRVikwX!WI2TUEcQsYRQ#p~rUi*0nuz_eGF%{zRyc z5+jJiabNSHCYkt?F zN|U&bY)qL^%&O(1J(+OLk_=ysfQVy=@{?K; zLMvMm?~&rr&I{g7U{ldb%;|kFt+22G95b$F;%kZK4&uDHQgZ?mI?--L9O>1StZy;B zjQ}E%Sof%e6hsG}M0rs6jOlRV2rdpIxSVo-7=)s+5`Kn)ojX`I%=;Lk9ISoAT%iO1;6gk7ceI^kLx+)t_+b%kv`&$O~WXWOnCh zZHysRH(6LZd&Per=F_K#x1C>YEo(_y%R*}1Bf65YK(uF8^xJLa>=Gh0e@aUhz^O@`rLgRyE(_9n$vX2;rJAWodbQzUo!qPm(7-#F=i#Q zhkl7AFn=k=s| zkk_`zWW}PNuB@zwdt4y&l}!e&)wQzVn}g3@VqNK#It~ZVIUX_9v3#6O1twL=DyWoZ zxp@2X*@$_=VYV>`ux0to`L_BF_WAj6Gnn9kCb054*Le)1;l^TDJ;0PI z7(a=u!y5I}-MLY{NK5d%>BU6t&DHzyAQl_nIRC!7vHJ5=-ngZK_m#Wlk#Wro>P6@p z=GFgFOwaPEuA4(BK>n((pWP=8_8R<}8|qWtrMLw1+-o8Rk$@`cf($e73+ zsNtC(u!W2aWxoizef8U zeFo6whCtB({*RiOQ)v%Od;$@Kg4NJfu}AklS0`5GDfC@f)e?^Wr~b_3LF_Qx zun8PY@@O1HnrE}&319)b0AZTYqhz5^&{KwtCXSDm>sOY{b|jG#WNutpZ?0Y6y@Xot z!3~9=>)WXVn^#}Ki>JktajDX|}R*NHK&|WPA_L#%502j1?)J zf35&2UC5LyIUWbhYvUf)3e%(9_ko^MediorbJ1c7O08Z^1!31oV#a8=xrTG`WPDfL zudmQOCreLYM5%v*OhKR^VE`B4c|7F&!6Ox_jKY^k-{0c`Gvfbm*w|p%o_^Ah z0Yet65k=ucsBdyW3Z*YosyCQM<%3B^*PG3aVUpJ)rT7k2uvfo~Q5_zL^_JAS)3XDp zF5gy3xm71WVzRM?CZK#?wuaOdl9o8njG{L>g~|a)PTMVXkkUOls7~dBO0DF(-Fi{LmH{H4EM zIbVWuGmB4s5A7j!aPl{;VUSD=Nayt0TlSGL7Nb$rcw|uOY&!ma3+* zR%2tSC&~*}g!1rDpE2hO<2-_J!>h7vaxTHe%T=7N^I*a7$Vw7)Qk0`6-ZK`>r1X;X zxZL8Jf{jHrl|@ahMTL!hg{@tArA4%YXM2Fl!#&L9?WF?mC3fJj#v>g1d}+&=lNRbb zVrbo8^@3R)_jye2fjJ5q+O>?#4sDlIp|qfa*cRwgi#Nh1e1|9w7ek1$*bE)hGWuGr zO}TRg30*{Hi#?=VNv)A#XnFFe-tN;*a~&x+S@iTb8S$gs^<(QE0A=}c^RzNVB5Brs zNYmKK`6To-b#t<`bTK7`_T?dvO~=+{EQOOx(0 zUpanEQQzOzj&Gvmt%zdKmi68dS$hp>HO=eP+(8r?kRh&!)tiX9DQ`3P2X4%FbqgTU=lKK1;Xs@098D6?5uc4xahesyMN zI}^3Dtg04@<-MXlVAxWJsI{<*(G6KTHC`Pg{4LweV;lRp_Lnt3wW4bhSEbpQd+;Ok zw)9rJl?WjXU5vq5|M9SaKSJv*TKHof6~f|*Xgt%)1wlo+JcW>ZWOnur?cOMf%ludH7e(GwCd%M3!9cO=Y2mJtf7CZ5C(7{1GP8on!aX@(oX>bNjX zPDFpK=zO2h`VvR2-f|4Wh#gP>4*i#IuwFTGhDE+8c)(!r(ElpOOSwlE`eEgw(Bl0O zi2^5I-~*nEd{qaUv(fp&`Nlf1zn_6+@&!!4kU04W6W{`BJmMI(;Q?w08wk{;b~}O# znn~b?cnA~Zq)_;aX2>;6kPXk~Ab^EJFm)z`M-zND!XAL4=f4LSz8iIqlxT9#)Lodw z7ky=FBaJIgU6 zobGS!3`Zm+pn@i`tm#ak3_$HrjV3CZ9*3k(;zn>Lsn=-mCGB%ny*1%nXU;R-AWo=ms##setyin7wsQ>b5`K^ll5qrwmV2>wyuM4P+vaYT<0qXu;Z% zDu^`bO0h(i-2uwk3t(;+LOBn%Bq)m6nUBzENavw2ibny6PZOed{0H31pzL1{TBVdY zg?&B?W45_JZ-IVXM>VwL2gq-Q^m=T=UdCD^HFk) zK*m{y52k}+oRcIR1~NVZ8hL@ed`5(k30APQ$QW2Bx`|FukZwd%y`STq49c5UCP;fe z?zK>S$Lg^}D5yi|9h-~g_Rb}zx=Ay@o<(|r7v!&**SNCn;g+t%g&nfkNPqeH8N233`V%vz=xUyhS}(04X zUo1#tUy{)?#3Se;10QpeXwU=>DK9ds6$bPdA!V@l>cDrAg31*I z2T&7ue!JR~(#QY}EBKOfKthRwl2}gBJ;bytic#`h(QHHicM&GcAE7&Rn*>QRpk6i!RpX|8@YaX9}mbZf+Aw;4H z$uXhHG53gv%f;XC*Irrp1?*-)9%z1OJ&2}*?-2!Uh75G!!yI^wr8%fYqep)GOHIbp zvBMmYjBrh&1EUdJ56yJz>H zLPEDVU>`z4bQ$qQBOBX_3BUMumpHa^N+9BL2jQ(Vd4O{KIxz%Gg%TO51REtq38px* z{!9z>ro;sF5h8jau(lD>Pw>l@+%hoS z`Jx+-2FW%3_f$B+O0<(u6=)d$oZ4JK+4G#1DkJwRrEFDI*DKdM2emvk2aM|*@kf{V zTBVMPuoxw#$X_19G?(V- z(t{IM^S4_Fn#3fGtPOd#04{8hP3mbGB5X%2)D7{jg8wOsR2pp+Mmh^JUi!IKp|>>f zulpaO*6G$~Ui(L`k=lcG;nW+c547A^w+CxOv^U)M;oOL~N9+Ot-KcrS?ZS$#&-`Y?T#tbj$xMj6sK`ko(iJBX2S}z6ALsK(ZiMkTtL+KPeJ1KG_-!nL&Fs zbjxp=&&!jvZg9ts^NFDP7$Nbl#}=0*pP5*9?4L&mT};Ev#kJbA~*Kk+pHOqtxo!NEz(%q<$? z9eoKV5nD~Sf;r1)xp_I_g}BlF4W1y#PMQlw^?^%%6m`JU2V(UBwK*{*^Ynu8^a@QN zx78S_`0El#q{gMh9bra6#4^HKbhtX?(aUKyQi2^UccEC12nkzESn8$JV`LROU?YFIHkg6xiexWr#!ZmWWdQUh1ot*X z(~Eohlv5vm7fR(zS$(Wt_*xqZ`|Y*l+q{5aQIxx9W+*nD{|<#ryM%Bf_6(`j5iZgt z3vI1$JCL+4y{qhSXqR5ecnOciArP_`A$Y!Gi*59Wip*f2o$$(gLC_BX^4m`0;7x$4 z554jIZ+-k7dqd~AfosC76%a~2%_i57#*7*Avn-1qzw0e0$X3Esui!dkRJX=R7@Hm! zv07Fx*k4WlNoPP_%0+EyZ~}7CPk=0z8(KzDFMMohR!#}WHO2OGf5KauYS93AA!a|2 z8V4Y@r?G;Nyg;=d9G83jpr}3wyC0kCrnvnP zAYa{nX^`(w|FqjAVNbPei;paXp}jz;AGqq%J7M5oh}8#q1L$9vmIqK5Ndu@(+fbFQ zKy#!|cM#oFaTnsKo*Smfif>~F&afA)X~RVK`F+Ipz-$(=O>z50#&@zEc-@FELH=Ro z7pD~fjf%giXsPN)a`;ACAQ>hjClB#7q(Y&|K$=QiGAWG)oyowSiMVLeOZhsJL8?lC z)d`U@xmzX>^Tp5%sF5*+bF-!A1+GDKlQcO;)*xfo{;eryCt2-!d+?6KH!Uro#|BCi zno`gNa#|pei%1fQQVCs96!Fuf=QKfCnuY0R7V*w5c0#5vG>U3hZRR#qd`p2ojXmi= z4o#swV+UL?4_8+TM|)-pMCKD?``pQMP!(^wV%@33CL;!+6cIC#ynjw(s@IWSa-2_3 z2CLTv+YR@poi*HdJpiO-Yxb9&#%2b#9j7G1Mtd;4L$u;WRdRJi7>roAYV*#?9xp)>8MlcnU!<2MVmF8x=O(3d6b%F|i}gO*`ql;B+?_#h;D z>XkR)^wZo1OczBRVq6%vY5oXPw1F3OAy~6XNi>|FXl0-TQPw7(G&;uzt*EF+LN$Tq zsgGzj3r5SLhi+J7nAO>(i&bZ~cmnb~S)Hw0KPPqAFs<$qjy5)7dij)hD$62xYB`r2 ze-q*re|S>i-j!6%&((!EF19U<*)w>~#$zFjNUt$5Bu)<{6^J%Xehc3r2*O=_h z8y4`3dUXjjVdKg$LAzEZkf^zgk~o*f_lDhm|EZUB4OjS125F; zGSBg{CF9z4ffmg9xa$N-KIT&B4DnPTb|nD_h3nl+|mPwHQI8v~eR8TP0H= zxLkvzCbj5zd=KLEhEaLLB9odMsB?jt^jV6{BfGZ3j#;&n{|Oa(b{w0)`LT*1mn$x( zCnBdOD5obZw<{p`6PewO$x0pqMxJ-b4eC{;*82w@o-yn|&Qfz=6zRi}<=~C79ex1* zHXveo*A>1P6(_I@{2;8EAn%%rekxHOR)A-;&xeZol_VEC=>?dX4ks8tf#%Hsch-=H z1|3m5)LSltP!%%On4l+$@e7cwC61xu56n@CJfZd{4$fkl0?ih~6Ggp2J+ zQ4s?H+zF`AU_9usY#$FOdyY?d3N(QrU7(9+tmIP$*o#b2c!arg3pDblK3C4E)1RQK7^*)?d5E(4;{ z#S`*o+Qb%c0zn<@><`}17B^XTP^TE{P9_O4-^u#G8i1;9sKn!yc$zh#%5E^xJpkon zXaeqP?Bq#1VcuktAaxhhPLT?Rt$2$7LPf~g0vE#C zK8Z}hcKX9h(O1FlYxMRO63p(O!)N+cu3R@==8fCO`@PpG~Hg8e-ge%(sbO5z3u>6(fbsQf-pBc7EF15I-)6FkBgAi(gB`*Dr8G2i}+)cuCU5 zR3GBSPE4c|ZG-IXxWyef&!va&t*n}%`?E^p#ps|OksB8A` zZq$rl`2QK4wQ@zXY+(TaFbVvpi7w55!=jbtBqdC398CX@FfT{_%N=`nvjEHJdnuhGCq{~Jj;hPrc#-9T*fO!ybAim#@~IGB zN?IGH#zAOE((jV?O44Uo=aOHzU#38%V9B@|MzC zJY^Xh?KN|!&(YX*3K%K#$!v|Kr*xa0!C&?@ylA*(f@MjoJI!|V7p)FwGMBg6ti%On zu?>AI#fvs3Ksu%pkr3G z+jew%aN+XQXzDn>Y-QG(LzWhrNK+-T=^zaZ29Lr-zOtlduIsuQV538sQZ{1YqIQ`S zC9GU}V9>y2txvW*jkd*Pz95H_Ti~XJNR6LQSlQ`mk*0B=1A9IRBV{?CqRC`LE7$*) z+SF=h{tPBmT2i80Pj{#^BF9UqpV;zF>S?XXdAM;qOrz?J<)xZEP^Wr5 zfJE&Z4YQG9wR|3`Jk(BCdqCt%ouB^XRG|4Icz}$V_s^f2)PCh6@c|pPZ{#j=KPAi0 zXJLHi{Mw5bMq7WB$voz|um-ZKS2IR1Z)2zI@U1=n5Wcg6ja+neoov~=(v`d~uacpIKU=`C(>ERs(!wE`Nd#EaAUd21k znkrAIxazlXvFrV;R$B0vT?L0F2j*!^iu%gQ+nS|8%Gp3wYGrEctggVm5;wmR_>)~v za$SI#GJj6K_{?;DE;&(~p-Xq`(elmIfP_%?i$9z2VNL>|L_31jz`03O4bU^&pYqoGy6NW1jR`-zM*zzTULcX{L%g%U`xm z&84eW)SMc>vhk+Wo41XCt?SBU#e_#l;kg|_0;!9~W$`L6^%W#z>G|M`TII1rtBJ@g ztNLB5p5xZNWJI;ONHXL@-K+B!J*nY~64tvgovCU3mX_#PzFwzFA7?v%qFXcxj0dwg zhgs^NIYM90Fvk;XpGfCq4!dx@pytDh+e7;z^6L@1pUPe!F~(6v#G6E|K@a|yVRM3Q zgm0jL3jvOFy^+u=3z(?`1;u5N1SixPAf3m4?e|s~CM$9Ye%)wiv|}y!0Z(4kjGIE~ zgZ39FEXWc$@IsN!vq!90Zz_&fBYM0yjz>FcCmw0@z>{&;W*KpNoue%q7pJk9hyGau zbB8HUo81LWoQ)nsi=|N2=0BmYU^w2K6uR$wexbo-{$~|YD*lj%Wc4X+^2tZS9LJuw zMYC$3=(!=Q5JgM}j^X=~I0SVf33>FMmD!0w$@gT`cI=X=usGbc`J9(`?iQ$qcAiHK zS)PhKIg~cTjC0;;_CY8c{oY8snq0%&*TmAg@tAu3u|LSTX9zl&pXh#S3m+PH;_276 zSA22gMW8MrceLaU{`X0xev_xW>|-){rQ)!Tk_LG*h*t>CfDRid?G=dTJ~UUH z9D@Ajm^MUv{%}tni1LJ`b@#+E8!nC^7`zVv5h(#~(c?a!Df;m}lLl6;J5pk{A6vH7A9{`F z;{%`IezrV9sq39gV(WM!2YGa5*9iLNk;%96yBu-k4JY`N`Vc6O09Vu+y#on>UvRY^ zN{ZmBdt(;cgfBuIVV?B5CC>$pzazqH54QDOdcOYtFY+@b{{1|vhXIRo2htFBj#)i0NA7!O0R6Bj9)-*$x44jPsUH_lyzFhyeyEE+@+ zd$(giPs6++OoUf(oCyi z<@@9SJ7{;Hc|Q~~QfG3h`m6@m@4*Akt|UNrWHIk9VnY&Rn5fvCILwDeaj{i7fSiAe zJGjS%cMUIWr;TFOEt;PY#`9`F;D0L$L8*!qnq(>$e+qnxi#QzM*W*fr9yT<|)9BKv zId@4zI<$e9Lk{)F68vFlo=&2J%D@ulvfLh0N;qw0ka*`-xRh`NYE^z<6h8x($#0d? z3vr9!@1Z<5KaA;h`eEX$VY2oOu)%e@o*A#BPKb-Cv+)yT-=_HEJ>zUD^Dgoj=7^=g zGGXk?k7+q~5x?S1wD?XrCYs0jp(7GSV?m1_v7hy^j=RO}kN7pI{KQ)aJ%by5=8>*V zcsU7X_l*u+A=8rXP<3SItx*_qP{zyBAo}h9XQc)mmy${R1FG`=BT)5U8C~W7ccuPs zq^d;&+Cyao^@n_8W@mew#6;L%z+Y5vf((I(51}04ks*O69(KW>g>E9G`kMIG&SQDA zaNXTnS|81(r3JonB{g5NTm?b9K}%bE%c|wo^kzxT+SF%aC<2YGMtUV%>T&=A-3 zy*2iq^=IteJ|pbj3M2U5(gR0t-2pfqPk}L>@A+Vy$#4Ggx3TAb5?1b_Vg$F#H;BBo zhnU=t3LSsdfqCO^hm9{`8t0QVx^Kym4^Mj3*}XL`tB2m%IXjkbl`*Jq+0om35VYTN zgT^gq1iH&Nq~Gd&VJvI=P)M4|FZxC|P1-M&=C`a;&*9+S$uvJpcjZAI*H6eANc5@0 zdh{yj--dKdWD1B6BHpbTkD@+uyog&g3fqp&zM;MqZ<3B$)W-0~`7owOgc|4Iq zeEL%qExeXiV@3m)3)~W?Fs!0R$xAtsbmkViBv@%$EAa0@z3qMG-qyuyDCJx|E@jtb zc@>nOVtx$mA%A)>pOps(70NJSZFXowAeKa$55)jy8i`t@!c!ixJ5cA6>|&+1#x8*w ze^c`}sN1`l`XIca1(U><0;nPN=p5KFV zOep$lB*nYw5x9$pk%6=0J+o{(p9QAr>I^7OofsjD4j&_71f0soXLgU(dJNU$ zHtPCCr(Q`?lcJ7g2wQxqu;cTWEPm7dvV#9V&fYmlvtZrc?CR>OE_`L%wr$%+muYN+qP}nQ|FvJcP4%j_nbQu@$GN_zvIo!l`G#|50y8O>G$0_7iryIo{4_rZW*pg zc*IAq+TjLX+zl>A1@R;!=8}5FVQ%6G#XVL?WU>7N3g>b<%JJXc^9C zqb$^8`xy@gk7w~sXM9@?&rgK(**>cpiN4Yi!CqnSqur{%5SV^R+@Rq(84o#`ryJq z&JtB7aI(g9JN_}iUDam>H9*eb96b#q;sEvx9y5vxT!MPXNN*8m)~N33X4f>*;qm}w z-#0F@pdLa3ZLOZ^Ce}37Vc0aw)}T&aHrviv?&Gk;$0LLJit>5d`2gMQP8+91 zgCH%i4;JwgGKts@Do4V}HIP=28;%98f2u4-6M|9BBv>q0ROiqX0W4z+`G&FTZnqrEAP;MV!P^%=)!U&X%pN3?vXe-!%+?_@2%>~{9p~*^##Q}66O=x zbTY8?cOir|f3@Kt17Mqjh41epkfsK6h5%2GB0qPYRq@8a`|hhxj=u*uv3OA(xDZA{ zYB8<9iXw!|)F-trxAxrT3}N-tmmHP!x%^o?iY2A=0&oqtnH=|IL`I4Kj9PC!v3c~! z2)Xh6nch9-RYXOM$?%k>z1)jxs6zleo2ig+XM%A`s6qUw;HGv{V@_UMWk*FtPGw%3 z?#Jun!_TnE#^h*C<>FH>{9kAuaX_}G)EUmqmqsU2VMWyMBPpB%ZCPn%emzWWYx9+( z0A=hh>M}OJ(7ZEPGLPON;2YlRR%Y~vt3p6za%oK2D8q9dQ9}nc{OOa(hnO%?ir|6A z4(a)gZL!t$_kp$k8QA8-gk@*sYGZ5QFE7uL+}!crD^^1x>D<-b5HthKtZKcz6!_8P zp{7M^VMG7nXmkXJQSr0Irav%n`c$&X?5ZEm;ob4t49LN$9ghtY>nJ$EB}4PVF4LhUKOnXf129Ca)Y?ii57JIK zDl&!APt}G>G7G+66D6G*7h|yn*{4maTa-YGQ|d6uj8e#m@0tC7aDKuzr{;Mb569GP zj+UknP0IhSYC4At<`ZhksF=iVh7C{+#1%myc_i?s%@&3mrI|0zLN_RxVT#Aoh{%oK z%n_!WWLr3~J-c6O)-c{W#^OtSqOA?uzDC|@z+>%55E#BuhT^-M#Pl80*hS^9Y?^2L zwV{#9;LmAY!u+dG;}o60vx(3d41_F&hL?LyiPIVUR#pI`qOieSE|4kNkDXGG3poc! zVkS7u2HctXrcCXmi3u;J;!oax|7J&Xgyj{A(4nRk*v#tvI%nriNIDMW^R)7ZiH0^@ z(hP&l9&djYJ!v;z)-DXo#aW6|64dm-OKhvRa{=4#%+;!_QT9A z6NKo7%J|IMBQz{aYG@}6(uDXpUmtBtqLDr4i`pQs%qy?z9LXU%#u!3-r_M+5Wbpj< zo`h@Ga51o@*kK7D5g_FZE@ZCU&+tEF1rvD$fqsflf1_)lXzQ=Rp?<3OvuTy^)QZ)- zb7Vt-(r>*2Gop0H7E)W%9jA1pM(-)#^FuV@MxJ{iO2iK%<3|03T}qoZsV=E&4mMza zlDgm^#A3PH*BJ$Ik&P}^T}7N;X?)DuEdLkdSeV50v<8KReD1t{d|NlW6Y@&=sB*~t zT01k%3Y|NZGOtS#8lHY5SEyc`E0FFDjFT!sgsv#;ko5@c5L-}sEq8G=Zki%$1H$+q zr!*+W8}Y7n{Z6Dhd!b{xBs{j-*Kd#_N!g?>yt-I?_3v*ETHrd`Df*s)a6Q>!%FvVU z-_MQ+OV&q`YqS_y`W7B=+L(e!mj?Um0SB!95_FmhM4>QPpyV z{9J+3htr)=chv;hl?>Gm1OXfp-5c|dfB>ksy|A4D1+0@;B&62@>E7{g*hiB?$4?~j z^a`R37;z=zQV_EeL%itEwA^|^t8NmS0>mUiO_GHrGd{PB6L$cG;kwW+lA0}PV$erA zF-WFY(z(C$JNnPf1Kvno2jPbqbpEG|iy@frm})%MVH1|j8WA!r+Vmr_G$Lb-YU0lrd!_vUNB_c7@kK^Qx>^JuM86Wt=sP3DzCt#+|&@UBUS6 zf(l*V7pi^lZpahdGG6YaEOdmA;U^hiSk!Ni?x@?fN3yV~J=)Y$F>8AbADY2Z=)&)y zchi-hK%kM306~yLfqs(UME>DHb_IMw`#FM$I>cKw*mU6bf^_X3YBWaPm83o7bV?)V z1%RVfmrMcGivh2KA+t4@vV{(tQfvQXqtFqz8ZDO9Pz^CKot1hD`^?Bfo$xTcDAwdmm zcp;MO}7fJjafvZ`_qHkjt9TOf15Q-}u z42!Mz6?{AthhLh$C^%GEPn$46$(5D-%DG{i$Az+Mp?3-AZZ*9rf?_DD`X`$J0o>4U z6rA@a`PaAg&!<00&L38Aj~Iem6Gz&H459}U+V3d10%eNgRpXc(wj_8P4AJltu|*?j z#;JRh;i;RWm^?y}h(2q`LyYegcU4ImAsqkVs_P%SHS^at6KSX)KPa&Oos0h;qp1J2 zTNBp(hpF&?gq&o=TguGIA`X2uQBa++yUJq^<^kJUhzI06|84JyHbD+a!2?CmFF~Pn zvaEFq&g!1pZt51Cf9_3czZO87x`6Pj>^n|#cf0z?viCYlZ~J)t*dzH1Qf?x;XN10y zj1q>IsDZ9UX-29q)@Mms(wwK4vLjz{s&?g4ZKdv`^3_c%zrye|0o-@sV|#fDB=Dy~ zy`ukK!T7%O3e^^*#n68(^$7GGS7*3^L(rK}N!elvS{Y3~phXJQb;7+5&5gWqEQ{G} zt^IR--RU^LYgetX&UDeTCJOpsyW)a@Qi-xkc&Ed2t%)m%ah+xJE%0D@JpxJTfKR8b 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 Date: Fri, 6 Nov 2026 15:58:32 +0700 Subject: [PATCH 2/5] COR-6538: update marker and record example (#247) * COR-6538: update marker and record example * update rework * update rework --- octave/README.md | 45 +++++++- octave/examples/recordAndMarker.m | 167 ++++++++++++++++++++++++++++ octave/examples/subscribeAndPlot.m | 5 +- octave/functions/cortexConnect.m | 6 +- octave/functions/cortexDisconnect.m | 8 +- octave/functions/cortexMarker.m | 58 ++++++++++ octave/functions/cortexRecord.m | 47 ++++++++ octave/functions/cortexSession.m | 75 +++++++++++++ octave/functions/cortexSubscribe.m | 49 +++----- octave/internal/CortexContext.m | 2 + octave/internal/CortexHeadset.m | 8 +- octave/internal/CortexManager.m | 18 ++- octave/internal/CortexMarker.m | 78 +++++++++++++ octave/internal/CortexRecord.m | 60 ++++++++++ 14 files changed, 577 insertions(+), 49 deletions(-) create mode 100644 octave/examples/recordAndMarker.m create mode 100644 octave/functions/cortexMarker.m create mode 100644 octave/functions/cortexRecord.m create mode 100644 octave/functions/cortexSession.m create mode 100644 octave/internal/CortexMarker.m create mode 100644 octave/internal/CortexRecord.m diff --git a/octave/README.md b/octave/README.md index d1b8b80..b55da92 100644 --- a/octave/README.md +++ b/octave/README.md @@ -13,14 +13,14 @@ The local connection has two parts: ## Folder Structure -- `functions/`: Public functions (`cortexConnect`, `cortexSubscribe`, `cortexGetData`, `cortexDisconnect`) that hide the internal MATLAB classes. +- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexDisconnect`) that hide the internal MATLAB classes. - `internal/`: Internal SDK classes. Not a public interface; they may change. - `lib/`: `nv-websocket-client-2.14.jar` and `cortex-ws-client.jar`, the Java WebSocket client used for WSS. - `java/`: Source of the small Java wrapper (`cortex-ws-client.jar`). - `config/`: Local configuration. Copy `config/config.example.json` to `config/config.json` to store your Cortex application credentials. `config/config.json` is ignored by Git and must not be committed or shared. - `examples/`: Beginner-friendly scripts that show complete workflows. -The public workflow uses `cortexConnect` and `cortexDisconnect`. The underlying `CortexManager` and `CortexAuth` classes are kept inside `internal/` so future examples can extend the SDK without making the user-facing scripts more complicated. +The public workflow uses procedural functions such as `cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexRecord`, `cortexMarker`, and `cortexDisconnect`. The underlying Cortex classes are kept inside `internal/` so examples can extend the SDK without making researchers manage the WebSocket or internal class instances. ## Requirements @@ -136,7 +136,8 @@ The internal manager is stored in the struct only so that `cortexDisconnect(cort ```matlab cortex = cortexConnect(); -cortex = cortexSubscribe(cortex, 'INSIGHT-A1B2C3D4', {'eeg'}); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +cortex = cortexSubscribe(cortex, {'eeg'}); [labels, data, time] = cortexGetData(cortex, 'eeg', 256); % newest 256 samples cortex = cortexDisconnect(cortex); % unsubscribes and closes the socket ``` @@ -144,10 +145,44 @@ cortex = cortexDisconnect(cortex); % unsubscribes and cl - To subscribe to other supported streams, pass their names instead, for example `{'mot','dev','eq','pow','met'}`. Call `cortexGetData(cortex, streamName)` for each stream you want to consume. - `labels{j}` names column `j` of `data`; each row is a sample. Use the returned labels to select columns rather than hard-coding positions. For console output, loop over `labels` and print each `data(end,j)`; for plots, plot the desired numeric columns against `time`. - `met` columns named `.isActive` are 1 when that metric is running. When it is 0 the metric value is `NaN` (Cortex sends `null`). Without a PRO license `met` arrives about every 10 seconds; with a PRO license about 2 samples per second. `pow` does not need a PRO license. -- `cortexSubscribe` scans for the headset, connects it if needed (waiting up to 5 seconds for Cortex warning 104), creates an active session and subscribes. Optional name/value pairs: `'autoRescan'` (default `true`), `'queryInterval'` (default `3` seconds), `'scanTimeout'` (default `15` seconds). +- `cortexSession` scans for the headset, connects it if needed (waiting up to 5 seconds for Cortex warning 104), and creates one active session for that headset. Calling it again for the same active headset reuses that session; a different headset requires disconnecting first. +- `cortexSubscribe(cortex, streams)` subscribes the requested streams on the active session created by `cortexSession`. - `cortexGetData` collects the samples that have arrived and returns them from a buffer that keeps the latest 10000 samples per stream. `data` has one row per sample and one column per entry in `labels`; empty values are `NaN`. - Call `cortexGetData` regularly. Samples are only read from the connection when it runs, and it can take up to about 1 second when no data is arriving. +## Record and Markers + +`examples/recordAndMarker.m` demonstrates creating and stopping a record without subscribing to any data stream, and adding keyboard-controlled markers. + +1. Set `headsetId` and `titlePrefix` near the top of `examples/recordAndMarker.m`. Add the examples folder to the MATLAB or Octave path and run the function without arguments: + +```matlab +addpath('octave/examples'); +recordAndMarker(); +``` + +2. Focus the opened figure. Press `S` to start a record titled `_`. The example adds a description and the tags `octave` and `record-marker-demo`. +3. Press any other letter to inject an instance marker; the pressed letter is used as both its label and string value. Press that letter again to update the marker with the current epoch time in milliseconds, turning it into an interval marker. The next press injects a new instance marker. +4. Press `Esc` or close the figure to stop the active record and disconnect. + +The headset-only connection and record/marker APIs are also available directly: + +```matlab +cortex = cortexConnect(); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +[cortex, started] = cortexRecord(cortex, 'start', 'my-study_1792692000', ... + 'Example record description', {'octave', 'demo'}); +[cortex, injected] = cortexMarker(cortex, 'inject', 'A', 'A'); +endTime = double(javaMethod('currentTimeMillis', 'java.lang.System')); +[cortex, updated] = cortexMarker(cortex, 'update', injected.marker.uuid, endTime); +[cortex, stopped] = cortexRecord(cortex, 'stop'); +cortex = cortexDisconnect(cortex); +``` + +`cortexSession(cortex, headsetId)` connects the headset and creates or reuses its active session without subscribing to streams. From that session, call either `cortexSubscribe(cortex, streams)` or start a record. `cortexRecord(cortex, 'start', title, description, tags)` returns the Cortex result fields `record` and `sessionId`; `cortexRecord(cortex, 'stop')` returns the stopped `record` and its `sessionId`. `cortex.isRecording` and `cortex.recordId` reflect the active record. + +`cortexMarker(cortex, 'inject', label, value, ...)` returns `recordId`, `sessionId`, and `marker`. Optional name/value pairs are `time` (epoch milliseconds; defaults to the current time), `port` (defaults to `Software`), and `extras` (a scalar struct). `cortexMarker(cortex, 'update', markerId, endTime, ...)` returns the same result fields and accepts optional `extras`. `endTime` is required and is measured in milliseconds since 1970-01-01 UTC. Both marker actions require an active record. + ## Troubleshooting ### Could not connect to Cortex at `wss://localhost:6868` @@ -179,7 +214,7 @@ Use a recent MATLAB or GNU Octave release with native JSON support. The SDK does - Switch the headset on and make sure it is in range, or enable a virtual headset in EMOTIV Launcher. - Check that `headsetId` matches the id shown in EMOTIV Launcher exactly. -- Increase `'scanTimeout'` in `cortexSubscribe` if the headset is slow to appear. +- Increase `'scanTimeout'` in `cortexSession` if the headset is slow to appear. - If you see "warning 104 was not received", the headset did not finish connecting in 5 seconds; try again. ## Next Steps diff --git a/octave/examples/recordAndMarker.m b/octave/examples/recordAndMarker.m new file mode 100644 index 0000000..40d1a8a --- /dev/null +++ b/octave/examples/recordAndMarker.m @@ -0,0 +1,167 @@ +function recordAndMarker() +% recordAndMarker Start/stop a record and inject/update markers from keyboard input. +% Set headsetId and recordTitlePrefix below, then call recordAndMarker(). +% Press S to start, any other letter to toggle a marker interval, and Esc to stop and exit. + +% Set your headset id and the prefix used to generate each record title. +headsetId = ''; +recordTitlePrefix = 'my-record'; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: establish authorization, connect the selected headset, and create its active session. +cortex = cortexConnect(); +fig = []; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('recordAndMarker:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + fprintf('[recordAndMarker] Connected to %s. Key help:\n', headsetId); + fprintf(' S: start a record.\n'); + fprintf(' A-Z except S: inject an instance marker; press that key again to end its interval.\n'); + fprintf(' Esc: stop the record and exit.\n'); + + markerIds = struct(); + fig = figure('Name', 'Cortex Record and Marker Example', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + helpLines = {'Keyboard controls', '', ... + 'S: start a new record', ... + 'A-Z (except S): add an instance marker while recording', ... + 'Press the same letter again: end its marker interval', ... + 'Esc: stop the record and exit', '', ... + 'Marker ID, type, start time, and end time are printed', ... + 'in the Command Window after each marker action.'}; + helpText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.12 0.84 0.78], ... + 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 12, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', ... + 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.02 0.84 0.08], ... + 'String', 'Ready: press S to start a record.', ... + 'HorizontalAlignment', 'left', 'FontSize', 10, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', ... + 'KeyPressFcn', @onKeyPress, 'Interruptible', 'off', 'BusyAction', 'queue'); + + % Acquire: wait for keyboard events while Cortex keeps the active session open. + uiwait(fig); +catch failure + fprintf('[recordAndMarker] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: stop any active record and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[recordAndMarker] Finished.\n'); + + function onKeyPress(source, event) + keyName = event.Key; + showStatus(sprintf('Key %s received.', keyName)); + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + if cortex.isRecording + try + [cortex, ~] = cortexRecord(cortex, 'stop'); + fprintf('[recordAndMarker] Record stopped.\n'); + showStatus('Record stopped. Closing example.'); + catch stopFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', stopFailure.identifier, stopFailure.message); + showStatus(['Could not stop record: ' stopFailure.message]); + end + end + if ishandle(fig), uiresume(fig); end + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 || ... + isempty(regexp(keyCharacter, '^[A-Za-z]$', 'once')) + showStatus(sprintf('Ignored key: %s. Use S, A-Z, or Esc.', keyName)); + return; + end + + % Process: reserve S for record start and use every other letter to toggle marker intervals. + if lower(keyCharacter) == 's' + if cortex.isRecording + fprintf('[recordAndMarker] A record is already active.\n'); + showStatus('A record is already active.'); + return; + end + try + recordTitle = sprintf('%s_%d', recordTitlePrefix, floor(currentTimeMilliseconds() / 1000)); + description = 'Keyboard-controlled Cortex record and marker example'; + tags = {'octave', 'record-marker-demo'}; + [cortex, result] = cortexRecord(cortex, 'start', recordTitle, description, tags); + fprintf('[recordAndMarker] Started record %s.\n', result.record.uuid); + showStatus(['Recording started: ' result.record.uuid]); + catch startFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', startFailure.identifier, startFailure.message); + showStatus(['Record start failed: ' startFailure.message]); + end + return; + end + + if ~cortex.isRecording + fprintf('[recordAndMarker] Start a record with S before adding markers.\n'); + showStatus('No active record. Press S to start one first.'); + return; + end + + markerKey = lower(keyCharacter); + try + if isfield(markerIds, markerKey) + markerId = markerIds.(markerKey); + [cortex, result] = cortexMarker(cortex, 'update', markerId, currentTimeMilliseconds()); + markerIds = rmfield(markerIds, markerKey); + fprintf('[recordAndMarker] Updated marker %s (type: %s).\n', ... + result.marker.uuid, result.marker.type); + fprintf(' Start: %s\n End: %s\n', ... + result.marker.startDatetime, result.marker.endDatetime); + showStatus(['Marker interval updated: ' result.marker.uuid]); + else + [cortex, result] = cortexMarker(cortex, 'inject', keyCharacter, keyCharacter, ... + 'time', currentTimeMilliseconds(), 'port', 'MATLAB/Octave example'); + markerIds.(markerKey) = result.marker.uuid; + fprintf('[recordAndMarker] Injected marker %s (type: %s, port: %s) with value %s.\n', ... + result.marker.uuid, result.marker.type, result.marker.port, keyCharacter); + fprintf(' Start: %s\n End: %s\n', ... + result.marker.startDatetime, result.marker.endDatetime); + showStatus(['Marker injected: ' result.marker.uuid ... + ' (value: ' result.marker.value ')']); + end + catch markerFailure + fprintf('[recordAndMarker] ERROR %s: %s\n', markerFailure.identifier, markerFailure.message); + showStatus(['Marker action failed: ' markerFailure.message]); + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if cortex.isRecording + try + [cortex, ~] = cortexRecord(cortex, 'stop'); + catch stopFailure + fprintf('[recordAndMarker] Could not stop the active record: %s\n', stopFailure.message); + end + end + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end + +function time = currentTimeMilliseconds() +time = double(javaMethod('currentTimeMillis', 'java.lang.System')); +end diff --git a/octave/examples/subscribeAndPlot.m b/octave/examples/subscribeAndPlot.m index 6c924d9..5f18856 100644 --- a/octave/examples/subscribeAndPlot.m +++ b/octave/examples/subscribeAndPlot.m @@ -10,12 +10,13 @@ function subscribeAndPlot() streams = {'eeg'}; durationSeconds = 90; -% 2. Connection / Authentication, then headset connection and subscription. +% 2. Connection / Authentication, then create a headset session and subscribe to streams. % Credentials are loaded from config/config.json. cortex = cortexConnect(); connectionCleanup = onCleanup(@() cortexDisconnect(cortex)); if cortex.isConnected - cortex = cortexSubscribe(cortex, headsetId, streams); + cortex = cortexSession(cortex, headsetId); + cortex = cortexSubscribe(cortex, streams); end % 3. Acquisition Loop: each cortexGetData call collects new samples into the buffer. diff --git a/octave/functions/cortexConnect.m b/octave/functions/cortexConnect.m index be15fcd..24472fa 100644 --- a/octave/functions/cortexConnect.m +++ b/octave/functions/cortexConnect.m @@ -8,7 +8,8 @@ % userInfo user details returned by Cortex ([] on failure) % licenseInfo license details returned by Cortex ([] on failure) % manager internal handle used by cortexDisconnect; do not modify -% isSubscribed, headsetId, sessionId, streams filled in by cortexSubscribe +% isSubscribed, headsetId, sessionId, streams filled in by headset connection/subscription +% isRecording, recordId filled in by cortexRecord functionsDir = fileparts(mfilename('fullpath')); addpath(fullfile(functionsDir, '..', 'internal')); @@ -16,7 +17,8 @@ [clientId, clientSecret, port] = cortexCredentials(); cortex = struct('isConnected', false, 'token', '', 'userInfo', [], 'licenseInfo', [], 'manager', [], ... - 'isSubscribed', false, 'headsetId', '', 'sessionId', '', 'streams', {{}}); + 'isSubscribed', false, 'isRecording', false, 'recordId', '', ... + 'headsetId', '', 'sessionId', '', 'streams', {{}}); manager = CortexManager(clientId, clientSecret, 'localhost', port); cortex.manager = manager; diff --git a/octave/functions/cortexDisconnect.m b/octave/functions/cortexDisconnect.m index 1c1c121..413f91e 100644 --- a/octave/functions/cortexDisconnect.m +++ b/octave/functions/cortexDisconnect.m @@ -4,12 +4,18 @@ if isstruct(cortex) && isfield(cortex, 'manager') && ~isempty(cortex.manager) fprintf('[cortexDisconnect] Closing Cortex connection...\n'); - cortex.manager.close(); + try + cortex.manager.close(); + catch failure + fprintf('[cortexDisconnect] Could not close the Cortex connection cleanly: %s\n', failure.message); + end cortex.manager = []; end cortex.isConnected = false; cortex.isSubscribed = false; +cortex.isRecording = false; +cortex.recordId = ''; cortex.headsetId = ''; cortex.sessionId = ''; cortex.streams = {}; diff --git a/octave/functions/cortexMarker.m b/octave/functions/cortexMarker.m new file mode 100644 index 0000000..5a78550 --- /dev/null +++ b/octave/functions/cortexMarker.m @@ -0,0 +1,58 @@ +function [cortex, result] = cortexMarker(cortex, action, varargin) +% cortexMarker Inject an instance marker or update it to an interval marker. +% [cortex, result] = cortexMarker(cortex, 'inject', label, value, ...) +% Optional inject name/value pairs: time (epoch milliseconds), port, extras. +% [cortex, result] = cortexMarker(cortex, 'update', markerId, endTime, ...) +% Optional update name/value pair: extras. Markers require an active record. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'isRecording') || ~cortex.isRecording || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:markerFailed', 'Start a record before using marker operations.'); + end + if ~ischar(action) + error('cortex:markerFailed', 'action must be ''inject'' or ''update''.'); + end + + marker = cortex.manager.getMarker(); + switch lower(action) + case 'inject' + if numel(varargin) < 2 + error('cortex:markerFailed', 'Inject requires a label and value.'); + end + label = varargin{1}; + value = varargin{2}; + options = parseOptions(varargin(3:end), struct('time', [], 'port', 'Software', 'extras', struct())); + result = marker.inject(label, value, options.time, options.port, options.extras); + case 'update' + if numel(varargin) < 2 + error('cortex:markerFailed', 'Update requires a markerId and endTime.'); + end + markerId = varargin{1}; + endTime = varargin{2}; + options = parseOptions(varargin(3:end), struct('extras', struct())); + result = marker.update(markerId, endTime, options.extras); + otherwise + error('cortex:markerFailed', 'action must be ''inject'' or ''update''.'); + end +catch failure + if strcmp(failure.identifier, 'cortex:markerFailed'), rethrow(failure); end + error('cortex:markerFailed', 'Marker operation failed: %s', failure.message); +end +end + +function options = parseOptions(arguments, options) +if mod(numel(arguments), 2) ~= 0 + error('cortex:markerFailed', 'Marker options must be supplied as name/value pairs.'); +end +for index = 1:2:numel(arguments) + name = arguments{index}; + if ~ischar(name) || ~isfield(options, name) + error('cortex:markerFailed', 'Unknown marker option.'); + end + options.(name) = arguments{index + 1}; +end +end + diff --git a/octave/functions/cortexRecord.m b/octave/functions/cortexRecord.m new file mode 100644 index 0000000..b42391f --- /dev/null +++ b/octave/functions/cortexRecord.m @@ -0,0 +1,47 @@ +function [cortex, result] = cortexRecord(cortex, action, varargin) +% cortexRecord Start or stop a record for the active Cortex session. +% [cortex, result] = cortexRecord(cortex, 'start', title, description, tags) +% [cortex, result] = cortexRecord(cortex, 'stop') +% Starting updates cortex.isRecording and cortex.recordId. The result is the +% Cortex result struct: record and sessionId. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:recordFailed', 'Connect to Cortex before using record operations.'); + end + if ~ischar(action) + error('cortex:recordFailed', 'action must be ''start'' or ''stop''.'); + end + + record = cortex.manager.getRecord(); + switch lower(action) + case 'start' + if isempty(varargin) || numel(varargin) > 3 + error('cortex:recordFailed', 'Start requires title and accepts optional description and tags.'); + end + title = varargin{1}; + description = ''; + tags = {}; + if numel(varargin) >= 2, description = varargin{2}; end + if numel(varargin) >= 3, tags = varargin{3}; end + result = record.create(title, description, tags); + case 'stop' + if ~isempty(varargin) + error('cortex:recordFailed', 'Stop does not accept additional arguments.'); + end + result = record.stop(); + otherwise + error('cortex:recordFailed', 'action must be ''start'' or ''stop''.'); + end + + context = cortex.manager.getContext(); + cortex.isRecording = context.isRecording; + cortex.recordId = context.recordId; +catch failure + if strcmp(failure.identifier, 'cortex:recordFailed'), rethrow(failure); end + error('cortex:recordFailed', 'Record operation failed: %s', failure.message); +end +end + diff --git a/octave/functions/cortexSession.m b/octave/functions/cortexSession.m new file mode 100644 index 0000000..3fb52f6 --- /dev/null +++ b/octave/functions/cortexSession.m @@ -0,0 +1,75 @@ +function cortex = cortexSession(cortex, headsetId, varargin) +% cortexSession Connect a headset and create or reuse its active Cortex session. +% cortex = cortexSession(cortex, 'INSIGHT-XXXXXXXX') creates one session for the headset. +% Calling it again for the same active headset reuses that session; another headset +% cannot be connected until the current Cortex connection is closed. +% Optional name/value pairs: autoRescan (true), queryInterval (3 seconds), +% and scanTimeout (30 seconds). + +options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30); +if mod(numel(varargin), 2) ~= 0 + error('cortex:sessionFailed', 'Options must be supplied as name/value pairs.'); +end +for index = 1:2:numel(varargin) + name = varargin{index}; + if ~ischar(name) || ~isfield(options, name) + error('cortex:sessionFailed', 'Unknown headset session option.'); + end + options.(name) = varargin{index + 1}; +end + +if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:sessionFailed', 'Connect and authorize Cortex before creating a headset session.'); +end +if ~ischar(headsetId) || isempty(headsetId) + error('cortex:sessionFailed', 'headsetId must be a non-empty character vector.'); +end + +manager = cortex.manager; +context = manager.getContext(); +if ~isempty(context.sessionId) + if ~strcmp(context.headsetId, headsetId) + error('cortex:sessionFailed', ... + 'A session for headset %s is already active. Disconnect before selecting headset %s.', ... + context.headsetId, headsetId); + end + cortex = syncSessionState(cortex, context); + return; +end + +headset = []; +try + headset = manager.getHeadset(); + headset.scanHeadset(options.autoRescan, options.queryInterval); + + if ~headset.waitForHeadset(headsetId, options.scanTimeout) + error('CortexHeadset:notFound', 'Headset %s was not found within %g seconds.', ... + headsetId, options.scanTimeout); + end + + [ok, message] = headset.connectToHeadset(headsetId, {}); + if ~ok + error('CortexHeadset:connect', '%s', message); + end + + cortex = syncSessionState(cortex, manager.getContext()); +catch failure + if ~isempty(headset) + try + headset.stopScan(); + catch + end + end + error('cortex:sessionFailed', 'Could not create a headset session: %s', failure.message); +end +end + +function cortex = syncSessionState(cortex, context) +cortex.headsetId = context.headsetId; +cortex.sessionId = context.sessionId; +cortex.streams = context.subscribedStreams; +cortex.isSubscribed = ~isempty(context.subscribedStreams); +cortex.isRecording = context.isRecording; +cortex.recordId = context.recordId; +end diff --git a/octave/functions/cortexSubscribe.m b/octave/functions/cortexSubscribe.m index 4d70173..b5397a9 100644 --- a/octave/functions/cortexSubscribe.m +++ b/octave/functions/cortexSubscribe.m @@ -1,30 +1,17 @@ -function cortex = cortexSubscribe(cortex, headsetId, streams, varargin) -% cortexSubscribe Scan for a headset, connect it, open a session and subscribe to data streams. -% cortex = cortexSubscribe(cortex, 'INSIGHT-XXXXXXXX', {'eeg','mot','dev','eq','pow','met'}) -% updates the fields: +function cortex = cortexSubscribe(cortex, streams) +% cortexSubscribe Subscribe to streams on an active headset session. +% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met'}) +% Update the fields: % isSubscribed true when the streams are being received -% headsetId the connected headset -% sessionId the Cortex session id % streams the subscribed stream names -% Optional name/value pairs: -% 'autoRescan' rescan automatically when a scan finishes (default true) -% 'queryInterval' seconds between headset list queries (default 3) -% 'scanTimeout' seconds to wait for the headset to appear (default 30) % Read the samples with cortexGetData. -options = struct('autoRescan', true, 'queryInterval', 3, 'scanTimeout', 30); -for index = 1:2:numel(varargin) - 1 - if ~isfield(options, varargin{index}) - fprintf('[cortexSubscribe] ERROR Unknown option "%s".\n', varargin{index}); - return; - end - options.(varargin{index}) = varargin{index + 1}; -end - -if ~cortex.isConnected +if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) fprintf('[cortexSubscribe] ERROR Call cortexConnect successfully first.\n'); return; end + if ischar(streams), streams = {streams}; end validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met'}; if ~iscellstr(streams) || isempty(streams) || ~all(ismember(streams, validStreams)) @@ -32,30 +19,22 @@ return; end -cortex.isSubscribed = false; try - headset = cortex.manager.getHeadset(); - headset.scanHeadset(options.autoRescan, options.queryInterval); - - if ~headset.waitForHeadset(headsetId, options.scanTimeout) - fprintf(['[cortexSubscribe] Headset %s was not found within %g seconds. ' ... - 'Check that it is switched on and in range.\n'], headsetId, options.scanTimeout); - headset.stopScan(); + context = cortex.manager.getContext(); + if isempty(context.sessionId) + fprintf('[cortexSubscribe] ERROR Call cortexSession first to create an active session.\n'); return; end - [ok, message] = headset.connectToHeadset(headsetId, streams); - if ~ok - fprintf('[cortexSubscribe] ERROR %s\n', message); - return; - end + headset = cortex.manager.getHeadset(); + headset.subscribe(streams); context = cortex.manager.getContext(); cortex.headsetId = context.headsetId; cortex.sessionId = context.sessionId; cortex.streams = context.subscribedStreams; - cortex.isSubscribed = true; - fprintf('[cortexSubscribe] Receiving data from %s.\n', headsetId); + cortex.isSubscribed = ~isempty(context.subscribedStreams); + fprintf('[cortexSubscribe] Receiving data from %s.\n', context.headsetId); catch failure fprintf('[cortexSubscribe] ERROR %s: %s\n', failure.identifier, failure.message); end diff --git a/octave/internal/CortexContext.m b/octave/internal/CortexContext.m index 3324c31..b012c14 100644 --- a/octave/internal/CortexContext.m +++ b/octave/internal/CortexContext.m @@ -10,6 +10,8 @@ headsetId = '' sessionId = '' subscribedStreams = {} + isRecording = false + recordId = '' streamLabels = struct() % one field per stream, each a cell array of column labels buffer = [] % CortexDataBuffer holding the received samples end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m index 4b8811b..c636377 100644 --- a/octave/internal/CortexHeadset.m +++ b/octave/internal/CortexHeadset.m @@ -1,10 +1,10 @@ classdef CortexHeadset < handle - % CortexHeadset Scans for headsets, connects one, opens a session and subscribes to data streams. + % CortexHeadset Scans for headsets, connects one and opens a session, optionally subscribing to streams. % The client is single-threaded, so the scan "timer" runs inside update(), which also reads % the incoming data samples into the context buffer. properties - connectTimeout = 5 % seconds to wait for warning 104 (headset connected) + connectTimeout = 10 % seconds to wait for warning 104 (headset connected) end properties (SetAccess = private) @@ -99,7 +99,7 @@ function stopScan(obj) end function [ok, message] = connectToHeadset(obj, headsetId, streams) - % Connects the headset if needed, creates an active session, then subscribes to streams. + % Connects the headset if needed, creates an active session, and subscribes when streams are provided. if nargin < 3, streams = {}; end ok = false; message = ''; @@ -231,6 +231,8 @@ function onSessionClosed(obj, warning) obj.context.sessionId = ''; obj.context.headsetId = ''; obj.context.subscribedStreams = {}; + obj.context.isRecording = false; + obj.context.recordId = ''; obj.parser.reset(); fprintf('[CortexHeadset] Session %s was closed by Cortex.\n', warning.message.sessionId); end diff --git a/octave/internal/CortexManager.m b/octave/internal/CortexManager.m index 5ae25d3..93a4cab 100644 --- a/octave/internal/CortexManager.m +++ b/octave/internal/CortexManager.m @@ -13,6 +13,8 @@ properties (Access = private) auth = [] headset = [] + record = [] + marker = [] end methods @@ -53,7 +55,19 @@ headset = obj.headset; end - % Future getRecord/getBCI follow the getAuth pattern: create lazily with getClient() and getAuth(). + function record = getRecord(obj) + if isempty(obj.record) + obj.record = CortexRecord(obj.getClient(), obj.context); + end + record = obj.record; + end + + function marker = getMarker(obj) + if isempty(obj.marker) + obj.marker = CortexMarker(obj.getClient(), obj.context); + end + marker = obj.marker; + end function close(obj) % Only closes what was actually created. @@ -67,6 +81,8 @@ function close(obj) if ~isempty(obj.auth) obj.auth.close(); end + obj.record = []; + obj.marker = []; end end end diff --git a/octave/internal/CortexMarker.m b/octave/internal/CortexMarker.m new file mode 100644 index 0000000..4e79a78 --- /dev/null +++ b/octave/internal/CortexMarker.m @@ -0,0 +1,78 @@ +classdef CortexMarker < handle + % CortexMarker Injects instance markers and updates them to interval markers. + + properties (Access = private) + client + context + end + + methods + function obj = CortexMarker(client, context) + obj.client = client; + obj.context = context; + end + + function result = inject(obj, label, value, time, port, extras) + if nargin < 4 || isempty(time) + time = double(javaMethod('currentTimeMillis', 'java.lang.System')); + end + if nargin < 5 || isempty(port), port = 'Software'; end + if nargin < 6 || isempty(extras), extras = struct(); end + obj.validateRecording(); + if ~ischar(label) || isempty(label) + error('CortexMarker:label', 'label must be a non-empty character vector.'); + end + if ~(ischar(value) || (isnumeric(value) && isscalar(value) && isfinite(value))) + error('CortexMarker:value', 'value must be a character vector or finite numeric scalar.'); + end + if ~isnumeric(time) || ~isscalar(time) || ~isfinite(time) || time < 0 + error('CortexMarker:time', 'time must be a non-negative numeric epoch timestamp in milliseconds.'); + end + if ~ischar(port) || isempty(port) + error('CortexMarker:port', 'port must be a non-empty character vector.'); + end + if ~isstruct(extras) || numel(extras) ~= 1 + error('CortexMarker:extras', 'extras must be a scalar struct.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'time', double(time), 'value', value, 'label', label, 'port', port); + if ~isempty(fieldnames(extras)), params.extras = extras; end + + response = obj.client.sendRequest('injectMarker', params); + result = response.result; + end + + function result = update(obj, markerId, endTime, extras) + if nargin < 4 || isempty(extras), extras = struct(); end + obj.validateRecording(); + if ~ischar(markerId) || isempty(markerId) + error('CortexMarker:markerId', 'markerId must be a non-empty character vector.'); + end + if ~isnumeric(endTime) || ~isscalar(endTime) || ~isfinite(endTime) || endTime < 0 + error('CortexMarker:time', 'endTime must be a non-negative numeric epoch timestamp in milliseconds.'); + end + if ~isstruct(extras) || numel(extras) ~= 1 + error('CortexMarker:extras', 'extras must be a scalar struct.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'markerId', markerId, 'time', double(endTime)); + if ~isempty(fieldnames(extras)), params.extras = extras; end + + response = obj.client.sendRequest('updateMarker', params); + result = response.result; + end + end + + methods (Access = private) + function validateRecording(obj) + if isempty(obj.context.sessionId) + error('CortexMarker:noSession', 'Create an active session before using markers.'); + end + if ~obj.context.isRecording + error('CortexMarker:notRecording', 'Markers can only be used while a record is active.'); + end + end + end +end \ No newline at end of file diff --git a/octave/internal/CortexRecord.m b/octave/internal/CortexRecord.m new file mode 100644 index 0000000..93f5a32 --- /dev/null +++ b/octave/internal/CortexRecord.m @@ -0,0 +1,60 @@ +classdef CortexRecord < handle + % CortexRecord Creates and stops records for the active Cortex session. + + properties (Access = private) + client + context + end + + methods + function obj = CortexRecord(client, context) + obj.client = client; + obj.context = context; + end + + function result = create(obj, title, description, tags) + if isempty(obj.context.sessionId) + error('CortexRecord:noSession', 'Create an active session before starting a record.'); + end + if obj.context.isRecording + error('CortexRecord:alreadyRecording', 'Stop the active record before starting another.'); + end + if ~ischar(title) || isempty(title) || numel(title) > 200 + error('CortexRecord:title', 'title must be a non-empty character vector of at most 200 characters.'); + end + if ~ischar(description) + error('CortexRecord:description', 'description must be a character vector.'); + end + if ischar(tags), tags = {tags}; end + if ~iscellstr(tags) + error('CortexRecord:tags', 'tags must be a character vector or a cell array of character vectors.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId, ... + 'title', title); + if ~isempty(description), params.description = description; end + if ~isempty(tags), params.tags = tags; end + + response = obj.client.sendRequest('createRecord', params); + result = response.result; + if ~isfield(result, 'record') || ~isfield(result.record, 'uuid') + error('CortexRecord:response', 'Cortex did not return the created record id.'); + end + + obj.context.recordId = char(result.record.uuid); + obj.context.isRecording = true; + end + + function result = stop(obj) + if ~obj.context.isRecording || isempty(obj.context.sessionId) + error('CortexRecord:notRecording', 'There is no active record to stop.'); + end + + params = struct('cortexToken', obj.context.token, 'session', obj.context.sessionId); + response = obj.client.sendRequest('stopRecord', params); + result = response.result; + obj.context.isRecording = false; + obj.context.recordId = ''; + end + end +end \ No newline at end of file From b72f2e491c8b60fca41c352cf38158f4834e5239 Mon Sep 17 00:00:00 2001 From: tungntEmotiv Date: Tue, 10 Nov 2026 04:31:02 +0700 Subject: [PATCH 3/5] Cor 6539: update training and set get mental command info example (#248) * COR-6539: update mentalcommand training example * COR-6539: update for get and set mental command info * update rework * update rework --- octave/README.md | 35 +- octave/examples/mentalCommandTraining.m | 314 ++++++++++++++++++ octave/functions/cortexConnect.m | 2 + octave/functions/cortexDisconnect.m | 9 + octave/functions/cortexGetData.m | 12 +- octave/functions/cortexMentalCommandInfo.m | 50 +++ octave/functions/cortexProfile.m | 42 +++ octave/functions/cortexSubscribe.m | 5 +- octave/functions/cortexTraining.m | 39 +++ octave/internal/CortexContext.m | 4 + octave/internal/CortexDataBuffer.m | 13 +- octave/internal/CortexHeadset.m | 18 +- octave/internal/CortexManager.m | 27 ++ .../CortexMentalCommandConfiguration.m | 143 ++++++++ octave/internal/CortexProfile.m | 177 ++++++++++ octave/internal/CortexStreamParser.m | 27 +- octave/internal/CortexTraining.m | 125 +++++++ 17 files changed, 1028 insertions(+), 14 deletions(-) create mode 100644 octave/examples/mentalCommandTraining.m create mode 100644 octave/functions/cortexMentalCommandInfo.m create mode 100644 octave/functions/cortexProfile.m create mode 100644 octave/functions/cortexTraining.m create mode 100644 octave/internal/CortexMentalCommandConfiguration.m create mode 100644 octave/internal/CortexProfile.m create mode 100644 octave/internal/CortexTraining.m diff --git a/octave/README.md b/octave/README.md index b55da92..8030bf7 100644 --- a/octave/README.md +++ b/octave/README.md @@ -13,7 +13,7 @@ The local connection has two parts: ## Folder Structure -- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexDisconnect`) that hide the internal MATLAB classes. +- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexProfile`, `cortexTraining`, `cortexDisconnect`) that hide the internal MATLAB classes. - `internal/`: Internal SDK classes. Not a public interface; they may change. - `lib/`: `nv-websocket-client-2.14.jar` and `cortex-ws-client.jar`, the Java WebSocket client used for WSS. - `java/`: Source of the small Java wrapper (`cortex-ws-client.jar`). @@ -183,6 +183,39 @@ cortex = cortexDisconnect(cortex); `cortexMarker(cortex, 'inject', label, value, ...)` returns `recordId`, `sessionId`, and `marker`. Optional name/value pairs are `time` (epoch milliseconds; defaults to the current time), `port` (defaults to `Software`), and `extras` (a scalar struct). `cortexMarker(cortex, 'update', markerId, endTime, ...)` returns the same result fields and accepts optional `extras`. `endTime` is required and is measured in milliseconds since 1970-01-01 UTC. Both marker actions require an active record. +## Mental Command Training + +`examples/mentalCommandTraining.m` loads (or creates) a profile, trains mental command actions from the keyboard, and shows live commands. + +1. Set `headsetId` and `profileName` near the top of the file, then run: + +```matlab +addpath('octave/examples'); +mentalCommandTraining(); +``` + +2. Focus the figure. `N`, `P`, `L`, `D` start training neutral, push, left and drop (train neutral first). When a training succeeds, press `A` to accept it (this saves the profile) or `R` to reject it. `S` subscribes to `com` and shows the live action and power as text. `U` or `Esc` unloads the profile and exits. + +The same flow with the public functions: + +```matlab +cortex = cortexConnect(); +cortex = cortexSession(cortex, 'INSIGHT-A1B2C3D4'); +[cortex, profile] = cortexProfile(cortex, 'load', 'my-profile'); % creates it when missing +cortex = cortexSubscribe(cortex, {'sys', 'com'}); +started = cortexTraining(cortex, 'mentalCommand', 'push', 'start', 'wait', 30); +if started.isSucceeded + accepted = cortexTraining(cortex, 'mentalCommand', 'push', 'accept', 'wait', 15); % also saves the profile +end +[labels, data, time, mcActions] = cortexGetData(cortex, 'com', 1); % mcActions{end} = action, data(end, 2) = power +[cortex, ~] = cortexProfile(cortex, 'unload'); +cortex = cortexDisconnect(cortex); +``` + +- `[cortex, result] = cortexProfile(cortex, action, profileName)`: `action` is `'load'` (creates the profile if missing), `'save'` or `'unload'` (`profileName` is only needed for `'load'`). `result` has `name`, `uuid`, `existed`, `created` and `isLoaded`. It updates `cortex.isProfileLoaded` and `cortex.profileName`. Errors use `cortex:profileFailed`. +- `result = cortexTraining(cortex, detection, action, status, 'wait', seconds)`: `detection` is `'mentalCommand'` (`'facialExpression'` uses the same call), `action` is any action Cortex lists for the detection (for example `neutral`, `push`, `pull`, `left`, `right`), and `status` is `start`, `accept`, `reject`, `reset` or `erase`. With `'wait'` (requires the `sys` stream), `start` waits for `MC_Succeeded` or `MC_Failed` and `accept` waits for `MC_Completed`, then saves the profile. `result` has `detection`, `action`, `status`, `event`, `isSucceeded` and `profileSaved`. Errors use `cortex:trainingFailed`. +- `cortexGetData(cortex, 'com')` returns labels `{'act','pow'}`. The `act` column of `data` is `NaN`; the mental command actions are in the fourth output `mcActions` (one string per row) and `pow` (0 to 1) is in `data`. + ## Troubleshooting ### Could not connect to Cortex at `wss://localhost:6868` diff --git a/octave/examples/mentalCommandTraining.m b/octave/examples/mentalCommandTraining.m new file mode 100644 index 0000000..72fca99 --- /dev/null +++ b/octave/examples/mentalCommandTraining.m @@ -0,0 +1,314 @@ +function mentalCommandTraining() +% mentalCommandTraining Train mental command actions from the keyboard and watch live commands. +% Set headsetId and profileName below, then call mentalCommandTraining(). +% Keys (focus the figure): N neutral, P push, L left, D drop start a training; +% A accept or R reject the training result; S show live commands; +% U (or Esc) unload the profile and exit. Train neutral first, then at least one action. +% +% The com stream sends one sample per update with two values: +% act the detected action name (for example 'neutral' or 'push') +% pow the action power from 0 to 1 +% It is a label plus a strength rather than a waveform, so it is shown as text instead of a plot. +% To train other actions, add a key that calls trainAction with another action name +% (see getDetectionInfo in the Cortex API for the supported list). + +% Set your headset id and the name of the training profile to create or load. +headsetId = ''; +profileName = 'my-mental-command'; + +trainStartTimeout = 10; +trainAcceptTimeout = 15; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: authorize, connect the headset, create its session and load (or create) the profile. +cortex = cortexConnect(); +fig = []; +statusText = []; +commandText = []; +powerAxes = []; +powerBar = []; +powerLabel = []; +isBusy = false; +isExitRequested = false; +isCommandStreaming = false; +pendingAction = ''; +lastAction = ''; +lastPower = NaN; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('mentalCommandTraining:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + [cortex, profileResult] = cortexProfile(cortex, 'load', profileName); + if profileResult.created + fprintf('[mentalCommandTraining] Created and loaded profile %s.\n', profileName); + else + fprintf('[mentalCommandTraining] Loaded existing profile %s.\n', profileName); + end + + mentalCommandInfo = cortexMentalCommandInfo(cortex, 'get'); + fprintf('[mentalCommandTraining] Mental command info:\n%s\n', ... + jsonencode(mentalCommandInfo, 'PrettyPrint', true)); + + % The sys stream reports the training events (started, succeeded, completed). + cortex = cortexSubscribe(cortex, {'sys'}); + if ~cortex.isSubscribed + error('mentalCommandTraining:subscribe', 'Could not subscribe to the sys stream.'); + end + + fprintf('[mentalCommandTraining] Key help:\n'); + fprintf(' N / P / L / D: start training neutral / push / left / drop.\n'); + fprintf(' A / R: accept / reject the training result.\n'); + fprintf(' S: show live mental commands (act and pow).\n'); + fprintf(' C: set sensitivity push 7, left 8, drop 2.\n'); + fprintf(' U or Esc: unload the profile and exit.\n'); + + fig = figure('Name', 'Cortex Mental Command Training', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress); + helpLines = {'Keyboard controls', '', ... + 'N: train neutral (do this first)', ... + 'P: train push', ... + 'L: train left', ... + 'D: train drop', ... + 'A: accept the training result (saves the profile)', ... + 'R: reject the training result', ... + 'S: show live mental commands (act = action, pow = power 0-1)', ... + 'C: set sensitivity (push 7, left 8, drop 2)', ... + 'U or Esc: unload the profile and exit'}; + uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.44 0.84 0.52], 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 11, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + commandText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.28 0.40 0.12], 'String', '', ... + 'HorizontalAlignment', 'left', 'FontSize', 20, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + powerAxes = axes('Parent', fig, 'Units', 'normalized', 'Position', [0.52 0.29 0.40 0.08], ... + 'XLim', [0 1], 'YLim', [0 1], 'XTick', [], 'YTick', [], 'Box', 'on', 'Visible', 'off'); + powerBar = patch('Parent', powerAxes, 'Faces', [1 2 3 4], ... + 'Vertices', [0 0; 0 0; 0 1; 0 1], 'FaceColor', [0.8 0.2 0.1], 'EdgeColor', 'none', ... + 'Visible', 'off'); + powerLabel = text('Parent', powerAxes, 'Position', [0.5 0.5], 'String', '', ... + 'HorizontalAlignment', 'center', 'Visible', 'off'); + statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.02 0.84 0.20], ... + 'String', ['Profile ' profileName ' ready. Press N to train neutral.'], ... + 'HorizontalAlignment', 'left', 'FontSize', 10, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + + % Acquire: poll keyboard events and, once subscribed, the live mental command stream. + while ~isExitRequested && ishandle(fig) + if isCommandStreaming && ~isBusy + updateCommandDisplay(); + else + pause(0.05); + end + drawnow(); + end +catch failure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: unload the profile and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[mentalCommandTraining] Finished.\n'); + + function onKeyPress(~, event) + if isBusy, return; end + keyName = event.Key; + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + unloadAndExit(); + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 + showStatus(sprintf('Ignored key: %s.', keyName)); + return; + end + + % Process: map each key to a training action, live display or exit. + switch lower(keyCharacter) + case 'n' + trainAction('neutral'); + case 'p' + trainAction('push'); + case 'l' + trainAction('left'); + case 'd' + trainAction('drop'); + case 'a' + finishTraining('accept'); + case 'r' + finishTraining('reject'); + case 's' + startCommandStream(); + case 'c' + configureSensitivity(); + case 'u' + unloadAndExit(); + otherwise + showStatus(sprintf('Ignored key: %s. Use N, P, L, D, A, R, S, C, U or Esc.', keyName)); + end + end + + function trainAction(actionName) + if ~isempty(pendingAction) + showStatus(sprintf('Press A to accept or R to reject the %s training first.', pendingAction)); + return; + end + isBusy = true; + try + showStatus(sprintf('Training %s: hold the mental state until it finishes...', actionName)); + started = cortexTraining(cortex, 'mentalCommand', actionName, 'start', ... + 'wait', trainStartTimeout); + if ~started.isSucceeded + fprintf('[mentalCommandTraining] Training %s failed (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s failed (%s). Press the key to try again.', ... + actionName, started.event)); + else + pendingAction = actionName; + fprintf('[mentalCommandTraining] Training %s succeeded (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s succeeded. Press A to accept or R to reject.', actionName)); + end + catch trainFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', trainFailure.identifier, trainFailure.message); + showStatus(['Training failed: ' trainFailure.message]); + end + isBusy = false; + end + + function finishTraining(status) + if isempty(pendingAction) + showStatus('No training result to accept or reject. Start a training first.'); + return; + end + isBusy = true; + try + if strcmp(status, 'accept') + accepted = cortexTraining(cortex, 'mentalCommand', pendingAction, 'accept', ... + 'wait', trainAcceptTimeout); + fprintf('[mentalCommandTraining] Training %s completed (%s); profile saved: %d.\n', ... + pendingAction, accepted.event, accepted.profileSaved); + if accepted.profileSaved + showStatus(sprintf('Training %s accepted and profile saved.', pendingAction)); + else + showStatus(sprintf('Training %s accepted, but saving the profile failed (see console).', pendingAction)); + end + else + cortexTraining(cortex, 'mentalCommand', pendingAction, 'reject'); + fprintf('[mentalCommandTraining] Training %s rejected.\n', pendingAction); + showStatus(sprintf('Training %s rejected. Press its key to train again.', pendingAction)); + end + pendingAction = ''; + catch finishFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', finishFailure.identifier, finishFailure.message); + showStatus(['Could not ' status ' the training: ' finishFailure.message]); + end + isBusy = false; + end + + function configureSensitivity() + isBusy = true; + try + showStatus('Configuring sensitivity...'); + % Sensitivities follow the order of the active actions, so activate them in this order. + settings = struct('activeActions', {{'neutral', 'push', 'left', 'drop'}}, ... + 'actionSensitivities', [7 8 2]); + configured = cortexMentalCommandInfo(cortex, 'configure', settings); + fprintf('[mentalCommandTraining] Mental command info:\n%s\n', ... + jsonencode(configured, 'PrettyPrint', true)); + showStatus('Sensitivity set: push 7, left 8, drop 2. Profile saved.'); + catch configureFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', configureFailure.identifier, configureFailure.message); + showStatus(['Could not configure sensitivity: ' configureFailure.message]); + end + isBusy = false; + end + + function startCommandStream() + if isCommandStreaming + showStatus('Live commands are already shown.'); + return; + end + isBusy = true; + try + cortex = cortexSubscribe(cortex, {'com'}); + if ~any(strcmp(cortex.streams, 'com')) + error('mentalCommandTraining:subscribe', 'Could not subscribe to the com stream.'); + end + isCommandStreaming = true; + set([powerAxes powerBar powerLabel], 'Visible', 'on'); + showStatus('Showing live mental commands. Train more actions with N, P, L or D.'); + catch subscribeFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', subscribeFailure.identifier, subscribeFailure.message); + showStatus(['Subscribe failed: ' subscribeFailure.message]); + end + isBusy = false; + end + + function updateCommandDisplay() + [labels, data, ~, actions] = cortexGetData(cortex, 'com', 1); + if isempty(data) || isempty(actions), return; end + powerColumn = find(strcmp(labels, 'pow'), 1); + if isempty(powerColumn), return; end + + action = actions{end}; + power = data(end, powerColumn); + isSamePower = (isnan(power) && isnan(lastPower)) || power == lastPower; + if strcmp(action, lastAction) && isSamePower, return; end + if ~strcmp(action, lastAction) + fprintf('[mentalCommandTraining] Action: %s (pow %.2f)\n', action, power); + end + lastAction = action; + lastPower = power; + + if isnan(power), power = 0; end + level = max(0, min(1, power)); + % Red (weak) through yellow to green (strong). + barColor = [min(1, 2 * (1 - level)), min(1, 2 * level), 0.1]; + if ishandle(commandText) + set(commandText, 'String', action); + end + if ishandle(powerBar) + set(powerBar, 'Vertices', [0 0; level 0; level 1; 0 1], 'FaceColor', barColor); + end + if ishandle(powerLabel) + set(powerLabel, 'String', sprintf('%.2f', power)); + end + end + + function unloadAndExit() + isBusy = true; + showStatus('Unloading the profile, please wait...'); + try + [cortex, unloadResult] = cortexProfile(cortex, 'unload'); + fprintf('[mentalCommandTraining] Profile %s unloaded.\n', unloadResult.name); + isExitRequested = true; + catch unloadFailure + fprintf('[mentalCommandTraining] ERROR %s: %s\n', unloadFailure.identifier, unloadFailure.message); + showStatus(['Could not unload the profile: ' unloadFailure.message ' Press U to try again.']); + isBusy = false; + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end diff --git a/octave/functions/cortexConnect.m b/octave/functions/cortexConnect.m index 24472fa..7639687 100644 --- a/octave/functions/cortexConnect.m +++ b/octave/functions/cortexConnect.m @@ -10,6 +10,7 @@ % manager internal handle used by cortexDisconnect; do not modify % isSubscribed, headsetId, sessionId, streams filled in by headset connection/subscription % isRecording, recordId filled in by cortexRecord +% isProfileLoaded, profileName filled in by cortexProfile functionsDir = fileparts(mfilename('fullpath')); addpath(fullfile(functionsDir, '..', 'internal')); @@ -18,6 +19,7 @@ cortex = struct('isConnected', false, 'token', '', 'userInfo', [], 'licenseInfo', [], 'manager', [], ... 'isSubscribed', false, 'isRecording', false, 'recordId', '', ... + 'isProfileLoaded', false, 'profileName', '', ... 'headsetId', '', 'sessionId', '', 'streams', {{}}); manager = CortexManager(clientId, clientSecret, 'localhost', port); cortex.manager = manager; diff --git a/octave/functions/cortexDisconnect.m b/octave/functions/cortexDisconnect.m index 413f91e..0e2521d 100644 --- a/octave/functions/cortexDisconnect.m +++ b/octave/functions/cortexDisconnect.m @@ -3,6 +3,13 @@ % cortex = cortexDisconnect(cortex) is safe to call even if cortexConnect failed. if isstruct(cortex) && isfield(cortex, 'manager') && ~isempty(cortex.manager) + try + if cortex.manager.getContext().isProfileLoaded + cortex.manager.getProfile().unload(); + end + catch failure + fprintf('[cortexDisconnect] Could not unload the profile: %s\n', failure.message); + end fprintf('[cortexDisconnect] Closing Cortex connection...\n'); try cortex.manager.close(); @@ -16,6 +23,8 @@ cortex.isSubscribed = false; cortex.isRecording = false; cortex.recordId = ''; +cortex.isProfileLoaded = false; +cortex.profileName = ''; cortex.headsetId = ''; cortex.sessionId = ''; cortex.streams = {}; diff --git a/octave/functions/cortexGetData.m b/octave/functions/cortexGetData.m index 0564d42..d456841 100644 --- a/octave/functions/cortexGetData.m +++ b/octave/functions/cortexGetData.m @@ -1,16 +1,20 @@ -function [labels, data, time] = cortexGetData(cortex, stream, lastN) -% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow or met). -% [labels, data, time] = cortexGetData(cortex, 'eeg', 256) first collects the data that has +function [labels, data, time, mcActions] = cortexGetData(cortex, stream, lastN) +% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow, met or com). +% [labels, data, time, mcActions] = cortexGetData(cortex, 'eeg', 256) first collects the data that has % arrived (this can take up to about 1 second), then returns the newest 256 samples: % labels cell array with one name per column of data % data samples-by-columns matrix, oldest sample first (NaN where a value is empty) % time sample times in seconds +% mcActions cell array with one mental command action per sample for com, '' for other streams +% For com, labels are {'act','pow'}: the act column of data is NaN and mcActions holds the action, +% while pow (0 to 1) is the action power. % Omit lastN to get everything in the buffer (the last 10000 samples per stream). if nargin < 3, lastN = []; end labels = {}; data = []; time = []; +mcActions = {}; if ~isstruct(cortex) || ~isfield(cortex, 'isSubscribed') || ~cortex.isSubscribed fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); @@ -23,5 +27,5 @@ fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); return; end -[labels, data, time] = cortex.manager.getContext().buffer.read(stream, lastN); +[labels, data, time, mcActions] = cortex.manager.getContext().buffer.read(stream, lastN); end diff --git a/octave/functions/cortexMentalCommandInfo.m b/octave/functions/cortexMentalCommandInfo.m new file mode 100644 index 0000000..3e1e023 --- /dev/null +++ b/octave/functions/cortexMentalCommandInfo.m @@ -0,0 +1,50 @@ +function config = cortexMentalCommandInfo(cortex, action, settings) +% cortexMentalCommandInfo Get or configure the mental command settings of the loaded profile. +% config = cortexMentalCommandInfo(cortex, 'get') +% config = cortexMentalCommandInfo(cortex, 'configure', settings) +% settings is a struct with any of these fields: +% activeActions cell array of actions to activate (at most 4 besides neutral) +% actionSensitivities up to 4 values from 1 to 10, in the order of the active actions +% config fields: currentTrainingThreshold, possibleActions, totalTrainingCount, +% trainingDuration and trainedActions (cell array of structs with action, active, +% sensitivity ([] when not applicable) and trainingCount). 'configure' saves the profile, +% then returns the configuration read back after the change. +% Requires cortexSession and cortexProfile(cortex, 'load', ...). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:mentalCommandFailed', 'Connect to Cortex before using mental command operations.'); + end + if ~ischar(action) + error('cortex:mentalCommandFailed', 'action must be ''get'' or ''configure''.'); + end + + mentalCommand = cortex.manager.getMentalCommandConfiguration(); + switch lower(action) + case 'get' + config = mentalCommand.get(); + case 'configure' + if nargin < 3 || ~isstruct(settings) + error('cortex:mentalCommandFailed', 'Configure requires a settings struct.'); + end + unknown = setdiff(fieldnames(settings), {'activeActions', 'actionSensitivities'}); + if ~isempty(unknown) + error('cortex:mentalCommandFailed', ... + 'Unknown setting "%s". Supported: activeActions, actionSensitivities.', unknown{1}); + end + activeActions = []; + sensitivities = []; + if isfield(settings, 'activeActions'), activeActions = settings.activeActions; end + if isfield(settings, 'actionSensitivities'), sensitivities = settings.actionSensitivities; end + mentalCommand.set(activeActions, sensitivities); + cortex.manager.getProfile().save(); + config = mentalCommand.get(); + otherwise + error('cortex:mentalCommandFailed', 'action must be ''get'' or ''configure''.'); + end +catch failure + if strcmp(failure.identifier, 'cortex:mentalCommandFailed'), rethrow(failure); end + error('cortex:mentalCommandFailed', 'Mental command operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexProfile.m b/octave/functions/cortexProfile.m new file mode 100644 index 0000000..25d0273 --- /dev/null +++ b/octave/functions/cortexProfile.m @@ -0,0 +1,42 @@ +function [cortex, result] = cortexProfile(cortex, action, profileName) +% cortexProfile Load, save or unload a training profile for the active headset. +% [cortex, result] = cortexProfile(cortex, 'load', profileName) loads the profile and +% creates it first when it does not exist yet. +% [cortex, result] = cortexProfile(cortex, 'save') saves the loaded profile. +% [cortex, result] = cortexProfile(cortex, 'unload') unloads the loaded profile. +% result fields: name, uuid ('' when Cortex gives none), existed, created and isLoaded. +% cortex.isProfileLoaded and cortex.profileName are updated. Call cortexSession first. + +result = []; +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:profileFailed', 'Connect to Cortex before using profile operations.'); + end + if ~ischar(action) + error('cortex:profileFailed', 'action must be ''load'', ''save'' or ''unload''.'); + end + + profile = cortex.manager.getProfile(); + switch lower(action) + case 'load' + if nargin < 3 + error('cortex:profileFailed', 'Load requires a profile name.'); + end + result = profile.loadOrCreate(profileName); + case 'save' + result = profile.save(); + case 'unload' + result = profile.unload(); + otherwise + error('cortex:profileFailed', 'action must be ''load'', ''save'' or ''unload''.'); + end + + context = cortex.manager.getContext(); + cortex.isProfileLoaded = context.isProfileLoaded; + cortex.profileName = context.profileName; +catch failure + if strcmp(failure.identifier, 'cortex:profileFailed'), rethrow(failure); end + error('cortex:profileFailed', 'Profile operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexSubscribe.m b/octave/functions/cortexSubscribe.m index b5397a9..9ae4435 100644 --- a/octave/functions/cortexSubscribe.m +++ b/octave/functions/cortexSubscribe.m @@ -1,6 +1,7 @@ function cortex = cortexSubscribe(cortex, streams) % cortexSubscribe Subscribe to streams on an active headset session. -% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met'}) +% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met','com','sys'}) +% com (mental command) needs a loaded profile; sys carries training events. % Update the fields: % isSubscribed true when the streams are being received % streams the subscribed stream names @@ -13,7 +14,7 @@ end if ischar(streams), streams = {streams}; end -validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met'}; +validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met', 'com', 'sys'}; if ~iscellstr(streams) || isempty(streams) || ~all(ismember(streams, validStreams)) fprintf('[cortexSubscribe] ERROR streams must be a non-empty list of: %s.\n', strjoin(validStreams, ', ')); return; diff --git a/octave/functions/cortexTraining.m b/octave/functions/cortexTraining.m new file mode 100644 index 0000000..f2b1234 --- /dev/null +++ b/octave/functions/cortexTraining.m @@ -0,0 +1,39 @@ +function result = cortexTraining(cortex, detection, action, status, varargin) +% cortexTraining Train an action of a detection on the loaded profile. +% result = cortexTraining(cortex, 'mentalCommand', 'push', 'start', 'wait', 30) +% result = cortexTraining(cortex, 'mentalCommand', 'push', 'accept', 'wait', 15) +% detection 'mentalCommand' ('facialExpression' uses the same call) +% action any action Cortex lists for the detection, for example neutral, push, left, right +% status start, accept, reject, reset or erase +% 'wait', seconds block until Cortex reports the outcome (needs the sys stream): +% start waits for MC_Succeeded or MC_Failed, accept waits for MC_Completed. +% Accepting a completed training also saves the profile. +% result fields: detection, action, status, event ('' without wait), isSucceeded, profileSaved. +% Requires cortexSession, cortexProfile(cortex, 'load', ...) and cortexSubscribe(cortex, {'sys'}). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:trainingFailed', 'Connect to Cortex before training.'); + end + if ~ischar(detection) || ~ischar(action) || ~ischar(status) + error('cortex:trainingFailed', 'detection, action and status must be character vectors.'); + end + if mod(numel(varargin), 2) ~= 0 + error('cortex:trainingFailed', 'Options must be supplied as name/value pairs.'); + end + + waitSeconds = 0; + for index = 1:2:numel(varargin) + if ~ischar(varargin{index}) || ~strcmp(varargin{index}, 'wait') + error('cortex:trainingFailed', 'Unknown training option. Supported: wait.'); + end + waitSeconds = varargin{index + 1}; + end + + result = cortex.manager.getTraining().train(detection, action, status, waitSeconds); +catch failure + if strcmp(failure.identifier, 'cortex:trainingFailed'), rethrow(failure); end + error('cortex:trainingFailed', 'Training operation failed: %s', failure.message); +end +end diff --git a/octave/internal/CortexContext.m b/octave/internal/CortexContext.m index b012c14..fa86e95 100644 --- a/octave/internal/CortexContext.m +++ b/octave/internal/CortexContext.m @@ -12,6 +12,10 @@ subscribedStreams = {} isRecording = false recordId = '' + profileName = '' + isProfileLoaded = false + detectionInfo = struct() % per detection: cell arrays actions, controls and events, set on profile load + trainingEvents = {} % structs with detection, event and time from the sys stream streamLabels = struct() % one field per stream, each a cell array of column labels buffer = [] % CortexDataBuffer holding the received samples end diff --git a/octave/internal/CortexDataBuffer.m b/octave/internal/CortexDataBuffer.m index ccb57c2..7c96cc3 100644 --- a/octave/internal/CortexDataBuffer.m +++ b/octave/internal/CortexDataBuffer.m @@ -11,6 +11,7 @@ labels = {} samples = {} times = {} + mcActions = {} nextRow = [] count = [] end @@ -30,16 +31,20 @@ function configure(obj, stream, labels) obj.labels{idx} = labels; obj.samples{idx} = []; obj.times{idx} = []; + obj.mcActions{idx} = {}; obj.nextRow(idx) = 1; obj.count(idx) = 0; end - function append(obj, stream, row, time) + function append(obj, stream, row, time, mcAction) + % mcAction is optional: the mental command action of a com sample. + if nargin < 5, mcAction = ''; end idx = obj.indexOf(stream); width = numel(row); if isempty(obj.samples{idx}) obj.samples{idx} = NaN(obj.capacity, width); obj.times{idx} = NaN(obj.capacity, 1); + obj.mcActions{idx} = cell(obj.capacity, 1); end columns = size(obj.samples{idx}, 2); @@ -52,15 +57,17 @@ function append(obj, stream, row, time) r = obj.nextRow(idx); obj.samples{idx}(r, :) = row; obj.times{idx}(r) = time; + obj.mcActions{idx}{r} = mcAction; obj.nextRow(idx) = mod(r, obj.capacity) + 1; obj.count(idx) = min(obj.count(idx) + 1, obj.capacity); end - function [labels, data, time] = read(obj, stream, lastN) + function [labels, data, time, mcActions] = read(obj, stream, lastN) % Returns the newest lastN samples (all buffered samples when lastN is omitted). labels = {}; data = []; time = []; + mcActions = {}; idx = find(strcmp(obj.names, stream), 1); if isempty(idx), return; end @@ -75,6 +82,7 @@ function append(obj, stream, row, time) rows = mod((newest - n + 1:newest) - 1, obj.capacity) + 1; data = obj.samples{idx}(rows, :); time = obj.times{idx}(rows); + mcActions = obj.mcActions{idx}(rows); end function n = numSamples(obj, stream) @@ -96,6 +104,7 @@ function append(obj, stream, row, time) obj.labels{idx} = {}; obj.samples{idx} = []; obj.times{idx} = []; + obj.mcActions{idx} = {}; obj.nextRow(idx) = 1; obj.count(idx) = 0; end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m index c636377..5a0fe45 100644 --- a/octave/internal/CortexHeadset.m +++ b/octave/internal/CortexHeadset.m @@ -233,6 +233,8 @@ function onSessionClosed(obj, warning) obj.context.subscribedStreams = {}; obj.context.isRecording = false; obj.context.recordId = ''; + obj.context.profileName = ''; + obj.context.isProfileLoaded = false; obj.parser.reset(); fprintf('[CortexHeadset] Session %s was closed by Cortex.\n', warning.message.sessionId); end @@ -248,9 +250,21 @@ function runScanTimer(obj) end function storeSample(obj, msg) - [stream, row, time] = obj.parser.parse(msg); + [stream, row, time, mcAction] = obj.parser.parse(msg); if isempty(stream), return; end - obj.context.buffer.append(stream, row, time); + if strcmp(stream, 'sys') + obj.storeSystemEvent(msg.sys, time); + return; + end + obj.context.buffer.append(stream, row, time, mcAction); + end + + function storeSystemEvent(obj, values, time) + % A sys sample is {detection, event}, for example {'mentalCommand', 'MC_Started'}. + names = CortexStreamParser.stringsOf(values); + if numel(names) < 2, return; end + obj.context.trainingEvents{end + 1} = ... + struct('detection', names{1}, 'event', names{2}, 'time', time); end end diff --git a/octave/internal/CortexManager.m b/octave/internal/CortexManager.m index 93a4cab..1354ee4 100644 --- a/octave/internal/CortexManager.m +++ b/octave/internal/CortexManager.m @@ -15,6 +15,9 @@ headset = [] record = [] marker = [] + profile = [] + training = [] + mentalCommand = [] end methods @@ -69,6 +72,27 @@ marker = obj.marker; end + function profile = getProfile(obj) + if isempty(obj.profile) + obj.profile = CortexProfile(obj.getClient(), obj.context); + end + profile = obj.profile; + end + + function training = getTraining(obj) + if isempty(obj.training) + obj.training = CortexTraining(obj.getClient(), obj.context, obj.getHeadset(), obj.getProfile()); + end + training = obj.training; + end + + function mentalCommand = getMentalCommandConfiguration(obj) + if isempty(obj.mentalCommand) + obj.mentalCommand = CortexMentalCommandConfiguration(obj.getClient(), obj.context); + end + mentalCommand = obj.mentalCommand; + end + function close(obj) % Only closes what was actually created. if ~isempty(obj.headset) @@ -83,6 +107,9 @@ function close(obj) end obj.record = []; obj.marker = []; + obj.profile = []; + obj.training = []; + obj.mentalCommand = []; end end end diff --git a/octave/internal/CortexMentalCommandConfiguration.m b/octave/internal/CortexMentalCommandConfiguration.m new file mode 100644 index 0000000..c9a0bce --- /dev/null +++ b/octave/internal/CortexMentalCommandConfiguration.m @@ -0,0 +1,143 @@ +classdef CortexMentalCommandConfiguration < handle + % CortexMentalCommandConfiguration Reads and writes the mental command configuration of the loaded profile. + + properties (Access = private) + client + context + end + + methods + function obj = CortexMentalCommandConfiguration(client, context) + obj.client = client; + obj.context = context; + end + + function config = get(obj) + obj.requireSession(); + token = obj.context.token; + session = obj.context.sessionId; + detection = 'mentalCommand'; + + info = obj.context.detectionInfo.(detection); + signature = obj.client.sendRequest('getTrainedSignatureActions', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + active = obj.getActiveActions(); + sensitivity = obj.getSensitivity(); + threshold = obj.client.sendRequest('mentalCommandTrainingThreshold', ... + struct('cortexToken', token, 'session', session)).result; + duration = obj.client.sendRequest('getTrainingTime', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + + sensitiveActions = CortexMentalCommandConfiguration.sensitiveActions(active); + trained = CortexMentalCommandConfiguration.toCell(CortexMentalCommandConfiguration.field(signature, 'trainedActions', {})); + trainedActions = cell(1, numel(trained)); + for index = 1:numel(trained) + name = trained{index}.action; + value = []; + position = find(strcmp(sensitiveActions, name), 1); + if ~isempty(position) && position <= numel(sensitivity) + value = sensitivity(position); + end + trainedActions{index} = struct('action', name, ... + 'active', strcmp(name, 'neutral') || any(strcmp(active, name)), ... + 'sensitivity', value, ... + 'trainingCount', CortexMentalCommandConfiguration.field(trained{index}, 'times', 0)); + end + + config = struct( ... + 'currentTrainingThreshold', CortexMentalCommandConfiguration.field(threshold, 'currentThreshold', []), ... + 'possibleActions', {info.actions}, ... + 'totalTrainingCount', CortexMentalCommandConfiguration.field(signature, 'totalTimesTraining', 0), ... + 'trainedActions', {trainedActions}, ... + 'trainingDuration', CortexMentalCommandConfiguration.field(duration, 'time', [])); + end + + function set(obj, activeActions, sensitivity) + % Either argument may be [] to leave it unchanged. + obj.requireSession(); + token = obj.context.token; + session = obj.context.sessionId; + + if ~isempty(activeActions) + if ischar(activeActions), activeActions = {activeActions}; end + if ~iscellstr(activeActions) + error('CortexMentalCommandConfiguration:argument', 'activeActions must be a cell array of action names.'); + end + info = obj.context.detectionInfo.mentalCommand; + for index = 1:numel(activeActions) + if ~any(strcmp(info.actions, activeActions{index})) + error('CortexMentalCommandConfiguration:argument', 'Unsupported action "%s".', activeActions{index}); + end + end + if numel(setdiff(activeActions, {'neutral'})) > 4 + error('CortexMentalCommandConfiguration:argument', 'At most 4 actions (excluding neutral) can be active.'); + end + obj.client.sendRequest('mentalCommandActiveAction', struct('cortexToken', token, ... + 'session', session, 'status', 'set', 'actions', {activeActions(:)'})); + end + + if ~isempty(sensitivity) + if ~isnumeric(sensitivity) || numel(sensitivity) > 4 || any(sensitivity < 1 | sensitivity > 10) + error('CortexMentalCommandConfiguration:argument', ... + 'sensitivity must have up to 4 values between 1 and 10, in the order of the active actions.'); + end + values = obj.getSensitivity(); + values(1:numel(sensitivity)) = sensitivity(:)'; + obj.client.sendRequest('mentalCommandActionSensitivity', struct('cortexToken', token, ... + 'session', session, 'status', 'set', 'values', values(:)')); + end + end + end + + methods (Access = private) + function requireSession(obj) + if isempty(obj.context.sessionId) + error('CortexMentalCommandConfiguration:noSession', 'Create a headset session first.'); + end + if ~obj.context.isProfileLoaded + error('CortexMentalCommandConfiguration:noProfile', 'Load a profile first.'); + end + end + + function active = getActiveActions(obj) + response = obj.client.sendRequest('mentalCommandActiveAction', struct( ... + 'cortexToken', obj.context.token, 'session', obj.context.sessionId, 'status', 'get')); + active = CortexMentalCommandConfiguration.toCell(response.result); + end + + function values = getSensitivity(obj) + response = obj.client.sendRequest('mentalCommandActionSensitivity', struct( ... + 'cortexToken', obj.context.token, 'session', obj.context.sessionId, 'status', 'get')); + values = double(response.result(:)'); + values = [values, 5 * ones(1, max(0, 4 - numel(values)))]; + end + end + + methods (Static, Access = private) + function actions = sensitiveActions(active) + % Sensitivity values follow the active actions; neutral has none, and only 4 are kept. + actions = active(~strcmp(active, 'neutral')); + actions = actions(1:min(4, numel(actions))); + end + + function items = toCell(value) + if iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + elseif ischar(value) + items = {value}; + else + items = {}; + end + end + + function value = field(source, name, default) + if isstruct(source) && isfield(source, name) + value = source.(name); + else + value = default; + end + end + end +end diff --git a/octave/internal/CortexProfile.m b/octave/internal/CortexProfile.m new file mode 100644 index 0000000..f061692 --- /dev/null +++ b/octave/internal/CortexProfile.m @@ -0,0 +1,177 @@ +classdef CortexProfile < handle + % CortexProfile Queries, creates, loads, saves and unloads training profiles for the active headset. + + properties (Access = private) + client + context + end + + methods + function obj = CortexProfile(client, context) + obj.client = client; + obj.context = context; + end + + function profiles = query(obj) + params = struct('cortexToken', obj.context.token); + response = obj.client.sendRequest('queryProfile', params); + profiles = CortexProfile.toCell(response.result); + end + + function profile = findProfile(obj, profileName) + profile = []; + profiles = obj.query(); + for index = 1:numel(profiles) + item = profiles{index}; + if isstruct(item) && isfield(item, 'name') && strcmp(item.name, profileName) + profile = item; + return; + end + end + end + + function result = loadOrCreate(obj, profileName) + CortexProfile.validateName(profileName); + obj.requireHeadset(); + + if obj.context.isProfileLoaded + if strcmp(obj.context.profileName, profileName) + info = obj.context.detectionInfo; + if ~isstruct(info) || ~isfield(info, 'mentalCommand') || ~isfield(info, 'facialExpression') + obj.loadDetectionInfo(); + end + result = CortexProfile.makeResult(profileName, '', true, false, true); + return; + end + error('CortexProfile:otherLoaded', ... + 'Profile %s is already loaded. Unload it before loading %s.', ... + obj.context.profileName, profileName); + end + + existing = obj.findProfile(profileName); + created = isempty(existing); + uuid = ''; + if created + fprintf('[CortexProfile] Profile %s not found; creating it...\n', profileName); + createResult = obj.setup(profileName, 'create'); + uuid = CortexProfile.textField(createResult, 'uuid'); + else + uuid = CortexProfile.textField(existing, 'uuid'); + end + + fprintf('[CortexProfile] Loading profile %s...\n', profileName); + loadResult = obj.setup(profileName, 'load'); + if isempty(uuid), uuid = CortexProfile.textField(loadResult, 'uuid'); end + + obj.context.profileName = profileName; + obj.context.isProfileLoaded = true; + obj.loadDetectionInfo(); + result = CortexProfile.makeResult(profileName, uuid, ~created, created, true); + end + + function result = save(obj) + obj.requireLoaded(); + name = obj.context.profileName; + setupResult = obj.setup(name, 'save'); + result = CortexProfile.makeResult(name, CortexProfile.textField(setupResult, 'uuid'), ... + true, false, true); + end + + function result = unload(obj) + obj.requireLoaded(); + name = obj.context.profileName; + setupResult = obj.setup(name, 'unload'); + obj.context.profileName = ''; + obj.context.isProfileLoaded = false; + obj.context.detectionInfo = struct(); + result = CortexProfile.makeResult(name, CortexProfile.textField(setupResult, 'uuid'), ... + true, false, false); + end + end + + methods (Access = private) + function loadDetectionInfo(obj) + maxAttempts = 3; + for detection = {'mentalCommand', 'facialExpression'} + for attempt = 1:maxAttempts + try + response = obj.client.sendRequest('getDetectionInfo', struct('detection', detection{1})); + break; + catch err + if attempt == maxAttempts + rethrow(err); + end + end + end + result = response.result; + obj.context.detectionInfo.(detection{1}) = struct( ... + 'actions', {CortexProfile.toStrings(result, 'actions')}, ... + 'controls', {CortexProfile.toStrings(result, 'controls')}, ... + 'events', {CortexProfile.toStrings(result, 'events')}); + end + end + + function result = setup(obj, profileName, status) + params = struct('cortexToken', obj.context.token, 'headset', obj.context.headsetId, ... + 'profile', profileName, 'status', status); + response = obj.client.sendRequest('setupProfile', params); + result = response.result; + end + + function requireHeadset(obj) + if isempty(obj.context.headsetId) + error('CortexProfile:noSession', 'Create a headset session before using profiles.'); + end + end + + function requireLoaded(obj) + if ~obj.context.isProfileLoaded + error('CortexProfile:notLoaded', 'No profile is loaded.'); + end + end + end + + methods (Static, Access = private) + function validateName(profileName) + if ~ischar(profileName) || isempty(profileName) + error('CortexProfile:name', 'profileName must be a non-empty character vector.'); + end + end + + function result = makeResult(name, uuid, existed, created, isLoaded) + result = struct('name', name, 'uuid', uuid, 'existed', existed, ... + 'created', created, 'isLoaded', isLoaded); + end + + function text = textField(item, fieldName) + text = ''; + if isstruct(item) && isfield(item, fieldName) && ischar(item.(fieldName)) + text = item.(fieldName); + end + end + + function items = toStrings(result, fieldName) + items = {}; + if ~isstruct(result) || ~isfield(result, fieldName), return; end + value = result.(fieldName); + if ischar(value) + items = {value}; + elseif iscell(value) + items = value(:)'; + end + end + + function items = toCell(value) + % jsondecode returns a struct array or a cell array depending on the content. + if isempty(value) + items = {}; + elseif iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + else + items = {}; + end + end + end +end diff --git a/octave/internal/CortexStreamParser.m b/octave/internal/CortexStreamParser.m index 2804cd7..7b16ed5 100644 --- a/octave/internal/CortexStreamParser.m +++ b/octave/internal/CortexStreamParser.m @@ -18,14 +18,22 @@ function reset(obj) obj.streams = {}; end - function [stream, row, time] = parse(obj, msg) + function [stream, row, time, mcAction] = parse(obj, msg) % stream is '' when the message does not belong to a registered stream. + % mcAction is the mental command action of a com sample ('' for other streams). stream = ''; row = []; time = NaN; + mcAction = ''; if isfield(msg, 'sid') && ischar(msg.sid) - index = find(strcmp(obj.sids, msg.sid), 1); - if ~isempty(index), stream = obj.streams{index}; end + % Streams of one session can share the same sid, so match the stream by its field name too. + candidates = find(strcmp(obj.sids, msg.sid)); + for index = candidates + if isfield(msg, obj.streams{index}) + stream = obj.streams{index}; + break; + end + end end if isempty(stream) || ~isfield(msg, stream) stream = ''; @@ -36,10 +44,23 @@ function reset(obj) time = double(msg.time); end row = CortexStreamParser.flattenSample(msg.(stream)); + names = CortexStreamParser.stringsOf(msg.(stream)); + if ~isempty(names), mcAction = names{1}; end end end methods (Static) + function names = stringsOf(values) + if ischar(values) + names = {values}; + elseif iscell(values) + names = values(cellfun(@ischar, values)); + names = names(:)'; + else + names = {}; + end + end + function labels = flattenLabels(cols) % The dev stream nests the contact-quality labels in a sub-array. if ischar(cols) diff --git a/octave/internal/CortexTraining.m b/octave/internal/CortexTraining.m new file mode 100644 index 0000000..780bfc2 --- /dev/null +++ b/octave/internal/CortexTraining.m @@ -0,0 +1,125 @@ +classdef CortexTraining < handle + % CortexTraining Trains mental command or facial expression actions on the loaded profile. + % Training progress arrives as events on the "sys" stream, so subscribe to it to wait for results. + + properties (Access = private) + client + context + headset + profile + end + + methods + function obj = CortexTraining(client, context, headset, profile) + obj.client = client; + obj.context = context; + obj.headset = headset; + obj.profile = profile; + end + + function result = train(obj, detection, action, status, waitSeconds) + if nargin < 5, waitSeconds = 0; end + detection = CortexTraining.normalizeDetection(detection); + if isempty(obj.context.sessionId) + error('CortexTraining:noSession', 'Create a headset session before training.'); + end + if ~obj.context.isProfileLoaded + error('CortexTraining:noProfile', 'Load a profile before training.'); + end + if ~isnumeric(waitSeconds) || ~isscalar(waitSeconds) || waitSeconds < 0 + error('CortexTraining:wait', 'wait must be a non-negative number of seconds.'); + end + + info = obj.context.detectionInfo.(detection); + action = CortexTraining.canonical(info.actions, action, 'action', detection); + status = CortexTraining.canonical(info.controls, status, 'status', detection); + + finalEvents = {}; + switch status + case 'start' + finalEvents = {'Succeeded', 'Failed'}; + case 'accept' + finalEvents = {'Completed'}; + end + shouldWait = waitSeconds > 0 && ~isempty(finalEvents); + if shouldWait && ~any(strcmp(obj.context.subscribedStreams, 'sys')) + error('CortexTraining:noSysStream', 'Subscribe to the sys stream to wait for training events.'); + end + + obj.context.trainingEvents = {}; + params = struct('cortexToken', obj.context.token, 'detection', detection, ... + 'session', obj.context.sessionId, 'action', action, 'status', status); + obj.client.sendRequest('training', params); + + result = struct('detection', detection, 'action', action, 'status', status, ... + 'event', '', 'isSucceeded', false, 'profileSaved', false); + if ~shouldWait, return; end + + event = obj.waitForEvent(finalEvents, waitSeconds); + if isempty(event) + error('CortexTraining:timeout', 'No %s %s event within %g seconds.', ... + detection, strjoin(finalEvents, '/'), waitSeconds); + end + result.event = event; + result.isSucceeded = ~isempty(regexp(event, '_(Succeeded|Completed)$', 'once')); + + if strcmp(status, 'accept') && result.isSucceeded + try + obj.profile.save(); + result.profileSaved = true; + catch err + fprintf('[CortexTraining] Training completed but saving the profile failed: %s\n', err.message); + end + end + end + end + + methods (Access = private) + function event = waitForEvent(obj, suffixes, waitSeconds) + event = ''; + pattern = ['_(' strjoin(suffixes, '|') ')$']; + startedAt = tic(); + seen = 0; + while toc(startedAt) < waitSeconds + obj.headset.update(0.25); + events = obj.context.trainingEvents; + for index = seen + 1:numel(events) + if ~isempty(regexp(events{index}.event, pattern, 'once')) + event = events{index}.event; + return; + end + end + seen = numel(events); + end + end + end + + methods (Static, Access = private) + function detection = normalizeDetection(detection) + if ~ischar(detection) + error('CortexTraining:detection', 'detection must be ''mentalCommand'' or ''facialExpression''.'); + end + switch lower(detection) + case 'mentalcommand' + detection = 'mentalCommand'; + case 'facialexpression' + detection = 'facialExpression'; + otherwise + error('CortexTraining:detection', ... + 'detection must be ''mentalCommand'' or ''facialExpression''.'); + end + end + + function value = canonical(allowed, value, kind, detection) + if ~ischar(value) || isempty(value) + error('CortexTraining:argument', '%s must be a non-empty character vector.', kind); + end + index = find(strcmpi(allowed, value), 1); + if isempty(index) + error('CortexTraining:argument', 'Unsupported %s "%s" for %s. Supported: %s.', ... + kind, value, detection, strjoin(allowed, ', ')); + end + value = allowed{index}; + end + end +end From b016db6b365f63f47f0bd872a12dfce5bc584ca8 Mon Sep 17 00:00:00 2001 From: tungntEmotiv Date: Tue, 10 Nov 2026 13:25:04 +0700 Subject: [PATCH 4/5] COR-6553: update facial expression example (#249) * COR-6553: update facial expression example * update rework * Fix facial expression thresholds Co-authored-by: tungntEmotiv <21233798+tungntEmotiv@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tungntEmotiv <21233798+tungntEmotiv@users.noreply.github.com> --- octave/README.md | 24 +- octave/examples/facialExpressionTraining.m | 328 ++++++++++++++++++ octave/functions/cortexFacialExpressionInfo.m | 21 ++ octave/functions/cortexGetData.m | 16 +- octave/functions/cortexSubscribe.m | 6 +- octave/internal/CortexDataBuffer.m | 22 +- .../CortexFacialExpressionConfiguration.m | 77 ++++ octave/internal/CortexHeadset.m | 4 +- octave/internal/CortexManager.m | 9 + octave/internal/CortexStreamParser.m | 13 +- 10 files changed, 489 insertions(+), 31 deletions(-) create mode 100644 octave/examples/facialExpressionTraining.m create mode 100644 octave/functions/cortexFacialExpressionInfo.m create mode 100644 octave/internal/CortexFacialExpressionConfiguration.m diff --git a/octave/README.md b/octave/README.md index 8030bf7..a766650 100644 --- a/octave/README.md +++ b/octave/README.md @@ -13,7 +13,7 @@ The local connection has two parts: ## Folder Structure -- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexProfile`, `cortexTraining`, `cortexDisconnect`) that hide the internal MATLAB classes. +- `functions/`: Public functions (`cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexGetData`, `cortexRecord`, `cortexMarker`, `cortexProfile`, `cortexTraining`, `cortexMentalCommandInfo`, `cortexFacialExpressionInfo`, `cortexDisconnect`) that hide the internal MATLAB classes. - `internal/`: Internal SDK classes. Not a public interface; they may change. - `lib/`: `nv-websocket-client-2.14.jar` and `cortex-ws-client.jar`, the Java WebSocket client used for WSS. - `java/`: Source of the small Java wrapper (`cortex-ws-client.jar`). @@ -207,14 +207,30 @@ started = cortexTraining(cortex, 'mentalCommand', 'push', 'start', 'wait', 30); if started.isSucceeded accepted = cortexTraining(cortex, 'mentalCommand', 'push', 'accept', 'wait', 15); % also saves the profile end -[labels, data, time, mcActions] = cortexGetData(cortex, 'com', 1); % mcActions{end} = action, data(end, 2) = power +[labels, data, time, bciActions] = cortexGetData(cortex, 'com', 1); % bciActions{end} = action, data(end, 2) = power [cortex, ~] = cortexProfile(cortex, 'unload'); cortex = cortexDisconnect(cortex); ``` - `[cortex, result] = cortexProfile(cortex, action, profileName)`: `action` is `'load'` (creates the profile if missing), `'save'` or `'unload'` (`profileName` is only needed for `'load'`). `result` has `name`, `uuid`, `existed`, `created` and `isLoaded`. It updates `cortex.isProfileLoaded` and `cortex.profileName`. Errors use `cortex:profileFailed`. -- `result = cortexTraining(cortex, detection, action, status, 'wait', seconds)`: `detection` is `'mentalCommand'` (`'facialExpression'` uses the same call), `action` is any action Cortex lists for the detection (for example `neutral`, `push`, `pull`, `left`, `right`), and `status` is `start`, `accept`, `reject`, `reset` or `erase`. With `'wait'` (requires the `sys` stream), `start` waits for `MC_Succeeded` or `MC_Failed` and `accept` waits for `MC_Completed`, then saves the profile. `result` has `detection`, `action`, `status`, `event`, `isSucceeded` and `profileSaved`. Errors use `cortex:trainingFailed`. -- `cortexGetData(cortex, 'com')` returns labels `{'act','pow'}`. The `act` column of `data` is `NaN`; the mental command actions are in the fourth output `mcActions` (one string per row) and `pow` (0 to 1) is in `data`. +- `result = cortexTraining(cortex, detection, action, status, 'wait', seconds)`: `detection` is `'mentalCommand'` (`'facialExpression'` uses the same call), `action` is any action Cortex lists for the detection (for example `neutral`, `push`, `pull`, `left`, `right`; for `facialExpression` only `neutral`, `surprise`, `frown`, `smile` and `clench` can be trained), and `status` is `start`, `accept`, `reject`, `reset` or `erase`. With `'wait'` (requires the `sys` stream), `start` waits for `MC_Succeeded` or `MC_Failed` and `accept` waits for `MC_Completed`, then saves the profile. `result` has `detection`, `action`, `status`, `event`, `isSucceeded` and `profileSaved`. Errors use `cortex:trainingFailed`. +- `cortexGetData(cortex, 'com')` returns labels `{'act','pow'}`. The `act` column of `data` is `NaN`; the mental command actions are in the fourth output `bciActions` (one string per row) and `pow` (0 to 1) is in `data`. + +## Facial Expression Training + +`examples/facialExpressionTraining.m` works like the mental command example, for facial expressions. + +1. Set `headsetId` and `profileName` near the top of the file, then run: + +```matlab +addpath('octave/examples'); +facialExpressionTraining(); +``` + +2. Focus the figure. `N`, `S`, `F`, `M`, `C` start training neutral, surprise, frown, smile and clench (train neutral first). Press `A` to accept a successful training (this saves the profile) or `R` to reject it. `L` subscribes to `fac` and shows the live eye, upper face and lower face actions with their powers. `U` or `Esc` unloads the profile and exits. + +- `info = cortexFacialExpressionInfo(cortex)` returns `possibleActions`, `trainedActions` (structs with `action`, `threshold` from 0 to 1000 (`[]` for neutral) and `trainingCount`) and `trainingDuration` in seconds. It requires a loaded profile. Errors use `cortex:facialExpressionFailed`. +- `cortexGetData(cortex, 'fac')` returns labels `{'eyeAct','uAct','uPow','lAct','lPow'}`. The action columns of `data` are `NaN`; each element of the fourth output is `{eyeAct, uAct, lAct}`, and `uPow` and `lPow` (0 to 1) are in `data`. ## Troubleshooting diff --git a/octave/examples/facialExpressionTraining.m b/octave/examples/facialExpressionTraining.m new file mode 100644 index 0000000..0b9a51f --- /dev/null +++ b/octave/examples/facialExpressionTraining.m @@ -0,0 +1,328 @@ +function facialExpressionTraining() +% facialExpressionTraining Train facial expression actions from the keyboard and watch live expressions. +% Set headsetId and profileName below, then call facialExpressionTraining(). +% Keys (focus the figure): N neutral, S surprise, F frown, M smile, C clench start a training; +% A accept or R reject the training result; L show live expressions; +% U (or Esc) unload the profile and exit. Train neutral first, then at least one action. +% +% The fac stream sends one sample per update with five values: +% eyeAct the eye action (for example 'neutral' or 'blink') +% uAct the upper face action, with its power uPow from 0 to 1 +% lAct the lower face action, with its power lPow from 0 to 1 +% Only neutral, surprise, frown, smile and clench can be trained. + +% Set your headset id and the name of the training profile to create or load. +headsetId = ''; +profileName = 'my-facial-expression'; + +% Allow the action duration plus time for Cortex to deliver FE_Succeeded or FE_Failed. +trainStartEventWaitLimit = 15; +% FE_Completed usually arrives immediately; keep this short timeout as a safeguard. No deadline for choosing A or R. +trainAcceptEventWaitLimit = 3; + +currentDir = fileparts(mfilename('fullpath')); +addpath(fullfile(currentDir, '../functions')); + +% Connect: authorize, connect the headset, create its session and load (or create) the profile. +cortex = cortexConnect(); +fig = []; +statusText = []; + liveText = {}; + powerAxes = {}; + powerBars = {}; + powerLabels = {}; +isBusy = false; +isExitRequested = false; +isLiveStreaming = false; +pendingAction = ''; +lastSample = ''; +connectionCleanup = onCleanup(@cleanupConnection); +try + if ~cortex.isConnected + error('facialExpressionTraining:connect', 'Cortex connection or authorization failed.'); + end + cortex = cortexSession(cortex, headsetId); + [cortex, profileResult] = cortexProfile(cortex, 'load', profileName); + if profileResult.created + fprintf('[facialExpressionTraining] Created and loaded profile %s.\n', profileName); + else + fprintf('[facialExpressionTraining] Loaded existing profile %s.\n', profileName); + end + + facialExpressionInfo = cortexFacialExpressionInfo(cortex); + trainingDuration = facialExpressionInfo.trainingDuration; + fprintf('[facialExpressionTraining] Facial expression info:\n%s\n', ... + jsonencode(facialExpressionInfo, 'PrettyPrint', true)); + + % The sys stream reports the training events (started, succeeded, completed). + cortex = cortexSubscribe(cortex, {'sys'}); + if ~cortex.isSubscribed + error('facialExpressionTraining:subscribe', 'Could not subscribe to the sys stream.'); + end + + fprintf('[facialExpressionTraining] Key help:\n'); + fprintf(' N / S / F / M / C: start training neutral / surprise / frown / smile / clench.\n'); + fprintf(' A / R: accept / reject the training result.\n'); + fprintf(' L: show live facial expressions.\n'); + fprintf(' U or Esc: unload the profile and exit.\n'); + + fig = figure('Name', 'Cortex Facial Expression Training', 'NumberTitle', 'off', ... + 'KeyPressFcn', @onKeyPress); + figurePosition = get(fig, 'Position'); + figurePosition(3) = 2 * figurePosition(3); + heightIncrease = 0.15 * figurePosition(4); + figurePosition(4) = figurePosition(4) + heightIncrease; + figurePosition(2) = figurePosition(2) - heightIncrease / 2; + set(fig, 'Position', figurePosition); + helpLines = {'Keyboard controls', '', ... + 'N: train neutral (do this first)', ... + 'S: train surprise', ... + 'F: train frown', ... + 'M: train smile', ... + 'C: train clench', ... + 'A: accept the training result (saves the profile)', ... + 'R: reject the training result', ... + 'L: show live expressions (eye, upper and lower face with power 0-1)', ... + 'U or Esc: unload the profile and exit'}; + uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.48 0.84 0.48], 'String', helpLines, ... + 'HorizontalAlignment', 'left', 'FontSize', 11, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + separatorAxes = axes('Parent', fig, 'Units', 'normalized', 'Position', [0.08 0.445 0.84 0.005], ... + 'XLim', [0 1], 'YLim', [0 1], 'Visible', 'off'); + line('Parent', separatorAxes, 'XData', [0 1], 'YData', [0.5 0.5], 'Color', [0.5 0.5 0.5], 'LineWidth', 1); + % One row per action; the upper and lower rows share their vertical center with their power bar. + rowBottoms = [0.38 0.31 0.24]; + liveText = cell(1, 3); + powerAxes = cell(1, 2); + powerBars = cell(1, 2); + powerLabels = cell(1, 2); + for row = 1:3 + liveText{row} = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 rowBottoms(row) 0.40 0.06], 'String', '', ... + 'HorizontalAlignment', 'left', 'FontSize', 14, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + end + for row = 1:2 + powerAxes{row} = axes('Parent', fig, 'Units', 'normalized', ... + 'Position', [0.52 rowBottoms(row + 1) + 0.01 0.40 0.04], ... + 'XLim', [0 1], 'YLim', [0 1], 'XTick', [], 'YTick', [], 'Box', 'on', 'Visible', 'off'); + powerBars{row} = patch('Parent', powerAxes{row}, 'Faces', [1 2 3 4], ... + 'Vertices', [0 0; 0 0; 0 1; 0 1], 'FaceColor', [0.8 0.2 0.1], ... + 'EdgeColor', 'none', 'Visible', 'off'); + powerLabels{row} = text('Parent', powerAxes{row}, 'Position', [0.5 0.5], 'String', '', ... + 'HorizontalAlignment', 'center', 'Visible', 'off'); + end + statusText = uicontrol(fig, 'Style', 'text', 'Units', 'normalized', ... + 'Position', [0.08 0.02 0.84 0.20], ... + 'String', ['Profile ' profileName ' ready. Press N to train neutral.'], ... + 'HorizontalAlignment', 'left', 'FontSize', 10, ... + 'BackgroundColor', get(fig, 'Color'), 'Enable', 'on', 'KeyPressFcn', @onKeyPress); + + % Acquire: poll keyboard events and, once subscribed, the live facial expression stream. + while ~isExitRequested && ishandle(fig) + if isLiveStreaming && ~isBusy + updateLiveDisplay(); + else + pause(0.05); + end + drawnow(); + end +catch failure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', failure.identifier, failure.message); +end + +% Disconnect: unload the profile and close the Cortex connection on every exit path. +clear connectionCleanup; +fprintf('[facialExpressionTraining] Finished.\n'); + + function onKeyPress(~, event) + if isBusy, return; end + keyName = event.Key; + if strcmpi(keyName, 'escape') || strcmpi(keyName, 'esc') + unloadAndExit(); + return; + end + + keyCharacter = event.Character; + if isempty(keyCharacter) && numel(keyName) == 1 + keyCharacter = keyName; + end + if ~ischar(keyCharacter) || numel(keyCharacter) ~= 1 + showStatus(sprintf('Ignored key: %s.', keyName)); + return; + end + + % Process: map each key to a training action, live display or exit. + switch lower(keyCharacter) + case 'n' + trainAction('neutral'); + case 's' + trainAction('surprise'); + case 'f' + trainAction('frown'); + case 'm' + trainAction('smile'); + case 'c' + trainAction('clench'); + case 'a' + finishTraining('accept'); + case 'r' + finishTraining('reject'); + case 'l' + startLiveStream(); + case 'u' + unloadAndExit(); + otherwise + showStatus(sprintf('Ignored key: %s. Use N, S, F, M, C, A, R, L, U or Esc.', keyName)); + end + end + + function trainAction(actionName) + if ~isempty(pendingAction) + showStatus(sprintf('Press A to accept or R to reject the %s training first.', pendingAction)); + return; + end + isBusy = true; + try + showStatus(sprintf(['Training %s: hold for about %g seconds. Waiting up to %g seconds total for ' ... + 'FE_Succeeded/FE_Failed (training plus event margin).'], ... + actionName, trainingDuration, trainStartEventWaitLimit)); + started = cortexTraining(cortex, 'facialExpression', actionName, 'start', ... + 'wait', trainStartEventWaitLimit); + if ~started.isSucceeded + fprintf('[facialExpressionTraining] Training %s failed (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s failed (%s). Press the key to try again.', ... + actionName, started.event)); + else + pendingAction = actionName; + fprintf('[facialExpressionTraining] Training %s succeeded (%s).\n', actionName, started.event); + showStatus(sprintf('Training %s succeeded. Press A to accept or R to reject.', actionName)); + end + catch trainFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', trainFailure.identifier, trainFailure.message); + showStatus(['Training failed: ' trainFailure.message]); + end + isBusy = false; + end + + function finishTraining(status) + if isempty(pendingAction) + showStatus('No training result to accept or reject. Start a training first.'); + return; + end + isBusy = true; + try + if strcmp(status, 'accept') + showStatus(sprintf(['Accepting %s. Waiting up to %g seconds for FE_Completed ' ... + '(example limit; configurable).'], pendingAction, trainAcceptEventWaitLimit)); + accepted = cortexTraining(cortex, 'facialExpression', pendingAction, 'accept', ... + 'wait', trainAcceptEventWaitLimit); + fprintf('[facialExpressionTraining] Training %s completed (%s); profile saved: %d.\n', ... + pendingAction, accepted.event, accepted.profileSaved); + if accepted.profileSaved + showStatus(sprintf('Training %s accepted and profile saved.', pendingAction)); + else + showStatus(sprintf('Training %s accepted, but saving the profile failed (see console).', pendingAction)); + end + else + cortexTraining(cortex, 'facialExpression', pendingAction, 'reject'); + fprintf('[facialExpressionTraining] Training %s rejected.\n', pendingAction); + showStatus(sprintf('Training %s rejected. Press its key to train again.', pendingAction)); + end + pendingAction = ''; + catch finishFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', finishFailure.identifier, finishFailure.message); + showStatus(['Could not ' status ' the training: ' finishFailure.message]); + end + isBusy = false; + end + + function startLiveStream() + if isLiveStreaming + showStatus('Live expressions are already shown.'); + return; + end + isBusy = true; + try + cortex = cortexSubscribe(cortex, {'fac'}); + if ~any(strcmp(cortex.streams, 'fac')) + error('facialExpressionTraining:subscribe', 'Could not subscribe to the fac stream.'); + end + isLiveStreaming = true; + for row = 1:2 + set(powerAxes{row}, 'Visible', 'on'); + set(powerBars{row}, 'Visible', 'on'); + set(powerLabels{row}, 'Visible', 'on'); + end + showStatus('Showing live facial expressions. Train more actions with N, S, F, M or C.'); + catch subscribeFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', subscribeFailure.identifier, subscribeFailure.message); + showStatus(['Subscribe failed: ' subscribeFailure.message]); + end + isBusy = false; + end + + function updateLiveDisplay() + [labels, data, ~, actions] = cortexGetData(cortex, 'fac', 1); + if isempty(data) || isempty(actions) || ~iscell(actions{end}), return; end + upperColumn = find(strcmp(labels, 'uPow'), 1); + lowerColumn = find(strcmp(labels, 'lPow'), 1); + if isempty(upperColumn) || isempty(lowerColumn), return; end + + % actions{end} is {eyeAct, uAct, lAct}. + names = actions{end}; + if numel(names) < 3, return; end + powers = [data(end, upperColumn), data(end, lowerColumn)]; + sample = sprintf('%s|%s|%s|%.2f|%.2f', names{1}, names{2}, names{3}, powers(1), powers(2)); + if strcmp(sample, lastSample), return; end + lastSample = sample; + + powers(isnan(powers)) = 0; + levels = max(0, min(1, powers)); + if all(cellfun(@ishandle, liveText)) + set(liveText{1}, 'String', ['Eye: ' names{1}]); + set(liveText{2}, 'String', ['Upper: ' names{2}]); + set(liveText{3}, 'String', ['Lower: ' names{3}]); + end + for row = 1:2 + % Red (weak) through yellow to green (strong). + barColor = [min(1, 2 * (1 - levels(row))), min(1, 2 * levels(row)), 0.1]; + if ishandle(powerBars{row}) + set(powerBars{row}, 'Vertices', [0 0; levels(row) 0; levels(row) 1; 0 1], ... + 'FaceColor', barColor); + end + if ishandle(powerLabels{row}) + set(powerLabels{row}, 'String', sprintf('%.2f', powers(row))); + end + end + end + + function unloadAndExit() + isBusy = true; + showStatus('Unloading the profile, please wait...'); + try + [cortex, unloadResult] = cortexProfile(cortex, 'unload'); + fprintf('[facialExpressionTraining] Profile %s unloaded.\n', unloadResult.name); + isExitRequested = true; + catch unloadFailure + fprintf('[facialExpressionTraining] ERROR %s: %s\n', unloadFailure.identifier, unloadFailure.message); + showStatus(['Could not unload the profile: ' unloadFailure.message ' Press U to try again.']); + isBusy = false; + end + end + + function showStatus(message) + if ~isempty(statusText) && ishandle(statusText) + set(statusText, 'String', message); + drawnow(); + end + end + + function cleanupConnection() + if ~isempty(fig) && ishandle(fig) + delete(fig); + end + cortex = cortexDisconnect(cortex); + end +end diff --git a/octave/functions/cortexFacialExpressionInfo.m b/octave/functions/cortexFacialExpressionInfo.m new file mode 100644 index 0000000..ff20379 --- /dev/null +++ b/octave/functions/cortexFacialExpressionInfo.m @@ -0,0 +1,21 @@ +function config = cortexFacialExpressionInfo(cortex) +% cortexFacialExpressionInfo Get the facial expression settings of the loaded profile. +% config = cortexFacialExpressionInfo(cortex) +% config fields: +% possibleActions cell array of every action Cortex supports for facial expression +% trainedActions cell array of structs with action, threshold (0 to 1000, [] for neutral) +% and trainingCount +% trainingDuration seconds a training lasts +% Requires cortexSession and cortexProfile(cortex, 'load', ...). + +try + if ~isstruct(cortex) || ~isfield(cortex, 'isConnected') || ~cortex.isConnected || ... + ~isfield(cortex, 'manager') || isempty(cortex.manager) + error('cortex:facialExpressionFailed', 'Connect to Cortex before using facial expression operations.'); + end + config = cortex.manager.getFacialExpressionConfiguration().get(); +catch failure + if strcmp(failure.identifier, 'cortex:facialExpressionFailed'), rethrow(failure); end + error('cortex:facialExpressionFailed', 'Facial expression operation failed: %s', failure.message); +end +end diff --git a/octave/functions/cortexGetData.m b/octave/functions/cortexGetData.m index d456841..f12f88b 100644 --- a/octave/functions/cortexGetData.m +++ b/octave/functions/cortexGetData.m @@ -1,20 +1,22 @@ -function [labels, data, time, mcActions] = cortexGetData(cortex, stream, lastN) -% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow, met or com). -% [labels, data, time, mcActions] = cortexGetData(cortex, 'eeg', 256) first collects the data that has +function [labels, data, time, bciActions] = cortexGetData(cortex, stream, lastN) +% cortexGetData Read buffered samples of one subscribed stream (eeg, mot, dev, eq, pow, met, com or fac). +% [labels, data, time, bciActions] = cortexGetData(cortex, 'eeg', 256) first collects the data that has % arrived (this can take up to about 1 second), then returns the newest 256 samples: % labels cell array with one name per column of data % data samples-by-columns matrix, oldest sample first (NaN where a value is empty) % time sample times in seconds -% mcActions cell array with one mental command action per sample for com, '' for other streams -% For com, labels are {'act','pow'}: the act column of data is NaN and mcActions holds the action, +% bciActions cell array with one action per sample for com and fac, '' for other streams +% For com, labels are {'act','pow'}: the act column of data is NaN and bciActions holds the action, % while pow (0 to 1) is the action power. +% For fac, labels are {'eyeAct','uAct','uPow','lAct','lPow'}: the act columns of data are NaN and +% each element of bciActions is {eyeAct, uAct, lAct}; uPow and lPow (0 to 1) are the powers. % Omit lastN to get everything in the buffer (the last 10000 samples per stream). if nargin < 3, lastN = []; end labels = {}; data = []; time = []; -mcActions = {}; +bciActions = {}; if ~isstruct(cortex) || ~isfield(cortex, 'isSubscribed') || ~cortex.isSubscribed fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); @@ -27,5 +29,5 @@ fprintf('[cortexGetData] No active subscription. Call cortexSubscribe first.\n'); return; end -[labels, data, time, mcActions] = cortex.manager.getContext().buffer.read(stream, lastN); +[labels, data, time, bciActions] = cortex.manager.getContext().buffer.read(stream, lastN); end diff --git a/octave/functions/cortexSubscribe.m b/octave/functions/cortexSubscribe.m index 9ae4435..fc6de71 100644 --- a/octave/functions/cortexSubscribe.m +++ b/octave/functions/cortexSubscribe.m @@ -1,7 +1,7 @@ function cortex = cortexSubscribe(cortex, streams) % cortexSubscribe Subscribe to streams on an active headset session. -% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met','com','sys'}) -% com (mental command) needs a loaded profile; sys carries training events. +% cortex = cortexSubscribe(cortex, {'eeg','mot','dev','eq','pow','met','com','fac','sys'}) +% com (mental command) and fac (facial expression) need a loaded profile; sys carries training events. % Update the fields: % isSubscribed true when the streams are being received % streams the subscribed stream names @@ -14,7 +14,7 @@ end if ischar(streams), streams = {streams}; end -validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met', 'com', 'sys'}; +validStreams = {'eeg', 'mot', 'dev', 'eq', 'pow', 'met', 'com', 'fac', 'sys'}; if ~iscellstr(streams) || isempty(streams) || ~all(ismember(streams, validStreams)) fprintf('[cortexSubscribe] ERROR streams must be a non-empty list of: %s.\n', strjoin(validStreams, ', ')); return; diff --git a/octave/internal/CortexDataBuffer.m b/octave/internal/CortexDataBuffer.m index 7c96cc3..9ca64c5 100644 --- a/octave/internal/CortexDataBuffer.m +++ b/octave/internal/CortexDataBuffer.m @@ -11,7 +11,7 @@ labels = {} samples = {} times = {} - mcActions = {} + bciActions = {} nextRow = [] count = [] end @@ -31,20 +31,20 @@ function configure(obj, stream, labels) obj.labels{idx} = labels; obj.samples{idx} = []; obj.times{idx} = []; - obj.mcActions{idx} = {}; + obj.bciActions{idx} = {}; obj.nextRow(idx) = 1; obj.count(idx) = 0; end - function append(obj, stream, row, time, mcAction) - % mcAction is optional: the mental command action of a com sample. - if nargin < 5, mcAction = ''; end + function append(obj, stream, row, time, bciAction) + % bciAction is optional: the mental command or facial expression action of a com or fac sample. + if nargin < 5, bciAction = ''; end idx = obj.indexOf(stream); width = numel(row); if isempty(obj.samples{idx}) obj.samples{idx} = NaN(obj.capacity, width); obj.times{idx} = NaN(obj.capacity, 1); - obj.mcActions{idx} = cell(obj.capacity, 1); + obj.bciActions{idx} = cell(obj.capacity, 1); end columns = size(obj.samples{idx}, 2); @@ -57,17 +57,17 @@ function append(obj, stream, row, time, mcAction) r = obj.nextRow(idx); obj.samples{idx}(r, :) = row; obj.times{idx}(r) = time; - obj.mcActions{idx}{r} = mcAction; + obj.bciActions{idx}{r} = bciAction; obj.nextRow(idx) = mod(r, obj.capacity) + 1; obj.count(idx) = min(obj.count(idx) + 1, obj.capacity); end - function [labels, data, time, mcActions] = read(obj, stream, lastN) + function [labels, data, time, bciActions] = read(obj, stream, lastN) % Returns the newest lastN samples (all buffered samples when lastN is omitted). labels = {}; data = []; time = []; - mcActions = {}; + bciActions = {}; idx = find(strcmp(obj.names, stream), 1); if isempty(idx), return; end @@ -82,7 +82,7 @@ function append(obj, stream, row, time, mcAction) rows = mod((newest - n + 1:newest) - 1, obj.capacity) + 1; data = obj.samples{idx}(rows, :); time = obj.times{idx}(rows); - mcActions = obj.mcActions{idx}(rows); + bciActions = obj.bciActions{idx}(rows); end function n = numSamples(obj, stream) @@ -104,7 +104,7 @@ function append(obj, stream, row, time, mcAction) obj.labels{idx} = {}; obj.samples{idx} = []; obj.times{idx} = []; - obj.mcActions{idx} = {}; + obj.bciActions{idx} = {}; obj.nextRow(idx) = 1; obj.count(idx) = 0; end diff --git a/octave/internal/CortexFacialExpressionConfiguration.m b/octave/internal/CortexFacialExpressionConfiguration.m new file mode 100644 index 0000000..dadcc76 --- /dev/null +++ b/octave/internal/CortexFacialExpressionConfiguration.m @@ -0,0 +1,77 @@ +classdef CortexFacialExpressionConfiguration < handle + % CortexFacialExpressionConfiguration Reads the facial expression configuration of the loaded profile. + + properties (Access = private) + client + context + end + + methods + function obj = CortexFacialExpressionConfiguration(client, context) + obj.client = client; + obj.context = context; + end + + function config = get(obj) + if isempty(obj.context.sessionId) + error('CortexFacialExpressionConfiguration:noSession', 'Create a headset session first.'); + end + if ~obj.context.isProfileLoaded + error('CortexFacialExpressionConfiguration:noProfile', 'Load a profile first.'); + end + token = obj.context.token; + session = obj.context.sessionId; + detection = 'facialExpression'; + + info = obj.context.detectionInfo.(detection); + signature = obj.client.sendRequest('getTrainedSignatureActions', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + duration = obj.client.sendRequest('getTrainingTime', ... + struct('cortexToken', token, 'detection', detection, 'session', session)).result; + + trained = CortexFacialExpressionConfiguration.toCell( ... + CortexFacialExpressionConfiguration.field(signature, 'trainedActions', {})); + trainedActions = cell(1, numel(trained)); + for index = 1:numel(trained) + name = trained{index}.action; + % Neutral has no threshold. + value = []; + if ~strcmp(name, 'neutral') + thresholdResult = obj.client.sendRequest('facialExpressionThreshold', struct( ... + 'cortexToken', token, 'session', session, 'action', name, 'status', 'get')).result; + value = CortexFacialExpressionConfiguration.field(thresholdResult, 'value', thresholdResult); + if ~isnumeric(value) || isempty(value), value = []; end + end + trainedActions{index} = struct('action', name, 'threshold', value, ... + 'trainingCount', CortexFacialExpressionConfiguration.field(trained{index}, 'times', 0)); + end + + config = struct( ... + 'possibleActions', {info.actions}, ... + 'trainedActions', {trainedActions}, ... + 'trainingDuration', CortexFacialExpressionConfiguration.field(duration, 'time', [])); + end + end + + methods (Static, Access = private) + function items = toCell(value) + if iscell(value) + items = value(:)'; + elseif isstruct(value) + items = num2cell(value(:))'; + elseif ischar(value) + items = {value}; + else + items = {}; + end + end + + function value = field(source, name, default) + if isstruct(source) && isfield(source, name) + value = source.(name); + else + value = default; + end + end + end +end diff --git a/octave/internal/CortexHeadset.m b/octave/internal/CortexHeadset.m index 5a0fe45..5bf39f4 100644 --- a/octave/internal/CortexHeadset.m +++ b/octave/internal/CortexHeadset.m @@ -250,13 +250,13 @@ function runScanTimer(obj) end function storeSample(obj, msg) - [stream, row, time, mcAction] = obj.parser.parse(msg); + [stream, row, time, bciAction] = obj.parser.parse(msg); if isempty(stream), return; end if strcmp(stream, 'sys') obj.storeSystemEvent(msg.sys, time); return; end - obj.context.buffer.append(stream, row, time, mcAction); + obj.context.buffer.append(stream, row, time, bciAction); end function storeSystemEvent(obj, values, time) diff --git a/octave/internal/CortexManager.m b/octave/internal/CortexManager.m index 1354ee4..d03d3cf 100644 --- a/octave/internal/CortexManager.m +++ b/octave/internal/CortexManager.m @@ -18,6 +18,7 @@ profile = [] training = [] mentalCommand = [] + facialExpression = [] end methods @@ -93,6 +94,13 @@ mentalCommand = obj.mentalCommand; end + function facialExpression = getFacialExpressionConfiguration(obj) + if isempty(obj.facialExpression) + obj.facialExpression = CortexFacialExpressionConfiguration(obj.getClient(), obj.context); + end + facialExpression = obj.facialExpression; + end + function close(obj) % Only closes what was actually created. if ~isempty(obj.headset) @@ -110,6 +118,7 @@ function close(obj) obj.profile = []; obj.training = []; obj.mentalCommand = []; + obj.facialExpression = []; end end end diff --git a/octave/internal/CortexStreamParser.m b/octave/internal/CortexStreamParser.m index 7b16ed5..74d33fd 100644 --- a/octave/internal/CortexStreamParser.m +++ b/octave/internal/CortexStreamParser.m @@ -18,13 +18,13 @@ function reset(obj) obj.streams = {}; end - function [stream, row, time, mcAction] = parse(obj, msg) + function [stream, row, time, bciAction] = parse(obj, msg) % stream is '' when the message does not belong to a registered stream. - % mcAction is the mental command action of a com sample ('' for other streams). + % bciAction is the action of a com sample, or {eyeAct, uAct, lAct} for fac ('' for other streams). stream = ''; row = []; time = NaN; - mcAction = ''; + bciAction = ''; if isfield(msg, 'sid') && ischar(msg.sid) % Streams of one session can share the same sid, so match the stream by its field name too. candidates = find(strcmp(obj.sids, msg.sid)); @@ -45,7 +45,12 @@ function reset(obj) end row = CortexStreamParser.flattenSample(msg.(stream)); names = CortexStreamParser.stringsOf(msg.(stream)); - if ~isempty(names), mcAction = names{1}; end + if strcmp(stream, 'fac') + % fac carries three actions per sample: {eyeAct, uAct, lAct}. + bciAction = names; + elseif ~isempty(names) + bciAction = names{1}; + end end end From 2dd2a422ae18430a38190109e6f459c0a9220fa7 Mon Sep 17 00:00:00 2001 From: tung_tung Date: Mon, 16 Nov 2026 10:25:42 +0700 Subject: [PATCH 5/5] COR-1866: update README to mention about octave example and clear somepoint --- README.md | 1 + octave/README.md | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0b04905..3db60eb 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Example code for Cortex V2 & V3 & V4. So far we have the following languages: * NodeJS * Python * Unity +* Octave # API Documentation For Cortex V2 / V3 / V4 API documentations please check out: https://emotiv.gitbook.io/cortex-api/ diff --git a/octave/README.md b/octave/README.md index a766650..86fc437 100644 --- a/octave/README.md +++ b/octave/README.md @@ -1,8 +1,8 @@ # Emotiv Cortex Octave/MATLAB Examples -This folder contains a small MATLAB/GNU Octave client for the Emotiv Cortex API. The first example checks the connection, verifies that an Emotiv user is logged in, requests application access when needed, authorizes the application, and prints basic account and license information. +This folder contains a MATLAB/GNU Octave client for the Emotiv Cortex API, with reusable functions and example scripts that demonstrate the Cortex API and its major Cortex workflows. -The examples are written for researchers and engineers who use MATLAB or GNU Octave for analysis. You do not need to understand the internal classes to run the example. +The examples demonstrate the main Cortex API workflows: authorization, connecting to a headset, subscribing to data, creating a record and injecting markers, and BCI training. ## What You Will Run @@ -20,7 +20,7 @@ The local connection has two parts: - `config/`: Local configuration. Copy `config/config.example.json` to `config/config.json` to store your Cortex application credentials. `config/config.json` is ignored by Git and must not be committed or shared. - `examples/`: Beginner-friendly scripts that show complete workflows. -The public workflow uses procedural functions such as `cortexConnect`, `cortexSession`, `cortexSubscribe`, `cortexRecord`, `cortexMarker`, and `cortexDisconnect`. The underlying Cortex classes are kept inside `internal/` so examples can extend the SDK without making researchers manage the WebSocket or internal class instances. +The `functions/` folder provides a task-oriented, procedural interface to the Cortex API. Its helpers group related API calls where useful—for example, `cortexConnect` connects and authorizes the app, while `cortexSession` scans for and connects a headset, then creates or reuses its session. Use these functions with the shared `cortex` state to build clear, sequential workflows without instantiating or coordinating Cortex classes directly. The underlying classes and WebSocket handling are kept in `internal/`. ## Requirements @@ -150,6 +150,8 @@ cortex = cortexDisconnect(cortex); % unsubscribes and cl - `cortexGetData` collects the samples that have arrived and returns them from a buffer that keeps the latest 10000 samples per stream. `data` has one row per sample and one column per entry in `labels`; empty values are `NaN`. - Call `cortexGetData` regularly. Samples are only read from the connection when it runs, and it can take up to about 1 second when no data is arriving. +**Known limitations:** EPOC Flex headsets are not currently supported by the Octave examples, including configurations that use channel mappings. The examples also do not automatically recover if a headset disconnects; reconnect the headset and run the example again. These limitations may be addressed in a future update. + ## Record and Markers `examples/recordAndMarker.m` demonstrates creating and stopping a record without subscribing to any data stream, and adding keyboard-controlled markers.