# Task I/O
WARNING
App Engine and its Task system are still in BETA. Therefore, all information presented in this documentation is subject to potentially breaking changes.
Tasks receive their inputs and write their outputs as files and directories within the Task container, specifically in an input folder (e.g., /inputs) and an output folder (e.g., /outputs). This section provides unified specifications for these files and directories, guiding developers on how to read inputs and write outputs.
# Table of content
# Generalities
At the start of the Task container, input parameters are accessible as files and directories within the /inputs folder, ready for the Task to read. This location can be changed by specifying a different path in configuration.input_folder in the descriptor.
During execution, the Task must write all outputs as files or directories in the /outputs folder. Similar to inputs, this default output location can be modified by specifying an alternative path in configuration.output_folder in the descriptor. Files or directories placed outside this designated folder will be disregarded by the App Engine and not recognized as outputs. Should an output parameter file or directory be absent, or if its structure deviates from the specified requirements, the Task will be considered failed.
The structure of the files or directories for each parameter must comply with the specifications detailed below, which vary based on the parameter's type. Inputs and outputs share the same structure, with the only difference being the location of the files and directories within the /inputs and /outputs folders, respectively.
For both inputs and outputs, the naming of each file or directory must align with its respective parameter identifier as defined in the descriptor file, without incorporating any extra characters or spaces.
In the examples below, <EOF> represents the end of the file.
# boolean
Boolean values are represented as a single file containing either true or false. The file should not contain any additional characters or spaces.
Examples:
# integer
Number values are represented as a single file containing a single integer value. The file should not contain any additional characters or spaces. For example:
VALUE<EOF>
where VALUE is an integer number in base 2 (prefix 0b), 8 (prefix 0), 10 (no prefix) or 16 (prefix 0x). More formally VALUE must match the following regex:
[-+]?0b[0-1_]+ # (base 2)
|[-+]?0[0-7_]+ # (base 8)
|[-+]?(0|[1-9][0-9_]*) # (base 10)
|[-+]?0x[0-9a-fA-F_]+ # (base 16)
2
3
4
Example values:
42-1037359316460b11011110101011011100101011111110(binary)0xDEADCAFE(base 16)033653345376(base 8)
# number
Number values are represented as a single file containing a single floating point value. The file should not contain any additional characters or spaces. For example:
VALUE<EOF>
where VALUE is a floating point number in decimal or scientific notation or one of the special values for infinity or not-a-number. More formally VALUE must match the following regex:
[-+]?([0-9][0-9]*)?\.[0-9.]*([eE][-+][0-9]+)?
|[-+]?(inf|Inf|INF)
|(nan|NaN|NAN)
2
3
Example values:
685230.156.8523015e+5685.23015e+03-infNaN
# string
String values are represented as a single file containing a single or multi-line string UTF8 encoded value. For example:
STRING_VALUE<EOF>
Examples:
# geometry
A geometry is represented as a single JSON file containing one valid GeoJSON object. The supported GeoJSON subtypes are comprehensively listed below:
Point(opens new window)MultiPoint(opens new window)LineString(opens new window)MultiLineString(opens new window)Polygon(opens new window)MultiPolygon(opens new window)Circle(opens new window) (as a GeoJSON feature)Rectangle(opens new window) (as a GeoJSON feature)- GeoJson
Feature(opens new window): the feature's geometry must only include one of the supported plain geometries (Point,MultiPoint,LineString,MultiLineString,Polygon,MultiPolygon). Features properties will not be interpreted nor validated by the App Engine (except forRectangleandCircle) but will be conserved if present.
Because this type targets individual or plain geometries, we deliberately exclude the following GeoJSON subtypes:
The coordinate system used to encode positions is a simple 2D cartesian coordinate system. Because we are not dealing with a latitude-longitude system, we can ignore the antimeridian cutting specification (opens new window) in GeoJSON.
When the geometry is derived from an image parameter (see outputs.{PARAM}.dependencies.derived_from), the origin of the cartesian coordinate system must be located at the top left corner of the image.
Examples:
References:
# image
Image files are provided in the input folder as such, only their original name (as it was when the image file was uploaded) has been replaced with the parameter name (and extension has been removed).
Only supported formats are png, jpeg and tiff (RGB planar), see Task descriptor reference for further restrictions of the supported image formats for an image parameter.
# array
An array parameter is represented by a directory containing comprising several files:
- a YAML file named
array.yml, which contains metadata about the array (e.g. its size). - an individual files for each element in the array, named based on the element's index within the array. The encoding of each file matches that of its specific subtype (for instance, a text file for simple types or a directory for complex collections).
For instance, for an input with this specification:
my_array:
# ...
type:
id: array
subtype: integer
2
3
4
5
and my_array is [4, 1, -1]. Then the parameter would be encoded as
my_array/
├── array.yml
├── 0 # txt file
├── 1 # txt file
└── 2 # txt file
2
3
4
5
where files have the following content:
If allow_missing is true, then missing collection items have their file absent and, therefore, index skipped.