SimpleDet/docs/core-concepts.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
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SimpleDet Docs - Core Concepts</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="overview.html">Overview</a>
          <a class="nav-link" href="quickstart.html">Quickstart</a>
          <a class="nav-link" href="core-concepts.html">Concepts</a>
          <a class="nav-link" href="configuration-guide.html">Config</a>
          <a class="nav-link" href="training.html">Training</a>
          <a class="nav-link" href="inference.html">Inference</a>
          <a class="nav-link" href="evaluation.html">Evaluation</a>
          <a class="nav-link" href="experiments-reproducibility.html">Repro</a>
          <a class="nav-link" href="diagrams.html">Diagrams</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>Core concepts</h1>
        <p class="subtle">
          SimpleDet makes more sense if you separate three questions: what detector am I defining,
          what runtime is going to execute it, and what artifacts should survive after the run finishes?
        </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">Read this page when the APIs make sense individually but the architecture and artifact flow still feel unclear.</p>
      </section>

      <section class="content">
        <div class="toc">
          <strong>On this page:</strong>
          <a href="#workflow">Workflow</a>
          <a href="#layers">Layers</a>
          <a href="#artifacts">Artifacts</a>
          <a href="#adaptation">Auto-adaptation</a>
        </div>

        <article class="section" id="workflow">
          <h2>Workflow</h2>
          <p class="section-lead">
            The repository follows one main object-detection lifecycle. The model is defined first, then attached to a dataset and runtime,
            then trained into a workdir that preserves checkpoints and evaluator outputs.
          </p>
          <pre><code>dataset
  -&gt; detector_spec
  -&gt; native runtime
  -&gt; training
  -&gt; checkpoint
  -&gt; inference
  -&gt; evaluation</code></pre>

          <pre><code>Recommended path
dataset root + COCO annotations
  -&gt; build_detector(...)
  -&gt; compile_native_detector_plan(...)
  -&gt; run_training(detector_spec=...)
  -&gt; run_evaluation(...)</code></pre>

          <pre><code>Lightweight path
dataset file or folder
  -&gt; load_dataset()
  -&gt; train(config=...)
  -&gt; epoch_001.pth
  -&gt; load_model()
  -&gt; predict()</code></pre>
          <p>
            The recommended path is the first one. The lightweight path is intentionally smaller and compatible with fewer checkpoints and behaviors.
          </p>
        </article>

        <article class="section" id="layers">
          <h2>Layers</h2>
          <ul>
            <li><strong>Authoring layer:</strong> <code>simpledet.suite</code> provides <code>DetectorSpec</code>, builders, and native planning.</li>
            <li><strong>Runtime layer:</strong> <code>run_training</code>, <code>run_inference</code>, <code>run_evaluation</code>, and <code>run_project</code> wire data and own the workdir.</li>
            <li><strong>Compatibility helpers:</strong> <code>simpledet.detectors.*</code> covers lightweight training, inference, and dataset loading.</li>
          </ul>
          <p>
            The important boundary is this: <code>simpledet.suite</code> decides the detector structure, while
            the native runtime decides how that detector is executed in a full experiment.
          </p>
        </article>

        <article class="section">
          <h2>What gets compiled and what stays runtime-configured</h2>
          <div class="callout-grid">
            <article class="callout">
              <h3>Compiled from the detector spec</h3>
              <p>Backbone, neck, dense head, ROI head, transformer blocks, class count, and downstream channel interfaces.</p>
            </article>
            <article class="callout">
              <h3>Configured by the pipeline</h3>
              <p>Dataset paths, dataloaders, resize policy, optimizer and scheduler settings, hooks, workdir layout, and evaluator outputs.</p>
            </article>
          </div>
        </article>

        <article class="section" id="artifacts">
          <h2>Artifacts</h2>
          <ul>
            <li><code>native-manifest.json</code> for the run summary</li>
            <li><code>checkpoints/</code> for the retained checkpoint files</li>
            <li>prediction records returned by the evaluation runtime</li>
          </ul>
          <p>In the lightweight path, the main artifacts are <code>epoch_001.pth</code> and <code>metrics.json</code>.</p>
          <p>
            This difference matters because a checkpoint from one path is not automatically interchangeable with the other.
            The native runtime path is the canonical execution surface for the current package.
          </p>
        </article>

        <article class="section" id="adaptation">
          <h2>Backbone auto-adaptation</h2>
          <p>When you build a detector with a supported <code>timm</code> backbone, SimpleDet can inspect the feature channels and patch downstream modules automatically.</p>
          <ul>
            <li>neck <code>in_channels</code></li>
            <li>dense head channel fields</li>
            <li>RPN and ROI bbox or mask heads</li>
            <li>ROI extractor output channels</li>
            <li>transformer embed dimensions and feature levels</li>
            <li><code>num_classes</code></li>
          </ul>
          <p>
            In practice, this means you can swap from one supported encoder to another without manually recalculating neck
            input channels or editing several head sections by hand.
          </p>
          <p class="notice">This covers <code>timm</code> encoders with usable feature metadata and custom backbones only when you provide <code>backbone_cfg</code> plus explicit <code>feature_channels</code>.</p>
        </article>
        <article class="section">
          <h2>Custom component mechanism</h2>
          <p class="section-lead">
            SimpleDet now exposes a suite-level customization path for registry-backed backbones, necks, heads, and decoders without dropping to handwritten low-level component wiring.
          </p>
          <pre><code>from simpledet.suite import build_custom_encoder, build_custom_neck, build_detector

spec = build_detector(
    "retinanet",
    num_classes=2,
    encoder=build_custom_encoder(
        "MyBackbone",
        imports=("my_project.detectors.backbones",),
        feature_channels=[64, 128, 256, 512],
    ),
    neck=build_custom_neck(
        "MyNeck",
        imports=("my_project.detectors.necks",),
        out_channels=256,
    ),
)</code></pre>
          <p>
            The important contract is explicit: custom components are still registry-backed types, but the suite now carries the required
            <code>imports</code> metadata into the native build plan so those modules can be resolved at runtime.
          </p>
        </article>
      </section>
    </main>

    <footer>SimpleDet documentation · Core concepts</footer>
  </body>
</html>