Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.
Descripción general
Esta guía cubre dos capacidades de analítica de cámara distintas que es fácil confundir:- Reconocimiento facial (identidad) — registra personas conocidas a partir de imágenes de rostros y luego recibe eventos de coincidencia facial cuando una cámara detecta un rostro que coincide. Cada evento incluye una puntuación de confianza y la persona que mejor coincide. Úsalo para reconocer quién aparece en la cámara.
- Conteo de personas (aforo) — analítica de cámara agregada y no identificante que cuenta cuántas personas cruzan el campo de visión de una cámara a lo largo del tiempo. Proviene del servicio de reportes como series temporales de conteo y conteos de ocupación. No implica identidad alguna.
- Registrar y administrar personas creando registros de persona y subiendo imágenes de rostros
- Consultar eventos de coincidencia facial con filtros enriquecidos y paginación
- Ajustar el umbral de coincidencia y corregir eventos mal identificados
- Obtener analíticas de conteo de personas como series temporales o los conteos más recientes por cámara
No es lo mismo que los sensores de ocupación. Rhombus también ofrece sensores de ocupación físicos (hardware Bluetooth/de movimiento) que reportan la presencia en una sala. Esos son un producto aparte servido por una API diferente — consulta la guía de Sensores IoT. El “conteo de personas” de esta página es analítica de cámara.
Requisitos previos
Antes de comenzar, asegúrate de tener:
- Una clave de API de Rhombus. Registrar o administrar rostros requiere permisos de administración de rostros; leer los reportes de conteo de personas requiere acceso de lectura de reportes. Genera y limita el alcance de las claves en la consola de Rhombus, en Configuración > API.
- Al menos una cámara con la analítica correspondiente habilitada (reconocimiento facial para los flujos de identidad, conteo de personas para las analíticas de aforo).
- El reconocimiento facial es una función licenciada y restringida. Si los endpoints de rostros no están disponibles para tu organización, contacta a tu equipo de cuenta de Rhombus para confirmar la habilitación.
POST a https://api2.rhombussystems.com y se autentican con los encabezados x-auth-scheme y x-auth-apikey. Las marcas de tiempo están en milisegundos epoch salvo que se indique lo contrario, y la confianza de coincidencia es un decimal entre 0 y 1.
Registrar y administrar personas conocidas
Una persona es un registro de identidad con nombre para el que registras rostros. Un matchmaker es una plantilla de rostro registrada asociada a una persona; el motor de reconocimiento compara los rostros detectados con tus matchmakers.Crear una persona
Crea un registro de persona con nombre para registrar rostros contra él.Nombre visible de la persona.
person:
Identificador único de la persona.
Nombre visible.
Correo electrónico opcional asociado a la persona.
Organización a la que pertenece la persona.
Cuándo se creó el registro de la persona.
Cuándo se actualizó por última vez el registro de la persona.
Subir una imagen de rostro
Registra un rostro subiendo una imagen.jpg o .png (máximo 5 MB) como multipart/form-data. El archivo debe enviarse bajo el nombre de campo de formulario file. Dos parámetros de consulta opcionales controlan la transacción:
transaction— un ID de transacción que proporcionas para rastrear y luego consultar la subida. Si se omite, el servidor genera uno y lo devuelve.createPersonIfNotFound— establécelo entruepara que el sistema cree una persona nueva automáticamente cuando el rostro subido no coincide con uno existente.
El ID de transacción de esta subida (devuelto tal cual, o generado si lo omitiste). Úsalo para consultar el estado de procesamiento.
Resultados de subida por archivo, cada uno con
fileName, success (booleano) y message.Consultar la transacción de subida
Las imágenes de rostros se procesan de forma asíncrona. Consulta la transacción para conocer elfaceId resultante y el personUuid al que se registró o vinculó el rostro.
faceUploadMetadata incluye:
| Campo | Tipo | Descripción |
|---|---|---|
transactionId | string | La transacción a la que pertenece esta subida |
faceId | string | Identificador del matchmaker de rostro registrado (una vez procesado) |
personUuid | string | Persona a la que se registró o vinculó el rostro |
success | boolean | Si el procesamiento tuvo éxito |
errorMsg | string | Detalle del error cuando success es false |
createdAtMillis | integer | Marca de tiempo de la subida en milisegundos epoch |
origS3Key | string | Clave de almacenamiento de la imagen original subida |
Etiquetar a una persona
Adjunta etiquetas (por ejemplo,employee o visitor) para organizar a las personas y filtrar los eventos faciales más adelante.
removePersonLabel con el mismo cuerpo para quitar una etiqueta, y findPersonLabelsByOrg (cuerpo vacío {}) para obtener un mapa labelsByPerson con las etiquetas de cada persona.
Listar personas y matchmakers
Lista todas las personas registradas confindPeopleByOrg, y lista las plantillas de rostro registradas con findFaceMatchmakersByOrg (o findFaceMatchmakersByPerson para una sola persona).
id (el ID del rostro), personUuid, orgUuid, uploaded (booleano) y createdOn.
Actualizar o eliminar personas y rostros
| Endpoint | Cuerpo | Propósito |
|---|---|---|
/api/faceRecognition/person/getPerson | { "personUuid": "..." } | Obtener una persona |
/api/faceRecognition/person/updatePerson | { "personSelectiveUpdate": { "uuid": "...", "name": "..." } } | Actualizar nombre/correo (selectivo) |
/api/faceRecognition/person/deletePerson | { "personUuid": "..." } | Eliminar una persona |
/api/faceRecognition/matchmaker/getFaceMatchmaker | { "faceId": "..." } | Obtener un rostro registrado |
/api/faceRecognition/matchmaker/deleteFaceMatchmaker | { "faceId": "..." } | Eliminar una plantilla de rostro registrada |
Para administrar la retención y eliminación de datos biométricos, usa
deletePerson (elimina la persona y su registro) y deleteFaceMatchmaker (elimina un solo rostro registrado). Los eventos faciales se pueden eliminar individualmente con deleteFaceEvent (más abajo).Consultar eventos de coincidencia facial
Cuando una cámara detecta un rostro, genera un evento facial. Recupera eventos confindFaceEventsByOrg, que toma un searchFilter y un pageRequest.
Filtro de búsqueda
Todos los campos desearchFilter son opcionales. Cuando se omite timestampFilter, la búsqueda usa por defecto los últimos 7 días.
Filtra por un conjunto de personas.
Filtra por nombres exactos de personas.
Filtra por una subcadena del nombre (mínimo 3 caracteres tras recortar). Tiene precedencia sobre
faceNames si ambos están definidos.Filtra por etiquetas de persona.
Filtra por un conjunto de cámaras.
Filtra por un conjunto de ubicaciones.
Filtra por la presencia (
true) o ausencia (false) de un nombre de persona coincidente.Filtra por la presencia o ausencia de una firma facial.
Ventana temporal con
rangeStart y rangeEnd, cada uno una cadena que contiene un valor en milisegundos epoch (inclusive). Por defecto usa los últimos 7 días.Solicitud de página
Número máximo de eventos a devolver en una página.
Cursor de paginación. Pasa el
lastEvaluatedKey de la respuesta anterior para obtener la página siguiente. Ausente cuando no hay más resultados.Interpretar un evento facial
Cada evento enfaceEvents es un objeto con estos campos:
Identificador único del evento facial.
Cuándo se detectó el rostro, en milisegundos epoch.
Nombre de la persona coincidente. Igual al
name de selectedPersonMatch cuando se seleccionó una coincidencia.UUID de la persona coincidente, si la hay.
Cámara que generó el evento.
Ubicación de la cámara.
Confianza (0–1) de que la imagen detectada es un rostro.
Confianza (0–1) asociada a la firma facial generada.
Si el evento tiene una firma facial.
La coincidencia de persona elegida, con
uuid, name, faceId y confidence (0–1). Nula cuando no se seleccionó ninguna coincidencia.Las mejores coincidencias candidatas para el rostro, cada una con
uuid, name, faceId y confidence (0–1). Útil para revisar coincidencias cercanas.Clave de almacenamiento de la imagen del evento.
Clave de almacenamiento de la miniatura del evento.
Ajustar la coincidencia y corregir eventos
Leer y actualizar el umbral de coincidencia
El umbral de coincidencia controla qué tan estricta es la coincidencia facial. Es un valor de confianza entre0 y 1 — un valor más alto exige una coincidencia más cercana (menos falsos positivos, más omisiones); un valor más bajo es más permisivo.
Confianza mínima de coincidencia (0–1) requerida para considerar que un rostro detectado es una coincidencia.
Corregir un evento mal identificado
Reasigna un evento facial a la persona correcta (o establece un nombre directamente) conupdateFaceEvent. Así corriges coincidencias erróneas.
El evento facial a actualizar.
UUID de la persona correcta a asociar con el evento.
Nombre a asociar con el evento. Se ignora si
personUuid coincide con una de las mejores coincidencias de persona del evento.deleteFaceEvent con { "eventUuid": "..." }.
Analíticas de conteo de personas
El conteo de personas es analítica de cámara agregada — cuenta personas sin identificarlas, servida por el servicio de reportes. Úsalo para tráfico de personas, aforo y paneles de tendencias.Serie temporal de conteo
getCountReportV2 devuelve una serie temporal de conteos agrupados por intervalo. Para el conteo de personas, establece types en ["PEOPLE"].
Inicio del rango en milisegundos epoch.
Fin del rango en milisegundos epoch.
Tamaño del bucket. Uno de
MINUTELY, QUARTERHOURLY, HOURLY, DAILY, WEEKLY, MONTHLY.Alcance de agregación. Uno de
REGION, DEVICE, LOCATION, ORG.Tipos de reporte a incluir. Usa
["PEOPLE"] para el conteo de personas.UUID de destino para el alcance elegido (por ejemplo, un UUID de cámara cuando
scope es DEVICE). Omítelo para el alcance ORG.Zona horaria IANA usada para agrupar los datos (por ejemplo,
America/Los_Angeles).timeSeriesDataPoints incluye:
Inicio del bucket en UTC.
Inicio del bucket en la zona horaria solicitada.
Mapa de tipo de reporte a conteo para el bucket (por ejemplo,
{ "PEOPLE": 42 }).Mapa que describe qué dispositivos reportaron en el bucket.
getCountReportV2 admite muchos types además de PEOPLE — consulta la guía de Reportes y analíticas para conocer el modelo completo de reportes, endpoints de analítica adicionales y la exportación CSV.Conteos de personas más recientes
getMostRecentPeopleCountEvents devuelve los últimos eventos de conteo de personas sin procesar para una cámara — útil para un mosaico de aforo en vivo.
Cámara de la que leer los conteos de personas.
Número de eventos de conteo más recientes a devolver.
eventTimestamp (ms epoch), peopleCount, deviceUuid, locationUuid y uuid.
Conteos de ocupación a lo largo del tiempo
getOccupancyCountsV2 devuelve una serie temporal de conteos de ocupación derivados de la cámara para una sola cámara.
Cámara de la que leer los conteos de ocupación.
Inicio del rango en milisegundos epoch.
Fin del rango en milisegundos epoch.
Tamaño del bucket (
MINUTELY, QUARTERHOURLY, HOURLY, DAILY, WEEKLY, MONTHLY).timestampMs y approximateTimestampMsMap a los campos estándar dateUtc, dateLocal, eventCountMap y reportingDevicesMap.
Este reporte de ocupación es derivado de la cámara. Para la presencia en salas medida por sensores de ocupación físicos (Bluetooth/de movimiento), consulta la guía de Sensores IoT — ese es un producto de hardware aparte con su propia API.
Referencia: enums de reportes
| Enum | Valores |
|---|---|
| Tipo de reporte | CROWD, PEOPLE, FACES, MOTION, BANDWIDTH, VEHICLES, LICENSEPLATES, ALERTS, AM_VERIFICATION, DWELL |
| Intervalo | MINUTELY, QUARTERHOURLY, HOURLY, DAILY, WEEKLY, MONTHLY |
| Alcance | REGION, DEVICE, LOCATION, ORG |
Casos de uso
- Alertas de lista de vigilancia — registra personas de interés y luego consulta
findFaceEventsByOrgfiltrando porpersonUuidsolabelspara marcar avistamientos. - Reconciliación de acceso — cruza los eventos faciales con la actividad de control de acceso para confirmar que la persona que usó su credencial coincide con la que vio la cámara.
- Ciclo de calidad del modelo — revisa
topPersonMatchesen eventos de baja confianza, corrígelos conupdateFaceEventy ajustafaceMatchConfidenceThresholdpara equilibrar falsos positivos y omisiones. - Paneles de tráfico de personas — grafica
getCountReportV2contypes: ["PEOPLE"]para tendencias de tráfico diarias u horarias por cámara o ubicación. - Mosaicos de aforo en vivo — muestra
getMostRecentPeopleCountEventspara una pantalla de aforo casi en tiempo real.
Solución de problemas
Los endpoints de rostros devuelven un error o no están disponibles
Los endpoints de rostros devuelven un error o no están disponibles
El reconocimiento facial es una función licenciada y restringida. Confirma que tu organización esté habilitada y que tu clave de API tenga permisos de administración de rostros. Contacta a tu equipo de cuenta de Rhombus si los endpoints no están disponibles.
uploadFaceMatchmakers rechaza mi archivo
uploadFaceMatchmakers rechaza mi archivo
Envía exactamente un archivo por solicitud bajo el nombre de campo de formulario
file, mantenlo por debajo de 5 MB y usa .jpg o .png. Deja que tu cliente HTTP defina el límite multipart de Content-Type — no establezcas Content-Type manualmente.findFaceUploadMetadataByTransaction aún no devuelve nada
findFaceUploadMetadataByTransaction aún no devuelve nada
Las subidas se procesan de forma asíncrona. Consulta la transacción hasta que cada entrada reporte un valor de
success. Cuando success es false, lee errorMsg para conocer el motivo.No regresan eventos faciales
No regresan eventos faciales
Si omites
timestampFilter, la búsqueda solo cubre los últimos 7 días. Amplía la ventana con rangeStart/rangeEnd (cadenas en milisegundos epoch) y relaja filtros como hasName o personUuids. Recuerda paginar con lastEvaluatedKey.Demasiadas coincidencias falsas (o muy pocas)
Demasiadas coincidencias falsas (o muy pocas)
Ajusta
faceMatchConfidenceThreshold con updateFaceMatchingConfig. Súbelo (más cerca de 1) para reducir falsos positivos; bájalo para capturar más coincidencias potenciales. Corrige los errores individuales con updateFaceEvent.Próximos pasos
Reportes y analíticas
Modelo completo de reportes de conteo, conteos de cruce de umbral y exportación CSV
LPR y vehículos
Detecta y busca placas de matrícula y vehículos en tus cámaras
Sensores IoT
Sensores físicos de ocupación, clima y ambientales
Referencia de la API
Explora y prueba cada endpoint de la API de Rhombus