You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/guano_specification.md
+48-28Lines changed: 48 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -73,7 +73,7 @@ string "\n" as a newline. At this time, this specification makes no attempt
73
73
to define an escape for encoding the literal string "\n" with a meaning apart
74
74
from "newline".
75
75
76
-
**TODO:**Binary field values should be encoded as Base64. However, Base64 enforces
76
+
Binary field values should be encoded as Base64. However, Base64 enforces
77
77
a maximum line length, and the GUANO metadata format thus far delimits fields
78
78
by newline. Enforcing a short line length for potentially-large binary values
79
79
would ease the development of reading implementations which must allocate
@@ -192,26 +192,26 @@ The following namespaces have been reserved or registered. Any manufacturer who
192
192
utilizes their own custom GUANO fields is encouraged to add their namespace to
193
193
this list so that it isn't accidentally used by another manufacturer.
194
194
195
-
**GUANO**
195
+
**GUANO**
196
196
This reserved namespace is for meta-metadata pertaining specifically to the
197
197
GUANO metadata in use.
198
198
199
-
**BAT**
199
+
**BAT**
200
200
Binary Acoustic Technologies
201
201
202
-
**MSFT**
202
+
**MSFT**
203
203
Myotisoft
204
204
205
-
**PET**
205
+
**PET**
206
206
Pettersson
207
207
208
-
**SB**
208
+
**SB**
209
209
SonoBat
210
210
211
-
**Anabat**
211
+
**Anabat**
212
212
Titley Scientific
213
213
214
-
**WAC**
214
+
**WAC**
215
215
Wildlife Acoustics
216
216
217
217
@@ -258,60 +258,80 @@ fields from the following defined or "well-known" list.
258
258
Reading implementations should expect to encounter any of the following
259
259
fields in a compliant GUANO file.
260
260
261
-
**GUANO|Version**
261
+
**GUANO|Version**
262
262
required, float. GUANO metadata version in use. This specification defines version `1.0`.
263
263
264
-
**GUANO|Size**
264
+
**GUANO|Size**
265
265
optional, integer. Total size, in bytes, of pre-allocated GUANO metadata space. Pre-allocating whitespace within the `guan` subchunk allows for writing/editing metadata without re-writing the entirety of the file back to disk. This field should only be used if pre-allocating space, so that writing (editing) implementations may check to see if their changes overflow the bounds of pre-allocated metadata space.
266
266
267
-
**Filter HP**
267
+
**Filter HP**
268
268
optional, float. High-pass filter frequency, in kHz.
269
269
270
-
**Filter LP**
270
+
**Filter LP**
271
271
optional, float. Low-pass filter frequency, in kHz.
272
272
273
-
**Length**
273
+
**Firmware Version**
274
+
optional, string. Device's firmware version, in manufacturer's own descriptive format.
275
+
276
+
**Hardware Version**
277
+
optional, string. Device's hardware revision or hardware options, in manufacturer's own descriptive format.
278
+
279
+
**Humidity**
280
+
optional, float. Relative humidity as a percentage in the range 0.0 - 100.0.
281
+
282
+
**Length**
274
283
optional, float. Recording length, in seconds. This should be the "actual length", which will be identical to the .WAV length for direct-recorded files, but will be calculated for time-expanded recordings (.WAV length divided by TE factor).
275
284
276
-
**Loc Accuracy**
277
-
optional, float. Location accuracy, in meters.
285
+
**Loc Accuracy**
286
+
optional, float. Location accuracy, in meters. This should be the Estimated Position Error (EPE); this statistical range states that 68% of measurements will fall within this radius, 95% of measurements will fall within twice this radius. EPE is calculated differently by different GPS receiver manufacturers, therefore it should be stressed that this value is merely an *estimate* of accuracy. Detector manufacturers may opt to estimate accuracy more coarsely if EPE is not available directly from their GPS receiver, but should express the value in the same one-sigma fashion.
278
287
279
-
**Loc Elevation**
288
+
**Loc Elevation**
280
289
optional, float. Elevation / altitude above mean sea level, in meters.
281
290
282
-
**Loc Position**
291
+
**Loc Position**
283
292
optional, (float float). Location that the recording was made, as a WGS84 latitude longitude tuple.
284
293
285
-
**Make**
294
+
**Make**
286
295
optional, string. Manufacturer of the recording hardware.
287
296
288
-
**Model**
297
+
**Model**
289
298
optional, string. Model name or number of the recording hardware.
290
299
291
-
**Note**
300
+
**Note**
292
301
optional, multiline string. Freeform textual note associated with the recording.
293
302
294
-
**Samplerate**
303
+
**Samplerate**
295
304
optional, integer. Recording samplerate, in Hz. This should be equal to the .WAV samplerate for direct-recording detectors, but should be a product of ``TE`` and the .WAV samplerate for time-expansion detectors.
296
305
297
-
**Species Auto ID**
306
+
**Species Auto ID**
298
307
optional, string. Species or guild classification, as determined by automated classification.
299
308
300
-
**Species Manual ID**
309
+
**Species Manual ID**
301
310
optional, string. Species or guild classification, as determined by a human.
302
311
303
-
**Tags**
312
+
**Tags**
304
313
optional, list of strings. A comma-separated list of arbitrary strings so that end users may easily apply any tags / labels that they see appropriate.
305
314
306
-
**TE**
315
+
**TE**
307
316
optional, integer. Time-expansion factor. If not specified, then 1 (*no* time-expansion, aka direct-recording) is assumed.
308
317
309
-
**Timestamp**
318
+
**Temperature**
319
+
optional, float. Temperature in degrees Celsius. This is assumed to be the "outside temperature"; if a device records temperature inside its housing and that temperature is not an accurate proxy for outside temperature, a vendor-specific field should be used instead.
320
+
321
+
**Timestamp**
310
322
required, datetime. Date and time of the start of the recording, in ISO 8601 compatible format (see datetime specification above). It is very strongly recommended that, if UTC offset is known, it is explicitly specified rather than recording the timestamp only in UTC "zulu" time. This is because local time is overwhelmingly more important when it comes to bat echolocation data than is absolute UTC time; unfortunately GPS receivers provide only UTC time, and the local UTC offset for a location may vary according to political boundaries.
311
323
312
324
313
325
Specification History
314
326
---------------------
315
327
316
-
2015-10-12 0.0.1 Initial public release of draft GUANO specification with
2015-10-12 | 0.0.1 | Initial public release of draft GUANO specification with reference Python implementation
332
+
333
+
334
+
Notes
335
+
-----
336
+
337
+
* The use of manufacturer or product names in this specification does not imply endorsement, support, or any other association by those manufacturers or products; nor does it imply compliance with the GUANO specification.
0 commit comments