Commit a0a1a8a3 authored by Julien Osman's avatar Julien Osman
Browse files

DOC: Add the list of available keys in pyhton api documentation.

parent 3ed2a118
Pipeline #9203 failed with stages
in 192 minutes and 13 seconds
......@@ -118,6 +118,15 @@ add_custom_target(generate_otbapps_rst
DEPENDS OTBSWIGWrapper-all
)
add_custom_target(generate_pythonapy_rst
COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/Scripts/otbGeneratePythonApiRstDoc.py
${RST_BINARY_DIR}
WORKING_DIRECTORY ${RST_BINARY_DIR}
COMMENT "Auto-generating Python Api Documentation in RST"
DEPENDS OTBSWIGWrapper-all
)
add_custom_target(generate_examples_rst
COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/Scripts/otbGenerateExamplesRstDoc.py
${RST_BINARY_DIR}
......@@ -144,6 +153,7 @@ add_custom_target(CookBookHTML
-c ${SPHINX_CONF_DIR}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS generate_otbapps_rst
DEPENDS generate_pythonapy_rst
DEPENDS generate_examples_rst
COMMENT "Building RST documentation in html")
......
import argparse
import otbApplication
def format_key_list(keys_str):
"""
Format the key list
:param keys_str: a string containing the keys separated by spaces
:return: a string containing the keys ordered and separated by a coma and a space
"""
key_list = keys_str.split(" ")
key_list.sort()
return ", ".join(key_list)
def GenerateRstForPythonAPi(rst_dir):
" Generate the .rst file for the PythonAPI page"
print("Generating rst for Python API")
# Instenciate an ImageMetadata object to retrieve the keys
imd = otbApplication.ImageMetadata()
# Render the page
output_python_api = template_python_api.format(
key_list_double=format_key_list(imd.GetKeyListNum()),
key_list_string=format_key_list(imd.GetKeyListStr()),
key_list_l1d=format_key_list(imd.GetKeyListL1D()),
# key_list_l2d=format_key_list(imd.GetKeyListL2D()),
key_list_time=format_key_list(imd.GetKeyListTime())
)
# Write the page
with open(rst_dir + '/PythonAPI.rst', 'w',encoding='utf-8') as new_rst_file:
new_rst_file.write(output_python_api)
if __name__ == "__main__":
parser = argparse.ArgumentParser(usage="Export the PythonAPI doc page to rst file")
parser.add_argument("rst_dir", help="Directory where rst files are generated")
args = parser.parse_args()
# Load rst template
template_python_api = open("templates/PythonAPI.rst").read()
GenerateRstForPythonAPi(args.rst_dir)
......@@ -106,7 +106,7 @@ functions *SetParameters()* and *GetParameters()*.
.. code-block:: python
params = {"in":"myInput.tif", "type.mean.radius":4}
params = {{"in":"myInput.tif", "type.mean.radius":4}}
app.SetParameters(params)
params2 = app.GetParameters()
......@@ -374,26 +374,61 @@ The Python dictionary used has the following entries:
* ``'spacing'``: signed spacing of the image
* ``'size'``: full size of the image
* ``'region'``: region of the image present in the buffer
* ``'metadata'``: metadata dictionary (contains projection, sensor model,...)
* ``'metadata'``: metadata dictionary (contains projection,...)
The metadata dictionary contains various type of data. Here are the available keys of the dictionnary, ordered by type:
* double:
{key_list_double}
* string:
{key_list_string}
* LUT 1D:
{key_list_l1d}
* time object:
{key_list_time}
This dictionary also contains metadata related to projection and
sensor model. The coresponding keys are not accessible at the
moment. But the dictionary offers a few extra methods:
* ``GetProjectedGeometry()`` returns a string representing the
projection. It can be a WKN, an EPSG or a PROJ string.
* ``GetProjectionWKT()`` returns a string representing the projection
as a WKT.
* ``GetProjectionProj()`` returns a string representing the projection
as a PROJ string.
Now some basic Q&A about this interface:
Q: What portion of the image is exported to Numpy array?
A: By default, the whole image is exported. If you had a non-empty requested
region (the result of calling PropagateRequestedRegion()), then this region
is exported.
* **What portion of the image is exported to Numpy array?**
By default, the whole image is exported. If you had a non-empty
requested region (the result of calling
PropagateRequestedRegion()), then this region is exported.
Q: What is the difference between ImportImage and ImportVectorImage?
A: The first one is here for Applications that expect a monoband otb::Image.
In most cases, you will use the second one: ImportVectorImage.
* **What is the difference between ImportImage and ImportVectorImage?**
Q: What kind of objects are there in this dictionary export?
A: The array is a numpy.ndarray. The other fields are wrapped
objects from the OTB library but you can interact with them in a
Python way: they support ``len()`` and ``str()`` operator, as well as
bracket operator ``[]``. Some of them also have a ``keys()`` function just like
dictionaries.
The first one is here for Applications that expect a monoband
otb::Image. In most cases, you will use the second one:
ImportVectorImage.
* **What kind of objects are there in this dictionary export?**
The array is a numpy.ndarray. The other fields are wrapped objects
from the OTB library but you can interact with them in a Python
way: they support ``len()`` and ``str()`` operator, as well as
bracket operator ``[]``. Some of them also have a ``keys()``
function just like dictionaries.
This interface allows you to export OTB images (or extracts) to Numpy array,
process them by other means, and re-import them with preserved metadata. Please
note that this is different from an in-memory connection.
......
......@@ -145,6 +145,9 @@ public:
/** Test if a key is available */
bool Has(const MDNum& key) const;
/** Return the list of valid keys */
std::string GetKeyListNum() const;
// -------------------- String utility function ----------------------------
......@@ -159,6 +162,9 @@ public:
/** Test if a key is available */
bool Has(const MDStr& key) const;
/** Return the list of valid keys */
std::string GetKeyListStr() const;
// -------------------- LUT1D utility function ----------------------------
......@@ -173,6 +179,9 @@ public:
/** Test if a key is available */
bool Has(const MDL1D& key) const;
/** Return the list of valid keys */
std::string GetKeyListL1D() const;
// -------------------- 2D LUT utility function ----------------------------
......@@ -187,6 +196,9 @@ public:
/** Test if a key is available */
bool Has(const MDL2D& key) const;
/** Return the list of valid keys */
// std::string GetKeyListL2D() const;
// -------------------- Time utility function ----------------------------
......@@ -202,6 +214,9 @@ public:
/** Test if a key is available */
bool Has(const MDTime& key) const;
/** Return the list of valid keys */
std::string GetKeyListTime() const;
// -------------------- Extra keys utility function --------------------------
/** Read-only accessor to extra keys */
......
......@@ -166,6 +166,16 @@ bool ImageMetadataBase::Has(const MDNum& key) const
return (NumericKeys.find(key) != NumericKeys.end());
}
std::string ImageMetadataBase::GetKeyListNum() const
{
std::ostringstream oss;
for (const auto& kv : MetaData::MDNumNames.left)
oss << kv.second << " ";
auto returnString = oss.str();
returnString.pop_back();
return returnString;
}
// -------------------- String utility function ----------------------------
const std::string & ImageMetadataBase::operator[](const MDStr& key) const
......@@ -188,6 +198,16 @@ bool ImageMetadataBase::Has(const MDStr& key) const
return (StringKeys.find(key) != StringKeys.end());
}
std::string ImageMetadataBase::GetKeyListStr() const
{
std::ostringstream oss;
for (const auto& kv : MetaData::MDStrNames.left)
oss << kv.second << " ";
auto returnString = oss.str();
returnString.pop_back();
return returnString;
}
// -------------------- LUT1D utility function ----------------------------
const MetaData::LUT1D & ImageMetadataBase::operator[](const MDL1D& key) const
......@@ -210,6 +230,16 @@ bool ImageMetadataBase::Has(const MDL1D& key) const
return (LUT1DKeys.find(key) != LUT1DKeys.end());
}
std::string ImageMetadataBase::GetKeyListL1D() const
{
std::ostringstream oss;
for (const auto& kv : MetaData::MDL1DNames.left)
oss << kv.second << " ";
auto returnString = oss.str();
returnString.pop_back();
return returnString;
}
// -------------------- 2D LUT utility function ----------------------------
const MetaData::LUT2D & ImageMetadataBase::operator[](const MDL2D& key) const
......@@ -232,6 +262,16 @@ bool ImageMetadataBase::Has(const MDL2D& key) const
return (LUT2DKeys.find(key) != LUT2DKeys.end());
}
//std::string ImageMetadataBase::GetKeyListL2D() const
//{
// std::ostringstream oss;
// for (const auto& kv : MetaData::MDL2DNames.left)
// oss << kv.second << " ";
// auto returnString = oss.str();
// returnString.pop_back();
// return returnString;
//}
// -------------------- Time utility function ----------------------------
const MetaData::Time & ImageMetadataBase::operator[](const MDTime& key) const
......@@ -254,6 +294,16 @@ bool ImageMetadataBase::Has(const MDTime& key) const
return (TimeKeys.find(key) != TimeKeys.end());
}
std::string ImageMetadataBase::GetKeyListTime() const
{
std::ostringstream oss;
for (const auto& kv : MetaData::MDTimeNames.left)
oss << kv.second << " ";
auto returnString = oss.str();
returnString.pop_back();
return returnString;
}
// -------------------- Extra keys utility function --------------------------
const std::string & ImageMetadataBase::operator[](const std::string & key) const
......
......@@ -84,6 +84,12 @@ public:
std::string GetProjectedGeometry() const;
std::string GetProjectionWKT() const;
std::string GetProjectionProj() const;
std::string GetKeyListNum() const;
std::string GetKeyListStr() const;
std::string GetKeyListL1D() const;
// std::string GetKeyListL2D() const;
std::string GetKeyListTime() const;
};
class ImageMetadata: public ImageMetadataBase
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment