Object-oriented asset file system#
Set up environment#
Install all the required libs if necessary and perform the import statements upstream.
# uncomment if installation of libs is necessary
# !pip install earthengine-api geetools
import ee
import geetools #noqa: F401
# uncomment if authetication to GEE is needed
# ee.Authenticate()
# uncomment if initialization is required
# ee.Initialize()
The Asset object#
In Google Earth Engine API, users are working with Assets. An asset is a filelike object that englobes a wide variety of types: IMAGE, IMAGE_COLLECTION, FOLDER, TABLE, FEATURE_COLLECTION, etc.
They are identified by a unique ID, which is a string that looks like: projects/username/assets/foo. Using the vanila Earthengine API, They can be modified using the ee.data module. This module has been proven complicated when dealing with basic file manipulation operation such as listing, moving, copying, etc.
geetools provides a simple way to manage assets as an object-oriented filesystem paths using the Asset object. This object is a subclass of the pathlib.Path object, which is a powerful way to manage file paths in Python. Most of the methods and properties are overwritten to work with the Google Earth Engine context.
ee.Asset objects implement the os.PathLike interface, allowing them to be used anywhere the interface is accepted.
Basic use#
Importing the main class:
import ee, geetools
Create asset objects#
The Asset objects etend the pathlib.Path object and thus behave exactly the same when dealing with constructor. THe only differnece is that asset path only supports posix-like file separator: /.
ee.Asset("projects/ee-geetools/assets/documentation/image1")
ee.Asset('projects/ee-geetools/assets/documentation/image1')
Each element of pathsegments can be either a string representing a path segment, or an object implementing the os.PathLike interface where the fspath() method returns a string, such as another path object.
ee.Asset("projects", "ee-geetools", "assets", "documentation", "image1")
ee.Asset('projects/ee-geetools/assets/documentation/image1')
ee.Asset("projects/ee-geetools/assets/documentation") / "image1"
ee.Asset('projects/ee-geetools/assets/documentation/image1')
ee.Asset("projects/ee-geetools/assets/documentation").joinpath("image1")
ee.Asset('projects/ee-geetools/assets/documentation/image1')
Listing subdirectories#
# a public folder created for this docuemntation
folder = ee.Asset("projects/ee-geetools/assets/documentation")
# list all its direct subdirectories
[a for a in folder.iterdir() if a.is_folder()]
[ee.Asset('projects/ee-geetools/assets/documentation/subfolder1'),
ee.Asset('projects/ee-geetools/assets/documentation/subfolder2'),
ee.Asset('projects/ee-geetools/assets/documentation/subfolder3')]
See API
ee.Asset.iterdir: Get the list of children of a container.{
ee.Asset.is_folder: Return ``True`` if the asset is a folder.
Listing Image in this folder#
[a for a in folder.iterdir() if a.is_image()]
[ee.Asset('projects/ee-geetools/assets/documentation/image0'),
ee.Asset('projects/ee-geetools/assets/documentation/image1'),
ee.Asset('projects/ee-geetools/assets/documentation/image2'),
ee.Asset('projects/ee-geetools/assets/documentation/image3'),
ee.Asset('projects/ee-geetools/assets/documentation/image4')]
[a for a in folder.glob("**/image*")]
[ee.Asset('projects/ee-geetools/assets/documentation/image0'),
ee.Asset('projects/ee-geetools/assets/documentation/image1'),
ee.Asset('projects/ee-geetools/assets/documentation/image2'),
ee.Asset('projects/ee-geetools/assets/documentation/image3'),
ee.Asset('projects/ee-geetools/assets/documentation/image4')]
See API
ee.Asset.iterdir: Get the list of children of a container.ee.Asset.glob: Return a list of assets matching the pattern.ee.Asset.is_image: Return ``True`` if the asset is an image.
Querying asset properties#
folder.exists()
True
fakeImage = folder / "image6"
fakeImage.exists()
False
See API
ee.Asset.exists: Return True if the asset exists and/or the user has access to it.
General properties#
Paths are immutable and hashable. Paths of a same flavour are comparable and orderable. These properties respect the flavour’s case-folding semantics:
folder = ee.Asset("projects/ee-geetools/assets/documentation")
folder == ee.Asset("projects/ee-geetools/assets/DOCUMENTATION")
False
folder in { ee.Asset("projects/ee-geetools/assets/documentation")}
True
The slash operator helps create child asset, like os.path.join(). If the argument is an absolute asset, the previous path is ignored.
ee.Asset("projects/ee-geetools/assets/documentation") / "image1"
ee.Asset('projects/ee-geetools/assets/documentation/image1')
An asset object can be used anywhere an object implementing os.PathLike is accepted.
import os
a = ee.Asset("projects/ee-geetools/assets/documentation")
os.fspath(a)
'projects/ee-geetools/assets/documentation'
The string representation of an asset is the asset id itself, which you can pass to any function taking an asset id as a string:
a = ee.Asset("projects/ee-geetools/assets/documentation/image1")
str(a)
'projects/ee-geetools/assets/documentation/image1'
Accessing individual parts#
To access the individual “parts” (components) of a path, use the following property:
a = ee.Asset("projects/ee-geetools/assets/documentation/image1")
a.parts
('projects', 'ee-geetools', 'assets', 'documentation', 'image1')
See API
ee.Asset.parts not found
access parent container#
Asset parent containers can be access either by the parent property or the parents property. Note This is a purely lexical operation and the parent is not checked to exist.
See API
ee.Asset.parent not found
ee.Asset.parents not found
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.parent
ee.Asset('projects/ee-geetools/assets/documentation/subfolder1')
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.parents
[ee.Asset('projects/ee-geetools/assets/documentation/subfolder1'),
ee.Asset('projects/ee-geetools/assets/documentation')]
Name of the asset#
A string representing the final path component can be used to get the name of the asset.add
See API
ee.Asset.name not found
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.name
'image1'
General Methods#
Pure paths provide the following methods.
evaluate relation between assets#
It’s possible to check if files are related between one another using the following methods:
See API
ee.Asset.is_relative_to: Return True if the asset is relative to another asset.
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
b = ee.Asset("projects/ee-geetools/assets/documentation")
a.is_relative_to(b)
True
create a siblings#
One can create a siblings asset in the same container by using the with_name() method:
See API
ee.Asset.with_name: Return the asset with the given name.
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.with_name("image2")
ee.Asset('projects/ee-geetools/assets/documentation/subfolder1/image2')
resolve unix like symbols#
One can use some unix-like descriptors in it’s Asset constructor parameters. If so before using the Asset object, it is necessary to resolve these symbols. The method expanduser does that.
See API
expanduser:ee.Asset.expanduser: Return a new path with expanded ~ constructs.
a = ee.Asset("~/documentation/subfolder1/image1")
a.expanduser()
ee.Asset('projects/None/assets/documentation/subfolder1/image1')
check existence#
One can check if an asset exists using the exists method:
See API
exists:ee.Asset.exists: Return True if the asset exists and/or the user has access to it.
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.exists()
True
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image10")
a.exists()
False
Evaluate asset type#
As Earth Engine is not using any file extention to differentiate the asset type, one can use the is_type method with any of the following types: IMAGE, IMAGE_COLLECTION, FOLDER, TABLE, FEATURE_COLLECTION, UNKNOWN.
See API
is_type:ee.Asset.is_type: Return ``True`` if the asset is of the specified type.
a = ee.Asset("projects/ee-geetools/assets/documentation/subfolder1/image1")
a.is_type("IMAGE")
True
All type checks are available in dedicated wrapped methods like is_image, is_folder, is_table …etc.
a.is_image()
True
Many other useful methods are available and are described in the API documentation.