SimpleDet/docs/quickstart.html at official · sirbastiano/SimpleDet · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SimpleDet Docs - Quickstart</title>
    <link rel="stylesheet" href="style.css" />
    <script src="script.js" defer></script>
  </head>
  <body class="theme-aurora">
    <header class="topbar">
      <nav class="nav">
        <a class="brand" href="index.html">SimpleDet <span>Docs</span></a>
        <div class="nav-links">
          <a class="nav-link" href="index.html">Home</a>
          <a class="nav-link" href="installation.html">Installation</a>
          <a class="nav-link" href="quickstart.html">Quickstart</a>
          <a class="nav-link" href="training.html">Training</a>
          <a class="nav-link" href="evaluation.html">Evaluation</a>
          <a class="nav-link" href="screenshots.html">Visuals</a>
        </div>
        <div class="theme-switcher" aria-label="Theme switcher">
          <button class="theme-btn" data-theme="theme-aurora">Aurora</button>
          <button class="theme-btn" data-theme="theme-midnight">Midnight</button>
          <button class="theme-btn" data-theme="theme-volcano">Volcano</button>
        </div>
      </nav>
    </header>
    <main class="main">
      <section class="hero">
        <p class="hero-kicker">SimpleDet Docs</p>
        <h1>Quickstart</h1>
        <p class="subtle">
          This tutorial is the shortest path through the current repository. It explains not only what to run,
          but why the repo is split into a detector-definition step and a native-runtime execution step.
        </p>
        <div class="btn-row">
          <a class="btn" href="overview.html">Overview</a>
          <a class="btn" href="quickstart.html">Quickstart</a>
          <a class="btn" href="core-concepts.html">Core Concepts</a>
          <a class="btn" href="api-reference.html">API Reference</a>
        </div>
        <p class="hero-context">Use this page when you want one guided path from install to detector definition, training, and evaluation.</p>
      </section>
      <section class="content">
        <article class="section">
          <h2>1. Install and verify</h2>
          <p class="section-lead">
            Install the package and CPU runtime first, then verify the command-line surface before working through the examples.
          </p>
          <pre><code>python -m pip install -e .
python -m pip install ".[cpu]"
python -m simpledet --check-runtime</code></pre>
        </article>
        <article class="section">
          <h2>2. Bootstrap a project config</h2>
          <p class="section-lead">
            If you want a repeatable operational workflow, start by creating a project file and validating it before launching training.
          </p>
          <pre><code>python -m simpledet --init-project project.toml
python -m simpledet --project-validate project.toml</code></pre>
        </article>
        <article class="section">
          <h2>3. Build a detector</h2>
          <p class="section-lead">
            A <code>DetectorSpec</code> is the repo’s high-level model description. It says which detector family you want, which backbone it should use,
            and how many classes it must predict. The planner then turns that high-level description into a native build plan.
          </p>
          <pre><code>python - &lt;&lt;'PY'
from pprint import pprint
from simpledet.suite import build_detector, compile_native_detector_plan

spec = build_detector(
    "retinanet",
    encoder="resnet18.a1_in1k",
    num_classes=2,
    in_channels=3,
)
plan = compile_native_detector_plan(spec)

print(spec.family)
pprint(plan.encoder)
pprint(plan.neck)
pprint(plan.head)
PY</code></pre>
          <p>Expected output shape:</p>
          <pre><code>dense
NativeEncoderPlan(type='TimmEncoder', ...)
NativeNeckPlan(type='FPN', ...)
NativeHeadPlan(type='RetinaHead', ...)</code></pre>
          <p>
            The key concept is that you are not writing the full <code>model</code> dictionary by hand.
            SimpleDet inspects the backbone, infers feature channels, and patches the neck and head interfaces for you.
          </p>
        </article>
        <article class="section">
          <h2>4. Train through the native runtime</h2>
          <p class="section-lead">
            The runtime owns everything that is not intrinsic to the detector itself: dataset locations, annotation files,
            image resize, logging, checkpointing, evaluator outputs, and operational validation.
          </p>
          <pre><code>from simpledet import run_training
from simpledet.suite import build_detector

detector_spec = build_detector(
    "retinanet",
    encoder="resnet18.a1_in1k",
    num_classes=2,
    in_channels=3,
)

result = run_training(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
    tif_channels_to_load=[1, 2, 3],
    resize=768,
    batch_size=2,
    learning_rate=0.001,
    max_epochs=10,
    validate=True,
)
print(result["backend"])</code></pre>
          <p>
            The runtime helper assumes the conventional <code>imgs/</code> and <code>Annotations/*_annotations.json</code> layout.
            It validates dataset wiring, assembles the model from the detector spec, and executes the requested native training stages.
          </p>
        </article>
        <article class="section">
          <h2>5. Run without a config file or explicit pipeline object</h2>
          <p class="section-lead">
            If you want the operational pipeline behavior but do not want to create a project config or hold a pipeline instance yourself,
            use the direct execution helpers.
          </p>
          <pre><code>from simpledet import run_training, run_evaluation

train_result = run_training(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
    batch_size=2,
    max_epochs=10,
)

metrics = run_evaluation(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
)</code></pre>
          <p>
            These helpers still use the same project-layout conventions and native runtime internals.
            They just remove the config-file step and the explicit project execution call.
          </p>
        </article>
        <article class="section">
          <h2>6. Evaluate</h2>
          <p class="section-lead">
            Evaluation is not a standalone subsystem in this repo. It reuses the native runtime test path so the evaluator,
            output files, and dataset metadata remain consistent with training.
          </p>
          <pre><code>from simpledet import run_evaluation

metrics = run_evaluation(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
)
print(metrics["backend"])</code></pre>
          <p>Expected artifacts:</p>
          <ul>
            <li><code>native-manifest.json</code></li>
            <li><code>checkpoints/</code></li>
            <li>prediction records returned by the runtime</li>
          </ul>
        </article>
        <article class="section">
          <h2>7. Run the same workflow from a config file</h2>
          <p class="section-lead">
            Once the experiment shape stabilizes, move the same settings into a project config and execute the package through the CLI.
          </p>
          <pre><code>python -m simpledet --project-run project.toml --stages build train test</code></pre>
        </article>
        <article class="section">
          <h2>What to remember</h2>
          <div class="callout-grid">
            <article class="callout">
              <h3>DetectorSpec</h3>
              <p>Describes the detector architecture you want to run.</p>
            </article>
            <article class="callout">
              <h3>Compiled build plan</h3>
              <p>Is the native runtime plan generated from that high-level spec.</p>
            </article>
            <article class="callout">
              <h3>Runtime</h3>
              <p>Attaches runtime concerns such as datasets, workdir layout, hooks, and evaluators.</p>
            </article>
          </div>
        </article>
        <article class="section">
          <h2>8. Use structured configs when the project grows</h2>
          <p class="section-lead">
            The project helpers are the fastest way to start. When experiments become more complex, move to structured config objects so dataset wiring, runtime knobs, and optimization settings are kept separate.
          </p>
          <pre><code>from simpledet import (
    ProjectConfig,
    DatasetConfig,
    RuntimeConfig,
    OptimizationConfig,
    run_project,
)

dataset = DatasetConfig(
    data_root="/path/to/dataset_root",
    annot_file_train="/path/to/annotations/train.json",
    annot_file_val="/path/to/annotations/val.json",
    annot_file_test="/path/to/annotations/test.json",
    categories=("object_a", "object_b"),
    in_channels=3,
)
runtime = RuntimeConfig(result_folder="/path/to/results", resize=768, batch_size=2)
optimization = OptimizationConfig(learning_rate=0.001, optimizer_choice="AdamW")

project = ProjectConfig(
    dataset=dataset,
    runtime=runtime,
    optimization=optimization,
    detector_spec=detector_spec,
)
run_project(project)</code></pre>
        </article>
      </section>
    </main>
    <footer>SimpleDet documentation · Quickstart</footer>
  </body>
</html>