Sub-Millimetre Cube Pose

Position位置

The cube centre, in metres, in the table frame, sampled uniformly in ±0.075 m. The camera is directly overhead and its image plane is parallel to the table, which means the mapping from pixels to metres is exactly affine — no perspective correction, no distortion model. At 128 px the scale is 367.9 px/m, i.e. one pixel is 2.72 mm.

テーブル座標系における立方体中心の位置（単位はm）で、±0.075 mの範囲から一様にサンプリングします。 カメラは真上にあり、像面はテーブルと平行です。そのためピクセルからメートルへの変換は厳密にaffineで、 透視補正も歪みモデルも不要です。128 pxでのスケールは367.9 px/m、つまり1ピクセルが2.72 mmです。

Two appearance regimes2種類の見た目の条件

Note what is not randomised: geometry, camera pose, object size. Only appearance moves. That keeps the comparison to a single axis, so a result can be attributed.

ランダム化していないものにも注意してください。形状、カメラ姿勢、物体のサイズは固定で、変わるのは見た目だけです。 比較の軸を1つに絞ることで、結果の原因を特定できるようにしています。

Where the label comes fromラベルの出どころ

The generator does not run physics. It writes the pose directly into the simulator's state vector and calls mj_forward, which recomputes all the derived quantities without advancing time:

生成スクリプトは物理演算を実行しません。姿勢をシミュレータの状態ベクトルに直接書き込み、 mj_forwardを呼びます。これは時間を進めずに、派生する量をすべて再計算します。

data.qpos[:3]  = [x, y, CUBE_HALF]
data.qpos[3:7] = [cos(yaw/2), 0, 0, sin(yaw/2)]     # quaternion about z
mujoco.mj_forward(model, data)
renderer.update_scene(data, camera="top")
imgs[i] = renderer.render()
labels[i] = [x, y, sin(4·yaw), cos(4·yaw), yaw]

A quaternion about the z axis is (cos(θ/2), 0, 0, sin(θ/2)) — the halved angle is the standard quaternion convention and is the second most common place to introduce a silent factor-of-two error in this kind of code. The label array keeps the raw yaw in a fifth column for debugging only; nothing trains on it.

z軸まわりのクォータニオンは(cos(θ/2), 0, 0, sin(θ/2))です。角度を半分にするのはクォータニオンの標準的な規約で、 この種のコードで気づかれない2倍の誤差が入り込む場所として2番目に多いところです。ラベル配列の5列目には生のyawを デバッグ用にだけ残しており、学習には一切使いません。

Randomising appearance見た目のランダム化

On hard, four things move per image:

hardでは、画像ごとに次の4つを変化させます。

These are written directly into model.geom_rgba, model.light_pos and model.light_diffuse — fields of the compiled model, mutable at run time, so one XML covers every appearance.

これらはmodel.geom_rgba、model.light_pos、model.light_diffuseに直接書き込みます。 いずれもコンパイル済みモデルのフィールドで、実行時に変更できるため、1つのXMLですべての見た目を表現できます。

Memory-mapped storagememory-mapによる保存

Twelve thousand 128×128 RGB images is about 590 MB. The generator opens the array with np.lib.format.open_memmap and writes into it row by row, so the whole set never has to fit in RAM at once. Training loads it the same way and sorts each batch's indices before slicing, which turns random access into sequential reads from the file — a small change that matters when the data is on disk rather than in memory.

128×128のRGB画像12 000枚は約590 MBです。生成スクリプトはnp.lib.format.open_memmapで配列を開き、 1行ずつ書き込むため、データ全体を一度にRAMに載せる必要はありません。学習時も同じ方法で読み込み、スライスする前に 各batchのインデックスをソートします。これでランダムアクセスがファイルの順次読み込みに変わります。 データがメモリではなくディスク上にある場合に効く、小さな工夫です。

Cost, measured生成コストの計測

900–1080 images per second at 128 px, so 12 000 images takes about twelve seconds. Rendering is not the bottleneck in this project, which is worth stating because it usually is: on this machine OpenGL is software-rendered (llvmpipe under WSL) and shadows are disabled precisely to keep it that way.

128 pxで毎秒900–1080枚なので、12 000枚で約12秒です。このプロジェクトではレンダリングはボトルネックではありません。 普通はボトルネックになるので、あえて明記しておきます。このマシンのOpenGLはソフトウェアレンダリング（WSL上のllvmpipe）であり、 影を無効にしているのはまさにこの速度を保つためです。

Version 1: two hand-written priorsバージョン1：手書きの2つのprior

Both variants share the same pipeline and differ only in the mask:

2つの版は同じ処理の流れを共有し、マスクだけが異なります。

hsv = cvtColor(img, RGB2HSV)
m   = MASKS[method](hsv)                       # 'red' or 'sat'
m   = morphologyEx(m, MORPH_OPEN, ones(3,3))   # kill speckle
c   = max(findContours(m), key=contourArea)    # largest blob
if contourArea(c) < 30: return None            # detection failed
(u,v),(w,h),ang = minAreaRect(c)
x, y = pixel_to_world(u, v, size)
yaw  = mod(radians(-ang), pi/2)                # image v grows down → sign flip

The two priors behave very differently once appearance moves:

見た目が変わると、2つのpriorの挙動は大きく分かれます。

Why the usual head cannot be used一般的なheadが使えない理由

Nearly every image classifier ends with global average pooling: average the feature map over space, then classify. That works because "is this a cat" does not depend on where the cat is — translation invariance is a feature.

ほぼすべての画像分類器は、最後にglobal average poolingを置きます。特徴マップを空間方向に平均してから分類するのです。 「これは猫か」は猫がどこにいるかに依存しないため、これでうまくいきます。平行移動不変性は利点なのです。

A pose regressor needs the opposite. The answer is the location. Average over space and you have thrown away the thing you were asked for. So the head has to preserve spatial information, and there are two ways to do that.

姿勢の回帰では逆が必要です。答えそのものが位置だからです。空間方向に平均すれば、求められているものを捨てることになります。 したがってheadは空間情報を保持しなければならず、その方法は2つあります。

How spatial soft-argmax worksspatial soft-argmaxの仕組み

Given one feature channel of shape (H, W):

形状(H, W)の特徴チャンネル1つに対して、次の処理を行います。

1. Divide by a learned temperature and take a softmax over all H×W positions. The channel is now a probability distribution over pixels — "where in this image is my feature".
2. Build two coordinate grids, u from −1 to 1 left-to-right and v from −1 to 1 top-to-bottom.
3. Take the expectation: E[u] = Σ p·u, E[v] = Σ p·v.

1. 学習可能な温度で割り、H×Wの全位置にわたってsoftmaxを取ります。これでチャンネルはピクセル上の確率分布、 つまり「この特徴は画像のどこにあるか」になります。
2. 座標グリッドを2つ作ります。uは左から右へ−1から1、vは上から下へ−1から1です。
3. 期待値を取ります：E[u] = Σ p·u、E[v] = Σ p·v。

The result is a differentiable, sub-pixel coordinate. The temperature is a learnable parameter stored as its logarithm, so the exponential keeps it strictly positive without a constraint — a low temperature gives a sharp, argmax-like peak; a high one averages broadly.

結果は微分可能で、サブピクセル精度の座標です。温度は対数の形で保持する学習可能パラメータなので、 制約を設けなくても指数関数によって常に正に保たれます。温度が低いとargmaxに近い鋭いピークになり、高いと広く平均されます。

This is the keypoint front end used by visuomotor policies — the deep-spatial-autoencoder line of work — and the reason to implement it here rather than read about it is that the project measures what the prior is worth: 5× fewer parameters, 2.6× faster, and more accurate, with a better tail.

これはvisuomotor policyで使われるkeypointのフロントエンド（deep spatial autoencoderの系譜）です。 読むだけでなくここで実装したのは、このpriorにどれだけの価値があるかを計測するためです。結果は パラメータ数が5分の1、2.6×高速、しかもより高精度で、tailも良好でした。

Training details that are load-bearing結果を左右する学習の詳細