Configuração gerador template
O gerador de template visa facilitar a criação de templates permitindo a configuração de um conjunto de regiões.
O gerador deve ser no formato PHP. O arquivo é, basicamente, o retorno de um array com as configurações gerais do template e as características dos conjuntos de regiões da imagem.
<?php
return [
'nome' => 'demo',
// Outros atributos irão aqui...
'regioes' => [
[
// Configuração conjunto 1
],[
// Configuração conjunto 2
],
],
];As configurações dos conjuntos serão detalhadas no tópico 'Configuração dos conjuntos' abaixo. Os demais atributos gerais, além do nome serão explicados no final deste artigo no tópico 'Definição atributos gerais'.
- as regiões dentro de um conjunto devem formar uma matriz
mxn, sendomenvalores inteiros quaisquer.
Os atributos tipo, id, p1 e p2 são obrigatórios para definir qualquer tipo de conjunto. Eles representam, respectivamente, o tipo, o identificador das regiões, o ponto superior esquerdo e o ponto inferior direito (formando um retângulo) do conjunto.
O atributo tipo pode conter o valores
- 0: conjunto de elipses
- 1: OCR numérico
'tipo' => 0, // ou 1O atributo id assim como os atributos casoTrue e casoFalse (utilizados para conjuntos de elipses) podem ser uma string ou uma função PHP que permita a definição de um identificador único para cada região dentro do conjunto. A assinatura da função será sempre a seguinte.
'id' => 'nome-unico',
// ou
'id' => function ($b, $l, $o) {
return $b . $l . $o; // ou qualquer outra combinação que gere um identificador único
}Quando o conjunto possui somente um região o id pode ser somente um string. Porém quando o conjunto especifica mais de uma região, por exemplo, o conjunto de elipses usados na folha de respostas, é preciso definir uma função que atribua um identificador único para cada uma das regiões do conjunto. Detalhes sobre o significado das variáveis $b, $l e $o estão abaixo no tópico 'Configuração conjunto de elipses'.
Os atributos p1 e p2 definem, respectivamente, o ponto superior esquerdo e o ponto inferior direito (em pixel) da parte da imagem onde o conjunto deve ser interpretado.
Define um região onde será feito o OCR numérico. Não possui nenhuma configuração além dos atributos obrigatórios. Abaixo um exemplo com a definição completa de um template que possua somente um região, sendo essa do tipo 1.
<?php
return [
'nome' => 'demo',
'regioes' => [
[
'tipo' => 1,
'id' => 'template',
'p1' => [38,3171],
'p2' => [400,3282],
],
],
];O resultado do processamento dessa região será o OCR realizado.
Para definir um conjunto de elipses é preciso especificar quantas quais objetos (conjunto de pontos pretos) devem ser considerados.
Os seguintes atributos devem ser adicionados para especificar um conjunto de elipses.
colunasPorLinhaagrupaObjetosminAreamaxAreacasoTruecasoFalse
Esses atributos alteram a forma como os contadores $b, $l e $o serão incrementados.
O atributo colunasPorLinha simplesmente informa para o gerador quantas elipses foram uma linha, ou seja, a quantidade de colunas por linha. Para a imagem de exemplo sendo utilizada as regiões de preenchimento de respostas possuem 20 colunas a cada linha, portanto:
'colunasPorLinha' => 20,O atributo agrupaObjetos define como dentro de cada linha os objetos da imagem serão agrupados. Neste exemplo queremos agrupar as questões de 5 em 5 formando a relação das alternativas de 'A' a 'E'. Portanto:
'agrupaObjetos' => 5,Tal configuração fará com que os contadores $b, $l e $o, os quais significam, respectivamente, contador de bloco, contador de linha e contador e de objeto possuam os seguintes valores:
-
$b {0,1,2,3}representando cada um dos blocos de questões (1-25, 26-50, 51-75 e 76-100) -
$l {0,1,...,25}representando cada uma das questões dentro de um bloco -
$o {0,1,2,3,4}representando cada um dos objetos dentro de uma linha
Os valores atribuídos para colunasPorLinha e para agrupaObjetos possibilitaram que o contador $o possa ser utilizado para definir o retorno em casoTrue para todas as elipses no conjunto.
Abaixo um exemplo com outro conjunto de elipses de como os valores dos contadores $b, $l e $o são incrementados. Neste exemplo o valore de colunasPorLinha é 10 e agrupaObjetos é 5.
Em azul o contador de bloco $b, em verde o contador de linha dentro de cada bloco $l e em vermelho o contador de objetos dentro de cada linha $o.
Define o valore retornado caso a elipse seja considerada como preenchida. No exemplo que está sendo tratado queremos o retorno 'A', 'B', 'C', 'D' e 'E' para as elipses de cada uma das questões da folha (de 1 a 100). Como comentado anteriormente o atributo casoTrue aceita como valor uma string ou uma função PHP.
Para obter o resultado de retorno como descrito acima é preciso utiliza uma função PHP e considerar o valor do contado de objetos $o para definir a saída. Sendo assim, a função de definição de retorno caso a elipses esteja preenchida será:
'casoTrue' => function($b,$l,$o) {
switch ($o){
case 0: return 'A';
case 1: return 'B';
case 2: return 'C';
case 3: return 'D';
case 4: return 'E';
}
},O atributo casoFalse define o valor de retorno caso a elipse não seja considerada preenchida. Assim como o atributo casoTrue o valor deste atributo pode ser uma string ou uma função PHP.
Para este exemplo todas as regiões consideradas não preenchidas terão o mesmo valore de retorno, no caso 'W'. Portante a definição será:
'casoFalse' => 'W',Definem a área mínima e a área máxima para considerar um objeto (conjunto conectado de pontos pretos) como uma região de interesse.
A quantidade de pixel pretos que compõem o objeto definem sua área.
Considerando todas a imagem de teste em uso e as etapas realizadas nos tópicos acima, a versão completa do gerador de template para a imagem considerando duas regiões, uma de OCR numérico e outra com várias elipses, será o seguinte:
return [
'nome' => 'demo',
'regioes' => [
[
'tipo' => 0,
'p1' => [50,1493],
'p2' => [2225,2674],
'colunasPorLinha' => 20,
'agrupaObjetos' => 5,
'minArea' => 300,
'maxArea' => 3000,
'id' => function($b,$l,$o) {
return "e_{$b}_{$l}_{$o}";
},
'casoTrue' => function($b,$l,$o) {
switch ($o){
case 0: return 'A';
case 1: return 'B';
case 2: return 'C';
case 3: return 'D';
case 4: return 'E';
}
},
'casoFalse' => 'W',
],[
'tipo' => 1,
'id' => 'template',
'p1' => [38,3171],
'p2' => [400,3282],
],
],
];Outros atributos podem ser definidos no gerador de template.
Além do nome e das regioes já descritos acima, os seguintes atributos estão disponíveis.
formatoSaidavalidaReconhecimento
O resultado de um processamento usando certo template retorna uma lista com todos os identificadores e os valores interpretados para cada um deles. Para agrupar os resultados é possível utilizar o atributo formatoSaida, nele é possível definir quais as regiões do template devem ser agrupadas e em qual ordem ('ASC' ou 'DESC', para ascendente e descendente, respectivamente).
Por exemplo, para agrupar todos os resultados das interpretações das elipses em um único campo, basta definir o atributo formatoSaida da seguinte forma.
'formatoSaida' => [
'respostas' => [
'match' => '/^e_.*$/',
'sort' => 'ASC',
],
],Dessa forma, após a aplicação do template, além do resultado individuais de cada uma das regiões também haverá um identificador com o nome de 'respostas' que conterá a concatenação dos resultados das regiões selecionadas pela expressão regular '/^e_.*$/', a qual busca todas as regiões que tenham identificador iniciando com 'e_'.
Algumas imagens podem possuir um identificar de template, em geral, um número fixo para todas as imagens de um trabalho. Para garantir que o template seja aplicado somente em imagens para o qual ele foi definido o atributo validaReconhecimento pode ser utilizado. Quando o valor definido em validaReconhecimento for diferente do valor de retorno esperado para certa região, um erro de processamento será disparado e a imagem não terá o seu processamento exportado.
Por exemplo, caso a região 'template' representasse um OCR sobre uma posição das imagens onde o resultado esperado e sempre o mesmo, digamos '123456'. O atributo validaReconhecimento pode ser definido da seguinte forma:
'validaReconhecimento' => ['template','123456'],Desta forma sempre que uma imagem incorreta ou com problemas (de cabeça para baixo, por exemplo) for processada, os resultados da interpretação (certamente incorretos) não serão exportados.