pose_estimation

"web_ui"

[!NOTE] Esta é uma versão traduzida do README. A versão em inglês é a fonte de referência.

Um contêiner para estimativa de pose a partir de imagens 2D.

Mapeamento de ossos de Pose para VRM

O backend retorna keypoints de pose e pares de ossos no estilo BODY_25. No MediaPipe mode, Neck é sintetizado a partir de LShoulder e RShoulder, e MidHip é sintetizado a partir de LHip e RHip. Use a tabela abaixo ao transferir a pose estimada para um VRM humanoid skeleton.

Vetor de pose estimado	Keypoints de entrada	VRM humanoid bone	Prioridade	Observações
Raiz do corpo	`MidHip`, `LHip`, `RHip`	`hips`	Required	Use principalmente para root rotation. Evite confiar em root translation a partir de uma única imagem.
Spine	`MidHip -> Neck`	`spine`	Required	Direção principal da parte superior do corpo.
Chest	`MidHip -> Neck`	`chest`	Recommended	Aplique com um weight mais fraco que `spine` para evitar curvatura exagerada.
Upper chest	`MidHip -> Neck`	`upperChest`	Optional	Use somente quando o VRM model carregado tiver este bone.
Neck	`Neck -> Nose`	`neck`	Recommended	Aplique com suavidade, porque os landmarks de head e neck são ruidosos na estimativa de pose com uma única imagem.
Head	`Neck -> Nose`, `Nose -> LEye`, `Nose -> REye`, `LEye -> LEar`, `REye -> REar`	`head`	Recommended	Um simple fallback pode usar apenas `Neck -> Nose`; eye e ear points podem melhorar a direção de orientação.
Left shoulder	`Neck -> LShoulder`	`leftShoulder`	Optional	Use somente quando o VRM tiver shoulder bones. O arm ainda pode ser controlado sem este bone.
Left upper arm	`LShoulder -> LElbow`	`leftUpperArm`	Required	Rotação principal do braço superior esquerdo.
Left lower arm	`LElbow -> LWrist`	`leftLowerArm`	Required	Rotação principal do antebraço esquerdo.
Left hand	`LElbow -> LWrist` or hand landmarks	`leftHand`	Optional	BODY_25 não fornece wrist orientation suficiente. Use um fallback fraco, a menos que hand landmarks estejam disponíveis.
Right shoulder	`Neck -> RShoulder`	`rightShoulder`	Optional	Use somente quando o VRM tiver shoulder bones.
Right upper arm	`RShoulder -> RElbow`	`rightUpperArm`	Required	Rotação principal do braço superior direito.
Right lower arm	`RElbow -> RWrist`	`rightLowerArm`	Required	Rotação principal do antebraço direito.
Right hand	`RElbow -> RWrist` or hand landmarks	`rightHand`	Optional	BODY_25 não fornece wrist orientation suficiente. Use um fallback fraco, a menos que hand landmarks estejam disponíveis.
Left upper leg	`LHip -> LKnee`	`leftUpperLeg`	Required	Rotação principal da coxa esquerda.
Left lower leg	`LKnee -> LAnkle`	`leftLowerLeg`	Required	Rotação principal da canela esquerda.
Left foot	`LAnkle -> LBigToe`, `LAnkle -> LHeel`	`leftFoot`	Recommended	Use toe e heel points quando estiverem visíveis.
Left toes	`LHeel -> LBigToe`	`leftToes`	Optional	Use somente quando o VRM tiver toe bones e os toe landmarks forem estáveis.
Right upper leg	`RHip -> RKnee`	`rightUpperLeg`	Required	Rotação principal da coxa direita.
Right lower leg	`RKnee -> RAnkle`	`rightLowerLeg`	Required	Rotação principal da canela direita.
Right foot	`RAnkle -> RBigToe`, `RAnkle -> RHeel`	`rightFoot`	Recommended	Use toe e heel points quando estiverem visíveis.
Right toes	`RHeel -> RBigToe`	`rightToes`	Optional	Use somente quando o VRM tiver toe bones e os toe landmarks forem estáveis.
Left eye	`Nose -> LEye`	`leftEye`	Optional	Necessário apenas para recursos de gaze ou expression.
Right eye	`Nose -> REye`	`rightEye`	Optional	Necessário apenas para recursos de gaze ou expression.

Os VRM bones mínimos úteis são spine, leftUpperArm, leftLowerArm, rightUpperArm, rightLowerArm, leftUpperLeg, leftLowerLeg, rightUpperLeg e rightLowerLeg. Depois que eles estiverem estáveis, adicione hips, chest, neck, head, leftFoot e rightFoot para uma avatar pose mais legível.

Iniciar o projeto

cp .env.example .env
docker compose up --build

Abra o navegador:

http://localhost:8081

Verifique a API:

curl http://localhost:8000/api/v1/health

Como usar

Pressione “Select image”.
Selecione uma image.
Confira os 2D keypoints sobrepostos na image.
Confira a pose direction na visualização inferior “3D skeleton check”.

Tests

Execute os backend tests:

docker compose -f docker-compose.test.yml run --rm backend_test

Execute o frontend smoke test:

docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm frontend_test

License

Apache License 2.0