1#![forbid(unsafe_code)]
55#![warn(missing_docs)]
56
57mod assurance;
58#[doc(hidden)]
59pub mod dataset;
60#[doc(hidden)]
61pub mod nev;
62#[doc(hidden)]
63pub mod nsx;
64
65use std::path::Path;
66
67use openreadout_core::Result;
68use openreadout_core::model::{DetectConfidence, FormatDescriptor};
69use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
70use openreadout_core::source::Input;
71
72#[doc(hidden)]
73pub use dataset::{
74 KIND_COMMENT, KIND_DIGITAL, KIND_OTHER, KIND_SPIKE, MAX_COMMENTS, MAX_TABLE_READ, NevDataset,
75 NsxDataset,
76};
77#[doc(hidden)]
78pub use nev::{
79 COMMENT_PACKET, ExtHeader, MAX_ELECTRODE_ID, NEV_BASIC_LEN, NEV_EXT_LEN, NevFile, NevPacket,
80 WaveformHeader, nev_packet, parse_nev,
81};
82#[doc(hidden)]
83pub use nsx::{
84 BASIC_HEADER_LEN, CC_LEN, MAX_CHANNELS, NsxChannel, NsxFile, NsxPacket, NsxSpec, NsxSweep,
85 PERIOD_CLOCK_HZ, PTP_RESOLUTION, SPEC21_HEADER_LEN, cc_scaling, parse_nsx, spec21_factor,
86 spec21_label, systemtime,
87};
88
89pub const FORMAT_ID: &str = "blackrock";
91
92pub const EXTENSIONS: [&str; 7] = ["ns1", "ns2", "ns3", "ns4", "ns5", "ns6", "nev"];
94
95pub const SIGNATURES: [&[u8; 8]; 5] = [
97 b"NEURALSG",
98 b"NEURALCD",
99 b"BRSMPGRP",
100 b"NEURALEV",
101 b"BREVENTS",
102];
103
104pub const SESSION_COMPANIONS: [&str; 6] = ["ccf", "txt", "log", "xml", "json", "md"];
107
108pub fn session_files(dir: &Path) -> Option<Vec<std::path::PathBuf>> {
111 session_files_in(&Input::local(dir))
112}
113
114fn session_files_in(input: &Input) -> Option<Vec<std::path::PathBuf>> {
115 let dir = input.path();
116 let fs = input.fs();
117 openreadout_core::session::session_files_in(
118 fs,
119 dir,
120 &|p| has_extension(p, &EXTENSIONS),
121 &SESSION_COMPANIONS,
122 0,
123 )
124}
125
126pub fn open_session(dir: &Path) -> Result<openreadout_core::session::SessionDataset> {
130 open_session_input(&Input::local(dir))
131}
132
133fn open_session_input(input: &Input) -> Result<openreadout_core::session::SessionDataset> {
134 let dir = input.path();
135 let files = session_files_in(input).ok_or_else(|| {
136 openreadout_core::Error::unsupported(
137 FORMAT_ID,
138 "a directory that is not a Blackrock recording",
139 "A Blackrock session directory holds .ns1-.ns6 and .nev files (plus .ccf/logs); open a single file otherwise.",
140 )
141 })?;
142 let mut members = Vec::new();
143 for f in &files {
144 members.push(BlackrockReader.open_input(&input.with_path(f))?);
145 }
146 openreadout_core::session::SessionDataset::new(
147 FORMAT_ID,
148 dir,
149 members,
150 openreadout_core::session::Combine::Separate,
151 )
152}
153
154#[derive(Debug, Default, Clone, Copy)]
156pub struct BlackrockReader;
157
158impl FormatReader for BlackrockReader {
159 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
160 Some(&assurance::BLACKROCK)
161 }
162
163 fn descriptor(&self) -> FormatDescriptor {
164 FormatDescriptor {
165 id: FORMAT_ID.into(),
166 name: "Blackrock NSx/NEV".into(),
167 vendor: "Blackrock Neurotech (Cerebus, NeuroPort)".into(),
168 extensions: EXTENSIONS.iter().map(|e| (*e).to_string()).collect(),
169 family: "electrophysiology".into(),
170 can_read: true,
171 can_write: false,
172 confidence: assurance::BLACKROCK.confidence,
173 known_gaps: vec![
174 "A recording directory is one session (each NSx file a trace, each NEV a table, clocks kept); NEV rows are not assigned to NSx sweeps".into(),
175 "NEV video-sync, tracking, button, configuration and log packets are counted (kind 3), not decoded; comment text is in `info --view full`".into(),
176 "Spec 2.1 NSx scaling needs the .nev with the same name next to it".into(),
177 ],
178 }
179 }
180
181 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
182 self.sniff_input(head, &Input::local(path))
183 }
184
185 fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
186 let path = input.path();
187 if input.is_dir() {
188 let files = session_files_in(input)?;
189 let signed = files.iter().take(8).any(|f| {
190 let mut head = [0u8; 8];
191 input
192 .fs()
193 .open(f)
194 .and_then(|mut h| std::io::Read::read(&mut h, &mut head))
195 .is_ok_and(|n| n == 8 && SIGNATURES.iter().any(|s| head == **s))
196 });
197 return Some(Detection {
198 format_id: FORMAT_ID,
199 confidence: if signed {
200 DetectConfidence::Definite
201 } else {
202 DetectConfidence::Likely
203 },
204 note: Some("Blackrock recording directory (NSx + NEV, read as one session)".into()),
205 });
206 }
207 if head.len() >= 8 && SIGNATURES.iter().any(|s| &head[..8] == *s) {
208 return Some(Detection {
209 format_id: FORMAT_ID,
210 confidence: DetectConfidence::Definite,
211 note: None,
212 });
213 }
214 (has_extension(path, &EXTENSIONS) && head.len() < 8).then(|| Detection {
216 format_id: FORMAT_ID,
217 confidence: DetectConfidence::ExtensionOnly,
218 note: Some("Blackrock extension but no NSx/NEV signature at byte 0".into()),
219 })
220 }
221
222 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
223 self.open_input(&Input::local(path))
224 }
225
226 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
227 let path = input.path();
228 if input.is_dir() {
229 return Ok(Box::new(open_session_input(input)?));
230 }
231 let mut head = [0u8; 8];
232 let mut f = input.open()?;
233 let n = std::io::Read::read(&mut f, &mut head)
234 .map_err(|e| openreadout_core::Error::io(path, e))?;
235 if n == 8 && (&head == b"NEURALEV" || &head == b"BREVENTS") {
236 Ok(Box::new(NevDataset::open_input(input)?))
237 } else {
238 Ok(Box::new(NsxDataset::open_input(input)?))
239 }
240 }
241
242 fn reads_any_source(&self) -> bool {
243 true
244 }
245}