Ir al contenido
DevLab

Solo medir

Envía datos de captura y recibe Human Context Indicators, sin interpretación.

En esta página
  1. Qué obtienes
  2. El protocolo Measurement
  3. Una medición, una inscripción
  4. Cuánto capturar
  5. Lee los indicadores
  6. Sin interpretación
  7. Baseline
  8. Lo que aún no está

Measurement es un contexto sin taxonomía: envías datos de captura y recibes los indicadores, por frame y agregados, sin interpretación. Es la vía del quickstart, que la recorre de punta a punta con el SDK, cURL o Python.

Measurement es un protocolo universal en el entorno de pruebas: todos las organizaciones lo tienen, sin asignación que pedir. El Engine de producción aún no lo ofrece (Tus entornos). Busca el protocolo Measurement en GET /catalog/protocols. Viene con interpreted: false, como todo protocolo que se mide pero nunca se interpreta. Si no está en tu lista, tu entorno aún no lo ofrece (Tus entornos).

triggerAnalysis son dos cosas distintas, y Measurement las trata distinto. En el SDK es una opción de captureProtocol (true por defecto): el SDK pide la interpretación y, con Measurement, Engine la rechaza con un 409. Por HTTP es un campo del lote Final (ausente vale false): Engine lo ignora con Measurement. No hay que renombrar nada: con el SDK pasa triggerAnalysis: false, por HTTP puedes omitirlo.

Con el SDK, dos parámetros lo hacen funcionar hoy:

JavaScript
import { createProtocolClient } from '@neurologyca/capture'
const client = createProtocolClient({ baseUrl: '/engine', taxonomy: { contextId: 'measurement' } })
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'webcam' }, triggerAnalysis: false })

taxonomy: { contextId: 'measurement' } (Measurement no tiene taxonomía, así que vale cualquier valor) y triggerAnalysis: false (no hay nada que interpretar). Desde la 0.29.0, el SDK lo decide solo cuando Engine dice que el protocolo no se interpreta (interpreted: false): no envía taxonomía, no pide análisis aunque pases triggerAnalysis: true y avisa una vez con protocol.not-interpreted. El Engine del entorno de pruebas devuelve interpreted; mantén triggerAnalysis: false con Measurement de todos modos, que lo mantiene funcionando con un Engine que no lo diga: sin él, el SDK pide un análisis que Engine rechaza con 409 PROTOCOL_NOT_ANALYSED, y desde la 0.29.0 eso también acaba complete. El contextId sigue siendo obligatorio en la configuración, aunque Measurement no lo envía. El bucle completo: Quickstart y En el dispositivo (tiempo real).

Por la API HTTP, envías tú los frames; el Quickstart lo recorre con cURL.

Una posición, una mecánica y un step de tipo measurement_free, con un mínimo de 6 segundos y sin máximo:

Cada medición es una inscripción y una captura. Una posición con una captura completada no se puede volver a capturar:

JSON
{
"status": 409,
"body": {
"code": 409,
"reason": "POSITION_ALREADY_COMPLETED",
"message": "This mechanic already has a completed session."
}
}

Para volver a medir a la misma persona, inscríbela otra vez en el mismo protocolo:

Shell
UP=$(curl -s -X POST "$ENGINE/user-protocols" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId)
JavaScript
const res = await fetch(`${ENGINE_BASE}/user-protocols`, {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({ user: EXT, protocol: PROTOCOL }),
});
const { userProtocolId } = await res.json();
Python
res = requests.post(
f"{ENGINE_BASE}/user-protocols",
headers={"Authorization": f"Bearer {TOKEN}"},
json={"user": EXT, "protocol": PROTOCOL},
)
up = res.json()["userProtocolId"]

GET /users/{app_user}/user-protocols lista las inscripciones de una persona, así encuentras sus mediciones anteriores.

  • El catálogo declara al menos 6 segundos. Engine no hace cumplir las duraciones. El SDK avisa por defecto (step.duration-below-min) y, con stepDurations: 'enforce', rechaza (E_STEP_DURATION): ver Steps y marcado.
  • Algunos indicadores necesitan una ventana de señal: solo aparecen pasados unos 5 segundos y, desde entonces, llegan por ventanas, no en todos los frames (uno de cada seis a 30 frames por segundo). Qué frame es el primero cambia de una ejecución a otra, así que nunca esperes un número de frame fijo. En la muestra del quickstart, workload va en pocos de los 300 frames:
JSON
{ "framesWithWorkload": 21, "framesTotal": 300 }
  • Las capturas largas tardan más en cerrarse: se midieron 128 segundos para un step de 5.888 frames. Sondea con una paciencia proporcional.

Cuando la captura de la posición está completa, el stream envía results.ready: con reason: analysis_not_requested si ningún lote pidió interpretación, y con protocol_not_interpreted si el lote Final envió triggerAnalysis (ver Eventos en vivo). Úsalo como señal, y como respaldo sondea GET /results/{userProtocolId}/{protocolMechanicId} hasta que el step 1 tenga entradas, como en el paso 6 del quickstart. aggResults lleva la media de cada indicador en el step y rawResults, el valor por frame. Míralo en el playground.

Measurement no tiene interpretación, así que no llames a POST /analyze en un flujo de Measurement. Si se llama, Engine responde 409 con reason: PROTOCOL_NOT_ANALYSED, antes o después de capturar:

JSON
{
"code": 409,
"reason": "PROTOCOL_NOT_ANALYSED",
"hint": "Its indicators are computed and available through GET /results. There is no narrative analysis for this protocol, and retrying will not produce one."
}

Engine ignora triggerAnalysis con Measurement: no hay interpretación que lanzar. Si lo envías en el lote Final, la captura se completa con los mismos indicadores y el stream envía results.ready:

JSON
{
"events": [
"connected",
"results.ready"
],
"resultsReady": [
{
"stepOrder": 1,
"analysis": false,
"reason": "protocol_not_interpreted"
}
]
}

Sin triggerAnalysis, la misma captura acaba con analysis_not_requested:

JSON
{
"events": [
"connected",
"hci.warning",
"results.ready"
],
"resultsReady": [
{
"stepOrder": 1,
"analysis": false,
"reason": "analysis_not_requested"
}
]
}

La transcripción está apagada por defecto en Measurement: su único step (measurement_free) no es de voz. Si la persona habla y transcribes, Engine guarda el texto y /results lo devuelve como el transcript del step 1 en speech (medido el 2026-11-02; speech, solo en el Engine del entorno de pruebas). Si no, activa la transcripción solo en protocolos con steps de voz (En el dispositivo (tiempo real)).

El baseline se recomienda para comparar personas o sesiones, pero no es obligatorio: la inscripción responde con baselineWarning y sigue. Ver Baseline.

  • En diferido, Measurement funciona desde 0.27.0: triggerAnalysis: false viaja en el manifiesto y el servicio de procesado no llama a /analyze. Desde la 0.29.0, cuando Engine dice interpreted: false, el cliente de grabación lo escribe también en el manifiesto (interpreted: false, siempre con triggerAnalysis: false). Hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada (Diferido (en servidor)).
  • Un kit generado en tu backend: desde capture-server 0.20.0, buildTenantKit da a Measurement su propio kit, kind: 'measurement', con taxonomy.contextId: 'measurement' y un aviso de capturar con triggerAnalysis: false; ramifica por kit.kind y resuélvelo antes de admin.enrol (Tu backend). ProtocolSummary.interpreted dice si un protocolo se interpreta (false con Measurement). Lo que no está: un Engine cuyo catálogo no publica interpreted sigue haciendo que buildTenantKit lance E_KIT_NO_CONTEXT con Measurement, como hacen siempre capture-server 0.19.0 y anteriores. Ahí, usa el kit de Measurement de la consola (Tu integración › Protocolos › un protocolo › Kit): su neuro.config.json lleva taxonomy.contextId: 'measurement' y triggerAnalysis: false.