Getting Started
Example TIF Files and Code
You can get example TIF files in a zip format and all code in the Getting Started page to convert TIF files to GeoTIFF and upload them into Ellipsis in our API.
To quickly Download the zip file, click HERE
If you dont know how to run a python code on your computer, you can use our google colab code. To check out the colab code click HERE
Setting Up Your Environment
first you need a python enviroment that have ellipsis and rasterio libraries. you can download them with
pip install rasterio==1.3.10
pip install ellipsis==3.1.45
Ellipsis Account
You need an Ellipsis account to get your USERNAME and PASSWORD. If you don't have an account, visit the Ellipsis Register page. If you already have an account but don’t know your USERNAME or PASSWORD, contact Ellipsis Support.
You also need ELLIPSIS_PARENTID. If you don’t have one, create a folder in your Ellipsis drive. Right-click in the drive page and select NEW FOLDER. After creating a folder, click the three dots on the right side of the folder and select INTEGRATE. The Path ID shown is your parent ID. Copy it and set it to ELLIPSIS_PARENTID.
Set your credentials:
Set ELLIPSIS_PARENTID with the Path Id you get in INTEGRATE page. As well as USERNAME and PASSWORD
ELLIPSIS_USERNAME = "ELLIPSIS_USERNAME" #change this with your ellipsis username
ELLIPSIS_PASSWORD = "ELLIPSIS_PASSWORD" #change this with your ellipsis password
ELLIPSIS_PARENTID = "ELLIPSIS_PARENTID" #change this with your ellipsis path id
Converting TIF Files to GeoTIFF
Before using the D4S API, convert TIF files into GeoTIFF format and upload them to Ellipsis as a raster. We create two functions: convert_tif_to_geotiff() and upload_tif_files_to_ellipsis() for these tasks.
Code Setup
Ensure the code is in the same path as the folder containing TIF files or update the paths accordingly.
First of all, we need to edit this variables. filename is just a string and can be change with anything you want. You can keep EPSG and FILE_FORMAT same if you dont sure what they are. root_dir is file path that contains TIF files (can have subfolders inside folder like folders with date of files inside datas folder). After running the function TIF files will converted into geotiff and stored in new_root_dir with same structure in root_dir. This example below is in folder called datas. And tif files inside folders with dates.
Update the following variables (only change filename and directory names if needed. keep EPSG and FILE_FORMAT same):
filename = "TestFile" #change this with a real raster name
EPSG = 4326
FILE_FORMAT = "tif"
root_dir = 'datas'
new_root_dir = 'processed_datas'
tiff_folder = new_root_dir
Converting TIFF Files to GeoTIFF
This function is used to convert tif files to geotiff. It will convert the tif files in given folder to geotiff and save them in the new folder.
If you have your own TIF files you need to update west (Minimum longitude), east (Maximum longitude), south (Minimum latitude) and north (Maximum latitude), if you are using demo samples we provide. You can keep them with default values.
def convert_tif_to_geotiff(west:float = 27.474279, east:float = 27.474347, south:float = 40.973221, north:float = 40.973268):
"""
This function is used to convert tif files to geotiff.
It will convert the tif files in given folder to geotiff and save them in the new folder
"""
crs = CRS.from_epsg(EPSG)
if not os.path.isdir(new_root_dir):
os.mkdir(new_root_dir)
def process_tif(file_path, output_path):
with rasterio.open(file_path) as src:
data = src.read()
transform = from_bounds(west, south, east, north, width=src.width, height=src.height)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with rasterio.open(
output_path, 'w',
driver='GTiff',
height=src.height,
width=src.width,
count=src.count,
dtype=src.dtypes[0],
crs=crs,
transform=transform
) as dst:
dst.write(data)
for dirpath, dirnames, filenames in os.walk(root_dir):
for filename in filenames:
if filename.endswith('.TIF'):
file_path = os.path.join(dirpath, filename)
relative_path = os.path.relpath(dirpath, root_dir)
output_dir = os.path.join(new_root_dir, relative_path)
output_file_path = os.path.join(output_dir, filename)
process_tif(file_path, output_file_path)
print(f"Processed {file_path} and exported to {output_file_path}")
You should see similar output like this:
Folders after function completion
Uploading GeoTIFF Files to Ellipsis
⚠️ Attention! After succesfull upload, Ellipsis need to activate the files. This activation sometimes took several minutes so check the status of your files in Ellipsis drive before try our API
After getting geotiff files in given new_root_dir you can now upload files with upload_tif_files_to_ellipsis(). This function will automatically upload files in new_root_dir. Just make sure code is in same path with new_root_dir base folder
Dont forget to update your metadata with previously given longitude and latitude values.
def upload_tif_files_to_ellipsis():
"""
This function is used to upload tif files to ellipsis.
It will upload the tif files from the given folder and create a raster layer in ellipsis
"""
token = el.account.logIn(ELLIPSIS_USERNAME, ELLIPSIS_PASSWORD)
metadata = {
"properties": {
"xMin": 27.474279, # Minimum longitude
"xMax": 27.474347, # Maximum longitude
"yMin": 40.973221, # Minimum latitude
"yMax": 40.973268 # Maximum latitude
}
}
rasterLayerId = el.path.raster.add(name=filename, token=token, parentId=ELLIPSIS_PARENTID, metadata=metadata)['id']
print("raster_pathId: {}".format(rasterLayerId))
timestamps = [_dir for _dir in os.listdir(tiff_folder) if os.path.isdir(os.path.join(tiff_folder,_dir))]
for _timestamp in timestamps:
timestampId = el.path.raster.timestamp.add(rasterLayerId, token,description=_timestamp)['id']
print("timestampId: {} for timestamp: {}".format(timestampId,_timestamp))
timestamp_dir = os.path.join(tiff_folder,_timestamp)
_tifs = [_dir for _dir in os.listdir(timestamp_dir) if _dir.endswith(".TIF")]
for tif in _tifs:
tif_path = os.path.join(timestamp_dir,tif)
_id = el.path.raster.timestamp.file.add(pathId=rasterLayerId,
timestampId=timestampId,
filePath=tif_path,
token=token,
fileFormat=FILE_FORMAT,
epsg=EPSG)
print("fileId: {} for tif: {} timestamp: {}".format(_id['id'],tif,timestampId))
el.path.raster.timestamp.activate(rasterLayerId, timestampId, token)
You should see similar output like this:
Step by step guide to use your output from upload_tif_files_to_ellipsis() and create your payload json
- Find raster_pathId:
Look for the line starting with raster_pathId.
Copy the value after the colon.
Paste this value into the "raster_pathId" field in your JSON.
- Find timestamp and timestampId:
Locate each timestampId entry. It will be followed by the corresponding timestamp.
Copy the timestampId value and the corresponding timestamp value. Paste these into the "timestampId" fields, respectively, in your JSON.
- Find fileId for each band:
Under each timestampId, locate the fileId values for the TIF files.
Identify which band each fileId corresponds to (Red, Green, Blue, RE, NIR).
Copy the fileId values and paste them into the corresponding "fileId" fields for each band in your JSON.
For preparing request parameters, you may fill related fields on empty_payload.json with using outputs of upload_tif_files_to_ellipsis(). For details please check the step images below.
Order of function output and payload might be different. Make sure you place correct Id's in correct fields
For "destination_pathId" you can create another folder like the one we create in previous chapter Ellipsis Account.
Example empty payload
If you are still confused about something like "access_token" in payload, check Understanding the disease_detection Endpoint inside our main documentation. You can press arrow named Previous on top right corner of your browser to go back and read.
{
"access_token": "ELLIPSIS_TOKEN",
"raster_pathId": "RASTER_PATH_ID",
"destination_pathId": "DESTINATION_PATH_ID",
"lat_min": MIN_LAT_FLOAT,
"lat_max": MAX_LAT_FLOAT,
"lon_min": MIN_LON_FLOAT,
"lon_max": MAX_LON_FLOAT,
"data": [
{
"timestamp": "2023-06-01",
"timestampId": "TIMESTAMP_ID",
"bands": [
{
"fileId": "RED_BAND_FILE_ID",
"band_info": "Red"
},
{
"fileId": "GREEN_BAND_FILE_ID",
"band_info": "Green"
},
{
"fileId": "BLUE_BAND_FILE_ID",
"band_info": "Blue"
},
{
"fileId": "RE_BAND_FILE_ID",
"band_info": "RE"
},
{
"fileId": "NIR_BAND_FILE_ID",
"band_info": "NIR"
}
]
},
{
"timestamp": "2023-07-20",
"timestampId": "TIMESTAMP_ID",
"bands": [
{
"fileId": "RED_BAND_FILE_ID",
"band_info": "Red"
},
{
"fileId": "GREEN_BAND_FILE_ID",
"band_info": "Green"
},
{
"fileId": "BLUE_BAND_FILE_ID",
"band_info": "Blue"
},
{
"fileId": "RE_BAND_FILE_ID",
"band_info": "RE"
},
{
"fileId": "NIR_BAND_FILE_ID",
"band_info": "NIR"
}
]
},
{
"timestamp": "2023-08-04",
"timestampId": "TIMESTAMP_ID",
"bands": [
{
"fileId": "RED_BAND_FILE_ID",
"band_info": "Red"
},
{
"fileId": "GREEN_BAND_FILE_ID",
"band_info": "Green"
},
{
"fileId": "BLUE_BAND_FILE_ID",
"band_info": "Blue"
},
{
"fileId": "RE_BAND_FILE_ID",
"band_info": "RE"
},
{
"fileId": "NIR_BAND_FILE_ID",
"band_info": "NIR"
}
]
},
{
"timestamp": "2023-08-20",
"timestampId": "TIMESTAMP_ID",
"bands": [
{
"fileId": "RED_BAND_FILE_ID",
"band_info": "Red"
},
{
"fileId": "GREEN_BAND_FILE_ID",
"band_info": "Green"
},
{
"fileId": "BLUE_BAND_FILE_ID",
"band_info": "Blue"
},
{
"fileId": "RE_BAND_FILE_ID",
"band_info": "RE"
},
{
"fileId": "NIR_BAND_FILE_ID",
"band_info": "NIR"
}
]
}
]
}
Combined Processing and Uploading
Use this function to run both conversion and upload functions sequentially:
def process_and_upload():
"""
This function is used to process and upload tif files to ellipsis.
"""
print("\n\n Converting geotiff processing Started \n\n")
west = 27.47427947 # Minimum longitude
east = 27.47434738 # Maximum longitude
south = 40.97322116 # Minimum latitude
north = 40.97326774 # Maximum latitude
convert_tif_to_geotiff(west, east, south, north)
print(" \n\n Converting geotiff processing Done")
print("\n\n\n\n Uploading Raster is starting \n\n")
upload_tif_files_to_ellipsis()
print(" \n\n Done")
Complete Code
Here a complete code to copy and paste into local python code
import os
import rasterio
from rasterio.transform import from_bounds
from rasterio.crs import CRS
import ellipsis as el
ELLIPSIS_USERNAME = "USERNAME" #change this with your ellipsis username
ELLIPSIS_PASSWORD = "PASSWORD" #change this with your ellipsis password
ELLIPSIS_PARENTID = "PARENTID" #change this with your ellipsis parent id
filename = "TestFile" #change this with a real raster name
EPSG = 4326
FILE_FORMAT = "tif"
root_dir = 'datas'
new_root_dir = 'processed_datas'
tiff_folder = new_root_dir
def process_and_upload():
"""
This function is used to process and upload tif files to ellipsis.
"""
print("\n\n Converting geotiff processing Started \n\n")
west = 27.47427947 # Minimum longitude
east = 27.47434738 # Maximum longitude
south = 40.97322116 # Minimum latitude
north = 40.97326774 # Maximum latitude
convert_tif_to_geotiff(west, east, south, north)
print(" \n\n Converting geotiff processing Done")
print("\n\n\n\n Uploading Raster is starting \n\n")
upload_tif_files_to_ellipsis()
print(" \n\n Done")
def upload_tif_files_to_ellipsis():
"""
This function is used to upload tif files to ellipsis.
It will upload the tif files from the given folder and create a raster layer in ellipsis
"""
token = el.account.logIn(ELLIPSIS_USERNAME, ELLIPSIS_PASSWORD)
metadata = {
"properties": {
"xMin": 27.474279, # Minimum longitude
"xMax": 27.474347, # Maximum longitude
"yMin": 40.973221, # Minimum latitude
"yMax": 40.973268 # Maximum latitude
}
}
rasterLayerId = el.path.raster.add(name=filename, token=token, parentId=ELLIPSIS_PARENTID, metadata=metadata)['id']
print("raster_pathId: {}".format(rasterLayerId))
timestamps = [_dir for _dir in os.listdir(tiff_folder) if os.path.isdir(os.path.join(tiff_folder,_dir))]
for _timestamp in timestamps:
timestampId = el.path.raster.timestamp.add(rasterLayerId, token,description=_timestamp)['id']
print("timestampId: {} for timestamp: {}".format(timestampId,_timestamp))
timestamp_dir = os.path.join(tiff_folder,_timestamp)
_tifs = [_dir for _dir in os.listdir(timestamp_dir) if _dir.endswith(".TIF")]
for tif in _tifs:
tif_path = os.path.join(timestamp_dir,tif)
_id = el.path.raster.timestamp.file.add(pathId=rasterLayerId,
timestampId=timestampId,
filePath=tif_path,
token=token,
fileFormat=FILE_FORMAT,
epsg=EPSG)
print("fileId: {} for tif: {} timestamp: {}".format(_id['id'],tif,timestampId))
el.path.raster.timestamp.activate(rasterLayerId, timestampId, token)
def convert_tif_to_geotiff(west:float = 27.474279, east:float = 27.474347, south:float = 40.973221, north:float = 40.973268):
"""
This function is used to convert tif files to geotiff.
It will convert the tif files in given folder to geotiff and save them in the new folder
"""
crs = CRS.from_epsg(EPSG)
if not os.path.isdir(new_root_dir):
os.mkdir(new_root_dir)
def process_tif(file_path, output_path):
with rasterio.open(file_path) as src:
data = src.read()
transform = from_bounds(west, south, east, north, width=src.width, height=src.height)
os.makedirs(os.path.dirname(output_path), exist_ok=True)
with rasterio.open(
output_path, 'w',
driver='GTiff',
height=src.height,
width=src.width,
count=src.count,
dtype=src.dtypes[0],
crs=crs,
transform=transform
) as dst:
dst.write(data)
for dirpath, dirnames, filenames in os.walk(root_dir):
for filename in filenames:
if filename.endswith('.TIF'):
file_path = os.path.join(dirpath, filename)
relative_path = os.path.relpath(dirpath, root_dir)
output_dir = os.path.join(new_root_dir, relative_path)
output_file_path = os.path.join(output_dir, filename)
process_tif(file_path, output_file_path)
print(f"Processed {file_path} and exported to {output_file_path}")
if __name__ == "__main__":
process_and_upload()