Package Exports
- @the-horizon-dev/fast-face-detection
- @the-horizon-dev/fast-face-detection/dist/index.esm.js
- @the-horizon-dev/fast-face-detection/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@the-horizon-dev/fast-face-detection) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Fast Face Detection
Um pacote poderoso e fácil de usar para detecção facial e landmarks usando os modelos MediaPipe.
Características
- ✅ Detecção facial rápida e precisa
- ✅ Detecção de landmarks faciais
- ✅ Rastreamento de faces (tracking)
- ✅ Funciona em navegadores, Node.js e React Native
- ✅ API simples e fácil de usar
- ✅ Tipagem completa em TypeScript
- ✅ Tratamento robusto de erros
- ✅ Métricas de performance
- ✅ Sem necessidade de conhecimento de TensorFlow
Instalação
npm install @the-horizon-dev/fast-face-detection
Dependências para Ambientes Específicos
O pacote carrega automaticamente apenas as dependências necessárias para cada ambiente:
Aplicações Web (navegadores)
# O pacote principal já inclui tudo que você precisa para navegadores
npm install @the-horizon-dev/fast-face-detection
React Native
# Para React Native, é necessário instalar uma dependência adicional:
npm install @the-horizon-dev/fast-face-detection @tensorflow/tfjs-react-native
Node.js
# Para Node.js, você precisará do módulo canvas:
npm install @the-horizon-dev/fast-face-detection canvas
# Para melhor performance em Node.js, recomendamos instalar o backend nativo:
npm install @tensorflow/tfjs-node
Nota: O pacote agora trata
@tensorflow/tfjs-node
como uma dependência opcional, o que significa que ele não será instalado automaticamente em ambientes de navegador. Isso evita problemas com dependências específicas do Node.js como@mapbox/node-pre-gyp
.
Uso Básico
import { mediapipeFace } from '@the-horizon-dev/fast-face-detection';
// Detectar faces em uma imagem
async function detectFaces(imageElement: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement) {
// Detectar faces
const faces = await mediapipeFace.detectFaces(imageElement);
console.log(`Encontradas ${faces.length} faces!`);
// Acessar informações de cada face
faces.forEach(face => {
const { x, y, width, height } = face.detection.box;
const score = face.detection.score;
console.log(`Face em (${x}, ${y}) com tamanho ${width}x${height}, confiança: ${score}`);
});
}
// Detectar faces com landmarks
async function detectLandmarks(imageElement: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement) {
// Detectar faces com landmarks
const facesWithLandmarks = await mediapipeFace.detectFacesWithLandmarks(imageElement);
// Acessar landmarks de cada face
facesWithLandmarks.forEach(face => {
// Pontos faciais (olhos, boca, etc.)
const landmarks = face.landmarks.positions;
// Fazer algo com os landmarks...
landmarks.forEach((point, index) => {
console.log(`Landmark ${index}: (${point.x}, ${point.y})`);
});
});
}
// Lembre-se de liberar recursos quando terminar
function cleanUp() {
mediapipeFace.dispose();
}
Obter Métricas de Performance
A biblioteca agora oferece métricas de performance para ajudar a otimizar sua aplicação:
import { mediapipeFace } from '@the-horizon-dev/fast-face-detection';
async function detectWithMetrics(imageElement) {
// O terceiro parâmetro como 'true' retorna métricas de performance
const result = await mediapipeFace.detectFaces(imageElement, {}, true);
// Acesse as faces detectadas
const faces = result.faces;
console.log(`Detectadas ${faces.length} faces`);
// Acesse as métricas de performance
const timing = result.timing;
console.log(`Tempo total: ${timing.total.toFixed(2)}ms`);
console.log(`Pré-processamento: ${timing.preprocessing.toFixed(2)}ms`);
console.log(`Inferência: ${timing.inference.toFixed(2)}ms`);
console.log(`Pós-processamento: ${timing.postprocessing.toFixed(2)}ms`);
}
Tratamento de Erros Robusto
A biblioteca agora fornece erros detalhados com códigos específicos para um tratamento mais preciso:
import { mediapipeFace, FaceDetection } from '@the-horizon-dev/fast-face-detection';
async function detectFacesWithErrorHandling(imageElement) {
try {
const faces = await mediapipeFace.detectFaces(imageElement);
// Processar faces
} catch (error) {
if (error instanceof FaceDetection.FaceDetectionError) {
// Acesse o código de erro
const errorCode = error.code;
switch (errorCode) {
case FaceDetection.ErrorCode.MODEL_LOAD_FAILED:
console.error('Falha ao carregar o modelo. Verifique sua conexão.');
break;
case FaceDetection.ErrorCode.INVALID_INPUT:
console.error('Entrada inválida. Verifique se a imagem/vídeo é válido.');
break;
case FaceDetection.ErrorCode.DETECTION_FAILED:
console.error('Falha na detecção. Tente novamente com outra imagem.');
break;
// outros códigos de erro...
default:
console.error('Erro desconhecido:', error.message);
}
// Também pode acessar o erro original
if (error.originalError) {
console.error('Erro original:', error.originalError);
}
} else {
console.error('Erro não relacionado à detecção facial:', error);
}
}
}
Opções Avançadas
import { DetectionOptions, ModelType } from '@the-horizon-dev/fast-face-detection';
// Configurações personalizadas com tipagem completa
const options: DetectionOptions = {
scoreThreshold: 0.7, // Limite de confiança (0-1)
maxFaces: 5, // Número máximo de faces a detectar
enableTracking: true, // Ativar rastreamento de faces entre frames
modelType: ModelType.SHORT, // Modelo mais leve e rápido
runtime: 'tfjs' // Runtime do TensorFlow
};
// Uso com opções personalizadas
const faces = await mediapipeFace.detectFaces(imageElement, options);
Otimização de Performance
Pré-carregamento de Modelos
Para aplicações onde você precisa iniciar rapidamente:
// Pré-carregar modelos na inicialização da aplicação
async function initApp() {
// Retorna o ambiente detectado ('browser', 'node' ou 'react-native')
const environment = await mediapipeFace.initialize();
console.log(`Modelos carregados para ambiente ${environment}!`);
}
Controle de Log
A biblioteca permite controlar o nível de log para depuração:
import { utils } from '@the-horizon-dev/fast-face-detection';
// Configurar nível de log
utils.setLogLevel('debug'); // Valores possíveis: 'debug', 'info', 'warn', 'error', 'none'
Carregamento de Recursos
A biblioteca carrega automaticamente apenas os recursos necessários para o ambiente detectado:
- Em navegadores: usa WebGL por padrão, com fallback para CPU
- Em React Native: usa o backend otimizado para React Native
- Em Node.js: usa o backend TensorFlow.js Node nativo se disponível, com fallback para CPU
Uso Avançado com TypeScript
A biblioteca fornece tipagem TypeScript completa:
import {
mediapipeFace,
PossiblyTrackedFace,
TrackedFace,
isTrackedFace,
Box,
Point,
DetectionResult
} from '@the-horizon-dev/fast-face-detection';
// Detectar faces com verificação de rastreamento
async function processTrackedFaces(videoElement: HTMLVideoElement) {
const faces = await mediapipeFace.detectFaces(videoElement, { enableTracking: true });
faces.forEach(face => {
// Verificar se a face possui ID de rastreamento
if (isTrackedFace(face)) {
// face tem trackingID
console.log(`Face #${face.trackingID} em posição:`, face.detection.box);
} else {
// face é uma detecção normal sem trackingID
console.log('Face sem rastreamento em posição:', face.detection.box);
}
});
}
// Função tipada para processar uma caixa delimitadora
function processBox(box: Box) {
const area = box.width * box.height;
return area;
}
// Função tipada para trabalhar com resultado completo
async function analyzeDetectionPerformance(imageElement: HTMLImageElement): Promise<number> {
const result: DetectionResult<PossiblyTrackedFace> =
await mediapipeFace.detectFaces(imageElement, {}, true);
console.log(`Tempo de detecção: ${result.timing.total}ms`);
return result.timing.total;
}
Notas de Performance
- A primeira detecção pode ser mais lenta devido ao carregamento do modelo
- Use
initialize()
para pré-carregar modelos - Para streams de vídeo, use uma taxa de quadros mais baixa para economizar CPU/GPU
- Em dispositivos móveis, considere usar modelos mais leves
Solução de Problemas
WebGL em Headless
Se estiver executando em um ambiente headless (como um servidor Node.js), a biblioteca automaticamente usará o backend CPU.
React Native
Certifique-se de que sua aplicação React Native está configurada corretamente para uso com TensorFlow.js. Consulte a documentação oficial para mais detalhes.
Exemplos
Consulte a pasta /examples
para exemplos completos de:
- Detecção facial em imagens
- Detecção em streams de vídeo
- Uso com React e React Native
- Utilização de landmarks para filtros faciais
Licença
MIT
Testes
A biblioteca inclui testes unitários e de integração. Os testes de integração utilizam imagens reais para verificar o funcionamento correto da detecção facial.
Executar testes
# Executar todos os testes
npm test
# Executar apenas testes unitários
npm run test:unit
# Executar apenas testes de integração
npm run test:integration
Resultados visuais
Os testes de integração com imagens reais geram resultados visuais que são salvos no diretório tests/output/
. Estes resultados mostram as faces detectadas e os pontos faciais (landmarks).
Requisitos para testes
Para executar os testes de integração, você precisará instalar a biblioteca canvas
:
npm install canvas
Em alguns sistemas, pode ser necessário instalar dependências adicionais. Consulte a documentação do node-canvas para mais informações.
Testing
The package includes unit tests for core functionality. To run the tests:
npm test
Testing Limitations
Due to the dependency on TensorFlow.js and browser APIs, some tests may not run correctly in a Node.js environment.
- Unit tests for services and utility functions run well in Node.js
- Integration tests requiring actual face detection need a browser environment
When developing this package, it's recommended to focus on unit testing the non-browser-dependent code.
For full integration testing, consider using a browser-based test environment like Playwright or Cypress.