Skip to content

Commit ea004af

Browse files
AdamDHinesAdamDHines
committed
Update docs
1 parent c24b76c commit ea004af

17 files changed

Lines changed: 707 additions & 7 deletions

‎baselines/baseline_config_template.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
# Template baseline configuration for Event-LAB.
3+
# Copy this file to baselines/<baseline_name>.yaml and keep only the keys your
4+
# wrapper reads.
5+
name: "my_baseline"
6+
repo_path: "./baselines/my_baseline_repo"
7+
model_path: "./baselines/my_baseline_repo/model.pth"
8+
batch_size: 8

‎datasets/dataset_template.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
# Template dataset configuration for Event-LAB.
3+
# Copy this file to datasets/<dataset_name>.yaml and replace the values.
4+
dataset:
5+
name: my_dataset
6+
version: "1.0.0"
7+
description: "Short dataset description"
8+
base_url: "https://example.com/my-dataset"
9+
camera: "event_camera_name"
10+
resolution: [346, 260] # Width, Height
11+
12+
sequences:
13+
reference_sequence:
14+
data:
15+
url: "https://example.com/reference_sequence.hdf5"
16+
ground_truth:
17+
available: true
18+
url: "https://example.com/reference_sequence_ground_truth.h5"
19+
hot_pixel:
20+
available: false
21+
url: ""
22+
23+
query_sequence:
24+
data:
25+
url: "https://example.com/query_sequence.hdf5"
26+
ground_truth:
27+
available: true
28+
url: "https://example.com/query_sequence_ground_truth.h5"
29+
hot_pixel:
30+
available: false
31+
url: ""
32+
33+
format:
34+
data:
35+
format: "hdf5"
36+
timestamp_val: "ns"
37+
time_scale: 1e-9
38+
ground_truth: "hdf5"
39+
hot_pixel: ""
40+
41+
other:
42+
offset:
43+
reference_sequence: 0.0
44+
query_sequence: 0.0

‎docs/_static/copybutton.css‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.highlight {
2+
position: relative;
3+
}
4+
5+
.eventlab-copy-button {
6+
position: absolute;
7+
top: 0.45rem;
8+
right: 0.45rem;
9+
z-index: 3;
10+
padding: 0.25rem 0.55rem;
11+
border: 1px solid #d0d7de;
12+
border-radius: 4px;
13+
background: #ffffff;
14+
color: #24292f;
15+
font-size: 0.75rem;
16+
line-height: 1.2;
17+
cursor: pointer;
18+
opacity: 0;
19+
transition: opacity 120ms ease-in-out, background 120ms ease-in-out;
20+
}
21+
22+
.highlight:hover .eventlab-copy-button,
23+
.highlight:focus-within .eventlab-copy-button,
24+
.eventlab-copy-button:focus {
25+
opacity: 1;
26+
}
27+
28+
.eventlab-copy-button:hover,
29+
.eventlab-copy-button:focus {
30+
background: #f6f8fa;
31+
}
32+
33+
.eventlab-copy-button.is-copied {
34+
border-color: #2da44e;
35+
color: #1a7f37;
36+
}

‎docs/_static/copybutton.js‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
(function () {
2+
function copyText(text) {
3+
if (navigator.clipboard && window.isSecureContext) {
4+
return navigator.clipboard.writeText(text);
5+
}
6+
7+
return new Promise(function (resolve, reject) {
8+
var textArea = document.createElement("textarea");
9+
textArea.value = text;
10+
textArea.setAttribute("readonly", "");
11+
textArea.style.position = "fixed";
12+
textArea.style.top = "-9999px";
13+
document.body.appendChild(textArea);
14+
textArea.select();
15+
16+
try {
17+
document.execCommand("copy");
18+
resolve();
19+
} catch (error) {
20+
reject(error);
21+
} finally {
22+
document.body.removeChild(textArea);
23+
}
24+
});
25+
}
26+
27+
function addCopyButtons() {
28+
document.querySelectorAll("div.highlight").forEach(function (block) {
29+
if (block.querySelector(".eventlab-copy-button")) {
30+
return;
31+
}
32+
33+
var pre = block.querySelector("pre");
34+
if (!pre) {
35+
return;
36+
}
37+
38+
var button = document.createElement("button");
39+
button.type = "button";
40+
button.className = "eventlab-copy-button";
41+
button.textContent = "Copy";
42+
button.setAttribute("aria-label", "Copy code block");
43+
44+
button.addEventListener("click", function () {
45+
var text = pre.innerText.replace(/\s+$/, "");
46+
copyText(text).then(function () {
47+
button.textContent = "Copied";
48+
button.classList.add("is-copied");
49+
window.setTimeout(function () {
50+
button.textContent = "Copy";
51+
button.classList.remove("is-copied");
52+
}, 1400);
53+
}).catch(function () {
54+
button.textContent = "Failed";
55+
window.setTimeout(function () {
56+
button.textContent = "Copy";
57+
}, 1400);
58+
});
59+
});
60+
61+
block.appendChild(button);
62+
});
63+
}
64+
65+
if (document.readyState === "loading") {
66+
document.addEventListener("DOMContentLoaded", addCopyButtons);
67+
} else {
68+
addCopyButtons();
69+
}
70+
}());

‎docs/_static/logo.svg‎

Lines changed: 87 additions & 0 deletions
Loading

‎docs/baselines.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
Baselines
2+
=========
3+
4+
Baselines are selected by command name:
5+
6+
.. code-block:: bash
7+
8+
pixi run eventlab <baseline> <dataset> <reference> <query>
9+
10+
Event-LAB downloads or prepares the selected baseline, formats the reference
11+
and query data, runs the method, then evaluates the saved distance or similarity
12+
matrix against the ground truth.
13+
14+
Available baselines
15+
-------------------
16+
17+
.. list-table::
18+
:header-rows: 1
19+
20+
* - Baseline
21+
- Command name
22+
- Notes
23+
* - EventVLAD
24+
- ``eventvlad``
25+
- Uses reconstructed frames and EventVLAD weights.
26+
* - Ensemble-Event-VPR
27+
- ``ensemble``
28+
- Runs the ensemble baseline over prepared event frames.
29+
* - LENS
30+
- ``lens``
31+
- Runs the LENS baseline with its own baseline config.
32+
* - Sparse-Event-VPR
33+
- ``sparse_event``
34+
- Samples sparse event pixels from generated frames.
35+
* - VPR-Methods
36+
- ``vprmethods``
37+
- Runs image VPR methods on reconstructed frames.
38+
39+
Baseline configuration
40+
----------------------
41+
42+
Baseline-specific settings live beside each baseline wrapper, for example
43+
``baselines/sparse_event.yaml`` and ``baselines/eventvlad.yaml``. These files
44+
control method settings, while ``config.yaml`` controls shared Event-LAB
45+
settings such as time windows and frame generation.
46+
47+
Outputs
48+
-------
49+
50+
Each run writes baseline outputs under ``output/<baseline>/`` and appends the
51+
evaluation summary to:
52+
53+
.. code-block:: text
54+
55+
output/eventlab_results.xlsx
56+
57+
For each baseline run, Event-LAB expects one or more ``.npy`` matrices in the
58+
baseline output directory. Distance matrices use lower values for better
59+
matches; similarity matrices use higher values for better matches. The baseline
60+
wrapper declares which type it produces before metrics are calculated.

‎docs/batching.rst‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Batching
2+
========
3+
4+
Batching runs several Event-LAB experiments from ``batch_config.yaml``. It is
5+
useful when you want to compare several baselines, queries, and frame settings
6+
without typing each command by hand.
7+
8+
Run a batch
9+
-----------
10+
11+
.. code-block:: bash
12+
13+
pixi run batch
14+
15+
This command reads ``batch_config.yaml``, updates ``config.yaml`` for each
16+
experiment, writes ``run_batch.sh``, and runs each generated Event-LAB command
17+
in order.
18+
19+
Batch configuration
20+
-------------------
21+
22+
.. code-block:: yaml
23+
24+
batch_experiments:
25+
- dataset: brisbane_event
26+
reference: sunset2
27+
queries: [sunrise]
28+
baselines: [sparse_event, lens, eventvlad]
29+
config:
30+
frame_generator: frames
31+
frame_accumulator: polarity
32+
timewindows:
33+
list: [33, 66, 120, 250]
34+
35+
Each experiment defines one dataset, one reference sequence, one or more query
36+
sequences, and one or more baselines. The ``config`` block contains the
37+
Event-LAB settings that should be applied before those runs.
38+
39+
Baseline overrides
40+
------------------
41+
42+
Use ``baseline_config`` when a batch needs to change a baseline YAML setting for
43+
one experiment.
44+
45+
.. code-block:: yaml
46+
47+
baseline_config:
48+
vprmethods:
49+
method: ["cosplace", "eigenplaces", "mixvpr"]
50+
51+
When ``method`` is a list, Event-LAB expands it into separate runs and writes
52+
each method into the baseline config before running that command.
53+
54+
Generated commands
55+
------------------
56+
57+
For each baseline and query pair, batching generates commands in this form:
58+
59+
.. code-block:: bash
60+
61+
python eventlab_run.py "<baseline>" "<dataset>" "<reference>" "<query>"
62+
63+
The results are saved in the same output locations as normal single-command
64+
runs.

‎docs/conf.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
2323

2424
html_theme = "sphinx_rtd_theme"
25+
html_logo = "_static/logo.svg"
2526

2627
html_theme_options = {
2728
"collapse_navigation": True,
@@ -33,5 +34,13 @@
3334

3435
html_static_path = ["_static"]
3536

37+
html_css_files = [
38+
"copybutton.css",
39+
]
40+
41+
html_js_files = [
42+
"copybutton.js",
43+
]
44+
3645
# Lets Read the Docs set the canonical URL.
3746
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

0 commit comments

Comments
 (0)