readme (#8)

Author: valentin-gauthier-geosiris

energyml-utils/README.md

@@ -27,3 +27,52 @@ or with poetry:
 ```console
 poetry add energyml-utils
 ```
+
+
+Features
+--------
+
+### Supported packages versions
+
+This package supports read/write in xml/json the following packages : 
+- EML (common) : 2.0, 2.1, 2.2, 2.3
+- RESQML : 2.0.1, 2.2dev3, 2.2
+- WITSMl : 2.0, 2.1
+- PRODML : 2.0, 2.2
+
+/!\\ By default, these package are not installed and are published independently.
+You can install only the versions you need by adding the following lines in the .toml file : 
+```toml
+energyml-common2-0 = "^1.12.0"
+energyml-common2-1 = "^1.12.0"
+energyml-common2-2 = "^1.12.0"
+energyml-common2-3 = "^1.12.0"
+energyml-resqml2-0-1 = "^1.12.0"
+energyml-resqml2-2-dev3 = "^1.12.0"
+energyml-resqml2-2 = "^1.12.0"
+energyml-witsml2-0 = "^1.12.0"
+energyml-witsml2-1 = "^1.12.0"
+energyml-prodml2-0 = "^1.12.0"
+energyml-prodml2-2 = "^1.12.0"
+```
+
+### Content of the package :
+
+- Support EPC + h5 read and write
+  - *.rels* files are automatically generated, but it is possible to add custom Relations.
+  - You can add "raw files" such as PDF or anything else, in your EPC instance, and it will be package with other files in the ".epc" file when you call the "export" function.
+  - You can work with local files, but also with IO (BytesIO). This is usefull to work with cloud application to avoid local storage.
+- Supports xml / json read and write (for energyml objects)
+- *Work in progress* : Supports the read of 3D data inside the "AbstractMesh" class (and sub-classes "PointSetMesh", "PolylineSetMesh", "SurfaceMesh"). This gives you a instance containing a list of point and a list of indices to easily re-create a 3D representation of the data.
+  -  These "mesh" classes provides *.obj*, *.off*, and *.geojson* export.
+- Introspection : This package includes functions to ease the access of specific values inside energyml objects.
+  - Functions to access to UUID, object Version, and more generic functions for any other attributes with regex like ".Citation.Title" or "Cit\\.*.Title" (regular dots are used as in python object attribute access. To use dot in regex, you must escape them with a '\\')
+  - Functions to parse, or generate from an energyml object the "ContentType" or "QualifiedType"
+  - Generation of random data : you can generate random values for a specific energyml object. For example, you can generate a WITSML Tubular object with random values in it.
+- Objects correctness validation :
+  - You can verify if your objects are valid following the energyml norm (a check is done on regex contraint attributes, maxCount, minCount, mandatory etc...)
+  - The DOR validation is tested : check if the DOR has correct information (title, ContentType/QualifiedType, object version), and also if the referenced object exists in the context of the EPC instance (or a list of object).
+- Abstractions done to ease use with *ETP* (Energistics Transfer Protocol) :
+  - The "EnergymlWorkspace" class allows to abstract the access of numerical data like "ExternalArrays". This class can thus be extended to interact with ETP "GetDataArray" request etc...
+- ETP URI support : the "Uri" class allows to parse/write an etp uri.
+

energyml-utils/example/main.py

@@ -15,6 +15,7 @@
 )
 
 from src.energyml.utils.data.hdf import *
+from src.energyml.utils.data.helper import get_projected_uom
 from src.energyml.utils.epc import *
 from src.energyml.utils.introspection import *
 from src.energyml.utils.manager import *
@@ -440,6 +441,18 @@ def test_local_depth_crs():
         print(e)
 
 
+def test_get_projected_uom():
+    # Fails because the xsi:type="VerticalCrsEpsgCode" doesn't
+    # contain the namespace : xsi:type="eml:VerticalCrsEpsgCode"
+    try:
+        depth3d = read_energyml_xml_file(
+            "../rc/obj_LocalDepth3dCrs_716f6472-18a3-4f19-a57c-d4f5642ccc53.xml"
+        )
+        print(get_projected_uom(depth3d).value)
+    except Exception as e:
+        print(e)
+
+
 def test_wellbore_marker_frame_representation():
     # Fails because the xsi:type="VerticalCrsEpsgCode" doesn't
     # contain the namespace : xsi:type="eml:VerticalCrsEpsgCode"
@@ -517,19 +530,20 @@ def class_field():
 
 
 if __name__ == "__main__":
-    tests_0()
-    tests_content_type()
-
-    tests_epc()
-    tests_dor()
-    test_verif()
-    test_ast()
-    test_introspection()
-
-    tests_hdf()
-    test_local_depth_crs()
-    test_wellbore_marker_frame_representation()
-
-    test_obj_attribs()
-    test_copy_values()
-    class_field()
+    # tests_0()
+    # tests_content_type()
+    #
+    # tests_epc()
+    # tests_dor()
+    # test_verif()
+    # test_ast()
+    # test_introspection()
+    #
+    # tests_hdf()
+    # test_local_depth_crs()
+    # test_wellbore_marker_frame_representation()
+    #
+    # test_obj_attribs()
+    # test_copy_values()
+    # class_field()
+    test_get_projected_uom()

energyml-utils/src/energyml/utils/data/helper.py

@@ -96,14 +96,14 @@ def is_z_reversed(crs: Optional[Any]) -> bool:
 
 
 def get_vertical_epsg_code(crs_object: Any):
-    projected_epsg_code = None
+    vertical_epsg_code = None
     if crs_object is not None:  # LocalDepth3dCRS
-        projected_epsg_code = get_object_attribute_rgx(crs_object, "VerticalCrs.EpsgCode")
-        if projected_epsg_code is None:  # LocalEngineering2DCrs
-            projected_epsg_code = get_object_attribute_rgx(
+        vertical_epsg_code = get_object_attribute_rgx(crs_object, "VerticalCrs.EpsgCode")
+        if vertical_epsg_code is None:  # LocalEngineering2DCrs
+            vertical_epsg_code = get_object_attribute_rgx(
                 crs_object, "OriginProjectedCrs.AbstractProjectedCrs.EpsgCode"
             )
-    return projected_epsg_code
+    return vertical_epsg_code
 
 
 def get_projected_epsg_code(crs_object: Any, workspace: Optional[EnergymlWorkspace] = None):
@@ -124,15 +124,15 @@ def get_projected_epsg_code(crs_object: Any, workspace: Optional[EnergymlWorkspa
 
 def get_projected_uom(crs_object: Any, workspace: Optional[EnergymlWorkspace] = None):
     if crs_object is not None:
-        projected_epsg_code = get_object_attribute_rgx(crs_object, "ProjectedUom")
-        if projected_epsg_code is None:
-            projected_epsg_code = get_object_attribute_rgx(crs_object, "HorizontalAxes.ProjectedUom")
+        projected_epsg_uom = get_object_attribute_rgx(crs_object, "ProjectedUom")
+        if projected_epsg_uom is None:
+            projected_epsg_uom = get_object_attribute_rgx(crs_object, "HorizontalAxes.ProjectedUom")
 
-        if projected_epsg_code is None and workspace is not None:
+        if projected_epsg_uom is None and workspace is not None:
             return get_projected_uom(
                 workspace.get_object_by_uuid(get_object_attribute_rgx(crs_object, "LocalEngineering2[dD]Crs.Uuid"))
             )
-        return projected_epsg_code
+        return projected_epsg_uom
     return None
 
 

energyml-utils/src/energyml/utils/introspection.py

@@ -602,7 +602,7 @@ def search_attribute_matching_name_with_path(
 ) -> List[Tuple[str, Any]]:
     """
     Returns a list of tuple (path, value) for each sub attribute with type matching param "name_rgx".
-    The path is a dot-version like ".Citation.Title"
+        The path is a dot-version like ".Citation.Title"
     :param obj:
     :param name_rgx:
     :param re_flags: