Se você precisar de mais flexibilidade para fazer upload de imagens no Google Earth Engine (EE) do que a
interface do editor de código
ou o comando upload da
ferramenta de linha de comando "earthengine"
fornecem, descreva um upload de imagem usando um arquivo JSON conhecido como "manifesto"
e use o comando upload image --manifest da ferramenta de linha de comando.
Confira um exemplo completo neste notebook do Colab, que demonstra como fazer upload de blocos de imagem como um único recurso usando um manifesto.
Configuração única
- Os uploads de manifestos só funcionam com arquivos localizados no Google Cloud Storage. Para começar a usar o Google Cloud Storage, crie um projeto na nuvem do Google, se ainda não tiver um. A configuração exige que você especifique um cartão de crédito para faturamento. A EE não está cobrando ninguém no momento, mas a transferência de arquivos para o Google Cloud Storage antes de fazer o upload para a EE terá um pequeno custo. Para tamanhos de dados de upload típicos (dezenas ou centenas de gigabytes), o custo será bastante baixo.
- No projeto, ative a API Cloud Storage e crie um bucket.
- Instale o cliente Python do Earth Engine. Ela inclui a ferramenta de linha de comando
earthengine, que será usada para fazer upload de dados. - Para uploads automatizados, use uma conta de serviço do Google Cloud associada ao seu projeto. Você não precisa de uma conta de serviço para fazer testes, mas, quando tiver um tempo, comece a se familiarizar com o uso delas.
Arquivos de origem muito grandes (100 GB ou mais) podem ser enviados mais rapidamente se forem divididos em vários blocos.
IDs e nomes de recursos
Para ativos de propriedade de projetos na nuvem, use esta convenção para nomes de ativos:
projects/some-project-id/assets/some-asset-id.
Aprenda Mais sobre os nomes de recursos para projetos legados e recursos de propriedade do usuário
Para projetos legados mais antigos, o nome do recurso no manifesto precisa ser
um pouco diferente do código do recurso visível
em outros lugares no Earth Engine. Para fazer upload de recursos com IDs que começam com
users/some_user ou projects/some_project, o nome do recurso no
manifesto precisa ter a string projects/earthengine-legacy/assets/ anexada ao
ID. Por exemplo, o código do recurso do EE users/username/my_geotiff precisa ser enviado
com o nome projects/earthengine-legacy/assets/users/username/my_geotiff.
Sim, isso significa que IDs como projects/some_projects/some_asset são
convertidos em nomes em que projects é mencionado duas vezes:
projects/earthengine-legacy/assets/projects/some_projects/some_asset.
Isso é confuso, mas necessário para estar em conformidade com os padrões da API Google Cloud.
Usar manifestos
Um manifesto básico é mostrado no bloco de código a seguir. Ele faz upload de um arquivo chamado
small.tif de um bucket do Google Cloud Storage chamado
gs://earthengine-test.
{
"name": "projects/some-project-id/assets/some-asset-id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://earthengine-test/small.tif"
]
}
]
}
]
}Para usá-lo, salve-o em um arquivo chamado manifest.json e execute:
earthengine upload image --manifest /path/to/manifest.json
O arquivo gs://earthengine-test/small.tif existe e é
legível publicamente. Você pode usá-lo para testes.
Tilesets
A estrutura de manifesto um tanto complicada do JSON é necessária para dar flexibilidade suficiente para lidar com um desafio comum de upload: como descrever todas as maneiras possíveis de combinar pixels de vários arquivos de origem em um único recurso. Especificamente, há duas maneiras independentes de agrupar arquivos:
- Mosaicos. Às vezes, vários arquivos representam vários blocos (por exemplo, cada bloco é um quadrado de 1x1 grau). Esses arquivos precisam ser mosaicos (mesclados) na mesma banda em um recurso do EE.
- Bandas separadas. Às vezes, vários arquivos representam várias bandas. Esses arquivos precisam ser empilhados como bandas em um recurso do EE.
(Pode ser necessário usar as duas formas ao mesmo tempo, mas essa é uma situação rara.)
Para descrever essas opções, os manifestos introduzem a noção de um tileset. Um único tileset corresponde a uma única fonte GDAL. Por isso, todas as fontes em um único tileset precisam ter a mesma estrutura GDAL (número e tipo de bandas, projeção, transformação, valor ausente). Como uma fonte GDAL pode ter várias bandas, um tileset pode conter dados de várias bandas do EE.
Para a ingestão de mosaico, o manifesto será assim:
{
"name": "projects/some-project-id/assets/some-asset-id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://bucket/N30W22.tif"
]
},
{
"uris": [
"gs://bucket/N31W22.tif"
]
}
]
}
]
}Para bandas separadas, o manifesto será
assim (você também precisa adicionar uma seção bands,
conforme explicado abaixo):
{
"name": "projects/some-project-id/assets/some-asset-id",
"bands": ...,
"tilesets": [
{
"id": "tileset_for_band1",
"sources": [
{
"uris": [
"gs://bucket/band1.tif"
]
}
]
},
{
"id": "tileset_for_band2",
"sources": [
{
"uris": [
"gs://bucket/band2.tif"
]
}
]
}
]
}No caso de bandas separadas, precisamos dar a cada tileset um ID diferente para fins de esclarecimento. O ID do conjunto de blocos pode ser uma string arbitrária. Essas strings não são mantidas no recurso enviado. Os IDs de conjunto de blocos são usados apenas na ingestão para distinguir conjuntos de blocos empilhados uns dos outros.
Bandas
O segundo conceito importante é a correspondência de arquivos de origem com as bandas de recursos do EE.
Isso é feito usando a seção bands do manifesto.
A seção bands pode ser omitida. Nesse caso, as bandas são criadas primeiro
com base nos arquivos do primeiro conjunto de blocos, depois do próximo conjunto de blocos e assim por diante.
Por padrão, as bandas são chamadas de "b1", "b2" etc. Para substituir os nomes padrão, inclua
uma seção "bands" no final, como esta:
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://bucket/rgb.tif"
]
}
]
}
],
"bands": [
{
"id": "R",
"tilesetBandIndex": 0
},
{
"id": "G",
"tilesetBandIndex": 1
},
{
"id": "B",
"tilesetBandIndex": 2
}
]
}O número de bandas do EE precisa ser igual ao número total de bandas em todos os conjuntos de blocos.
Se você não quiser ingerir todas as bandas de um arquivo, use o campo tilesetBandIndex para indicar quais bandas GDAL devem ser ingeridas.
A primeira banda tem tilesetBandIndex de 0.
Exemplo:
Suponha que o arquivo de origem tenha quatro bandas: "tmin", "tmin_error", "tmax", "tmax_error". Queremos ingerir apenas "tmin" e "tmax". As seções relevantes do manifesto serão assim:
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"id": "temperature",
"sources": [
{
"uris": [
"gs://bucket/temperature.tif"
]
}
]
}
],
"bands": [
{
"id": "tmin",
"tilesetBandIndex": 0,
"tilesetId": "temperature"
},
{
"id": "tmax",
"tilesetBandIndex": 2,
"tilesetId": "temperature"
}
]
}Bandas de máscara
A máscara de banda é controlada pelo componente maskBands do manifesto.
Há suporte para três configurações de máscara possíveis, mas a banda de máscara é sempre considerada
a última banda em um determinado arquivo.
- Máscara para todas as bandas de dados no mesmo arquivo.
- Máscara para todas as bandas de dados de todos os outros arquivos.
- Máscara para algumas bandas de dados.
1. O caso mais comum é um único GeoTIFF em que a última banda é usada como máscara para as outras bandas. Isso só funciona para GeoTIFFs do tipo Byte. Use o seguinte manifesto:
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"id": "data_tileset",
"sources": [
{
"uris": [
"gs://bucket/data_file.tif"
]
}
]
}
],
"bands": [
{
"id": "data_band",
"tilesetId": "data_tileset"
},
{
"id": "qa_band",
"tilesetId": "data_tileset"
}
],
"maskBands": [
{
"tilesetId": "data_tileset"
}
]
}2. Para usar um GeoTIFF como máscara para todas as bandas em outro GeoTIFF, use o seguinte manifesto:
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"id": "data_tileset",
"sources": [
{
"uris": [
"gs://bucket/data_file.tif"
]
}
]
},
{
"id": "mask_tileset",
"sources": [
{
"uris": [
"gs://bucket/mask_file.tif"
]
}
]
}
],
"bands": [
{
"id": "data_band",
"tilesetId": "data_tileset"
},
{
"id": "qa_band",
"tilesetId": "data_tileset"
}
],
"maskBands": [
{
"tilesetId": "mask_tileset"
}
]
}3. Para usar um GeoTIFF como máscara para uma banda específica em outro arquivo, use o
manifesto a seguir (a diferença em relação ao caso anterior é que o
campo bandIds em maskBands está definido):
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"id": "data_tileset",
"sources": [
{
"uris": [
"gs://bucket/data_file.tif"
]
}
]
},
{
"id": "mask_tileset",
"sources": [
{
"uris": [
"gs://bucket/mask_file.tif"
]
}
]
}
],
"bands": [
{
"id": "data_band",
"tilesetId": "data_tileset"
},
{
"id": "qa_band",
"tilesetId": "data_tileset"
}
],
"maskBands": [
{
"tilesetId": "mask_tileset",
"bandIds": ["data_band"]
}
]
}No último exemplo, estamos trabalhando com duas bandas do conjunto de blocos data_tileset, mas aplicando uma máscara apenas a uma delas (data_band), conforme designado pelo campo bandIds do único objeto de lista maskBands fornecido.
Somente a última banda do conjunto de blocos mencionado em maskBands é usada como
a banda de máscara.
Política de pirâmide
Quando o Earth Engine cria
pirâmides de imagens
durante a ingestão, ele precisa reduzir repetidamente grades de 2x2 pixels em um único pixel,
transformando o valor do pixel de alguma forma. Por padrão, os valores de pixel são calculados pela média, o que
é o certo a se fazer na maioria dos casos em que a banda raster representa dados mais ou menos
contínuos. No entanto, há duas situações em que o uso do padrão
produz resultados incorretos. Nesse caso, o campo pyramidingPolicy na
definição da banda precisa ser definido. Se não for, o valor será considerado "MEAN"
por padrão.
Para a classificação de imagens rasterizadas (por exemplo, para classificação de cobertura do solo), a maneira mais lógica de criar pirâmides de pixels é usar a maioria dos quatro valores para produzir o próximo. Isso é feito usando a política de pirâmide "MODE":
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://bucket/landcover.tif"
]
}
]
}
],
"bands": [
{
"id": "landcover",
"pyramidingPolicy": "MODE"
}
]
}Para bandas raster em que nem "MEAN" nem "MODE" fazem sentido (por exemplo, pixels compactados em bits), use a política de pirâmide "SAMPLE". "SAMPLE" sempre usa o valor do pixel superior esquerdo de cada grade 2x2. O exemplo a seguir atribui a política de pirâmide "MEAN" a uma banda que representa uma variável contínua ("NDVI") e "SAMPLE" à banda "QA" dos dados.
{
"name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://bucket/ndvi.tif"
]
}
]
}
],
"bands": [
{
"id": "NDVI",
"tilesetBandIndex": 0,
"pyramidingPolicy": "MEAN"
},
{
"id": "QA",
"tilesetBandIndex": 1,
"pyramidingPolicy": "SAMPLE"
}
]
}Horário de início e término
Todos os recursos precisam especificar o horário de início e término para dar mais contexto aos dados, especialmente se estiverem incluídos em coleções. Esses campos não são obrigatórios, mas recomendamos usá-los sempre que possível.
Os horários de início e término geralmente se referem ao horário da observação, não ao horário em que o arquivo de origem foi produzido.
O horário de término é tratado como um limite exclusivo para simplificar. Por exemplo, para recursos que abrangem exatamente um dia, use a meia-noite de dois dias consecutivos (por exemplo, 1980-01-31T00:00:00 e 1980-02-01T00:00:00) para o horário de início e término. Se o recurso não tiver duração, defina o horário de término como o mesmo do início. Represente os horários nos manifestos como strings ISO 8601. Recomendamos presumir que o horário de término é exclusivo (por exemplo, meia-noite do dia seguinte para recursos diários) para simplificar os valores de data.
Exemplo:
{
"name": "projects/some-project-id/assets/some-asset-id",
"tilesets": [
{
"sources": [
{
"uris": [
"gs://bucket/img_20190612.tif"
]
}
]
}
],
"startTime": "1980-01-31T00:00:00Z",
"endTime": "1980-02-01T00:00:00Z"
}Referência da estrutura do manifesto
A estrutura JSON a seguir inclui todos os campos possíveis do manifesto de upload de imagens. Encontre as definições de campo na seção Definições de campo do manifesto.
{ "name": <string>, "tilesets": [ { "dataType": <string>, "id": <string>, "crs": <string>, "sources": [ { "uris": [ <stringn>> ], "affineTransform": { "scaleX": <double>, "shearX": <double>, "translateX": <double>, "shearY": <double>, "scaleY": <double>, "translateY": <double> } } ] } ], "bands": [ { "id": <string>, "tilesetId": <string>, "tilesetBandIndex": <int32>, "missingData": { "values": [<doublen>>] }, "pyramindingPolicy": <string> } ], "maskBands": [ { "tilesetId": <string>, "bandIds": [ <stringn>> ] } ], "footprint": { "points": [ { "x": <double>, "y": <doublen>> } ], "bandId": <string> }, "missingData": { "values": [<double>] }, "pyramidingPolicy": <string>, "uriPrefix": <string>, "startTime": { "seconds": <integer> }, "endTime": { "seconds": <integer> }, "properties": { <unspecified> } }
Definições de campo do manifesto
nome
string
O nome do recurso a ser criado.
name está no formato "projects/*/assets/**"
(por exemplo, "projects/earthengine-legacy/assets/users/USER/ASSET").
tilesets
list
Uma lista de dicionários que definem propriedades para conjuntos de blocos.
Consulte os seguintes campos de elemento de dicionário tilesets
para mais informações.
tilesets[i].dataType
string
Especifica o tipo de dados numéricos. O padrão é o tipo que o GDAL informa. Nesse caso, não é necessário definir.
| Tipo de dado | Valor |
|---|---|
| Não especificado | "DATA_TYPE_UNSPECIFIED" |
| Número inteiro assinado de 8 bits | "INT8" |
| Número inteiro sem sinal de 8 bits | "UINT8" |
| Número inteiro assinado de 16 bits | "INT16" |
| Número inteiro sem sinal de 16 bits | "UINT16" |
| Número inteiro assinado de 32 bits | "INT32" |
| Número inteiro sem assinatura de 32 bits | "UINT32" |
| Ponto flutuante de 32 bits | "FLOAT32" |
| Ponto flutuante de 64 bits | "FLOAT64" |
tilesets[i].id
string
O ID do tileset. Precisa ser exclusivo entre os tilesets especificados no manifesto do recurso. Esse ID é descartado durante a etapa de processamento e é usado apenas para vincular um conjunto de blocos a uma banda. A string vazia é um ID válido.
tilesets[i].crs
string
O sistema de referência de coordenadas da grade de pixels, especificado como um código padrão sempre que possível (por exemplo, código EPSG) e no formato WKT, caso contrário.
tilesets[i].sources
list
Uma lista de dicionários que definem as propriedades de um arquivo de imagem e
os sidecars dele. Consulte os seguintes campos de elemento de dicionário sources
para mais informações.
tilesets[i].sources[j].uris
list
Uma lista dos URIs dos dados a serem ingeridos. Somente URIs do Google Cloud Storage
são compatíveis. Cada URI precisa ser especificado no seguinte formato:
gs://bucket-id/object-id.
O objeto principal precisa ser o primeiro elemento da lista, e os sidecars
listados depois. Cada URI é prefixado com
ImageManifest.uriPrefix, se definido.
tilesets[i].sources[j].affineTransform
dictionary
Uma transformação afim opcional. Só deve ser especificado se os dados de uris (incluindo sidecars) não forem suficientes para posicionar os pixels.
Fornecido como um dicionário com as seguintes chaves:
"scaleX", "shearX", "translateX", "shearY", "scaleY", "translateY".
Consulte
esta referência para mais informações.
Exemplos de chaves e valores:
{
"scaleX": 0.1,
"shearX": 0.0,
"translateX": -180.0,
"shearY": 0.0,
"scaleY": -0.1,
"translateY": 90.0
}bandas
list
Uma lista de dicionários que definem as propriedades de uma única banda de um conjunto de blocos.
A ordem das bandas do recurso é igual à ordem de bands.
Consulte os seguintes campos de elemento do dicionário bands para mais informações.
bands[i].id
string
O ID (nome) da banda.
bands[i].tilesetId
string
O ID do conjunto de blocos correspondente à banda.
bands[i].tilesetBandIndex
int32
O índice de banda baseado em zero do conjunto de blocos correspondente à banda.
bands[i].missingData.values
list
Uma lista de valores (tipo duplo) que representam a ausência de dados na banda.
bands[i].pyramidingPolicy
string
A política de pirâmide. Consulte este link para mais informações. As opções incluem:
- "MEAN" (padrão)
- "MODE"
- "SAMPLE"
maskBands
list
Uma lista de dicionários que definem as propriedades de uma única banda de máscara de um conjunto de blocos.
No máximo uma banda de máscara pode ser fornecida.
Consulte os seguintes campos de elemento do dicionário maskBands para mais informações.
maskBands[i].tilesetId
string
O ID do conjunto de blocos correspondente à banda de máscara. A última banda do conjunto de blocos é sempre usada como a banda de máscara.
maskBands[i].bandIds
list of strings
Lista dos IDs das bandas às quais a banda de máscara se aplica. Se estiver vazia, a banda de máscara será aplicada a todas as bandas no recurso. Cada banda pode ter apenas uma banda de máscara correspondente.
footprint
dictionary
Um dicionário que define as propriedades da pegada de todos os pixels válidos em uma imagem.
Se estiver vazio, o footprint padrão será a imagem inteira. Consulte os
campos de elemento do dicionário footprint a seguir para mais informações.
footprint.points
list
Uma lista de pontos que definem uma área de todos os pixels válidos em uma imagem. Um ponto
é definido por um dicionário com as chaves "x" e "y" com valores flutuantes. Uma lista de
pontos descreve um anel que forma o exterior de um polígono simples que precisa conter
os centros de todos os pixels válidos da imagem. Precisa ser um anel linear: o
último ponto precisa ser igual ao primeiro. As coordenadas estão na projeção da
banda especificada por bandId.
Observação: use coordenadas não inteiras, como o centro de cada pixel, porque
footprint é usado para incluir um pixel se ele (um retângulo 1x1)
cruzar a área de cobertura. Para evitar a seleção acidental de pixels vizinhos, não use coordenadas de valor inteiro, porque elas são os limites entre os pixels. Desenhar a área de cobertura ao longo dos centros de pixels
evita a inclusão de pixels não intencionais, o que pode causar erros quando os pixels pretendidos
estão encostados em um limite do mapa, como o antimeridiano ou um polo.
Por exemplo, para uma imagem 2x2 com todos os quatro pixels válidos, o seguinte é um anel possível:
[
{
"x": 0.5,
"y": 0.5
},
{
"x": 0.5,
"y": 1.5
},
{
"x": 1.5,
"y": 1.5
},
{
"x": 1.5,
"y": 0.5
},
{
"x": 0.5,
"y": 0.5
}
]footprint.bandId
string
O ID da banda cujo CRS define as coordenadas da área de cobertura. Se estiver vazio, a primeira banda será usada.
missingData.values
list
Uma lista de valores (tipo duplo) que representam a ausência de dados em todas as bandas da imagem. Aplica-se a
todas as bandas que não especificam o próprio missingData.
pyramidingPolicy
string
A política de pirâmide. Se não for especificada, a política "MEAN" será aplicada por padrão. Aplica-se a todas as bandas que não especificam as próprias. Consulte este link para mais informações. As opções incluem:
- "MEAN" (padrão)
- "MODE"
- "SAMPLE"
uriPrefix
string
Um prefixo opcional adicionado a todos os uris definidos no manifesto.
startTime
integer
O carimbo de data/hora associado ao recurso, se houver. Isso geralmente corresponde ao momento em que uma imagem de satélite foi tirada. Para recursos que correspondem a um intervalo de tempo, como valores médios ao longo de um mês ou ano, esse carimbo de data/hora corresponde ao início desse intervalo. Especificado como segundos e (opcionalmente) nanossegundos desde a época (1970-01-01). Presume-se que esteja no fuso horário UTC.
endTime
integer
Para recursos que correspondem a um intervalo de tempo, como valores médios ao longo de um mês ou ano, esse carimbo de data/hora corresponde ao final desse intervalo (exclusivo). Especificado como segundos e (opcionalmente) nanossegundos desde a época (1970-01-01). Presume-se que esteja no fuso horário UTC.
propriedades
dictionary
Um dicionário simples arbitrário de pares de chave-valor. As chaves precisam ser strings, e os valores podem ser números ou strings. Os valores de lista ainda não são compatíveis com recursos enviados pelo usuário.
Limitações
Tamanho do manifesto JSON
O limite de tamanho do arquivo de manifesto JSON é de 10 MB. Se você tiver muitos arquivos para fazer upload,
considere maneiras de reduzir o número de caracteres necessários para descrever o conjunto de dados. Por exemplo,
use o campo uriPrefix para eliminar
a necessidade de fornecer o caminho do bucket do Google Cloud para cada URI na
lista uris. Se for necessário reduzir ainda mais o tamanho, tente encurtar os nomes dos arquivos.
Formato do arquivo de imagem
Cada arquivo de imagem precisa ser uma imagem TIFF. Se o CRS não for especificado no manifesto, o arquivo precisará ser um GeoTIFF com um CRS incorporado.
Os arquivos TIFF podem ser compactados com DEFLATE, JPEG-XL/JXL, LERC, LERC_DEFLATE, LERC_ZSTD, LZMA, LZW, WEBP ou ZSTD.
Recomendações para melhorar a experiência de upload de arquivos grandes:
- Melhor opção: o ZSTD oferece um bom equilíbrio entre velocidade e compactação.
- Evite: o LZMA pode ser muito lento, apesar da boa compactação.
- Arquivos descompactados: resultam em arquivos maiores e tempos de upload mais longos.
- Compactação com perda (por exemplo, JPEG): pode alterar os valores de pixel. Use compactação sem perdas (por exemplo, DEFLATE, LZMA, LZW, ZSTD), a menos que você entenda o impacto potencial nos seus dados.