objutils 0.10.16__tar.gz → 0.10.17__tar.gz

{objutils-0.10.16 → objutils-0.10.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: objutils
-Version: 0.10.16
+Version: 0.10.17
 Summary: Objectfile library for Python
 Keywords: hex files,intel hex,s19,srec,srecords,object files,map files,embedded,microcontroller,ECU,shf,rfc4194
 Author-Email: Christoph Schueler <cpu12.gems@googlemail.com>

{objutils-0.10.16 → objutils-0.10.17}/docs/howto.rst

@@ -75,6 +75,82 @@ Read/write ASAM values (incl. word-swap byte orders)
    img.write_asam_string(0x3010, "MOTOR", "ASCII")
    name = img.read_asam_string(0x3010, "ASCII")
 
+Read/write ASAM strings with encoding override
+----------------------------------------------
+
+Some ECUs store Latin-1 (or other non-UTF-8) characters in a field that is
+declared ``ASCII`` in the A2L description.  Use the ``encoding`` keyword to
+override the codec without changing the ASAM dtype name:
+
+.. code-block:: python
+
+   from objutils import Image, Section
+
+   img = Image([Section(0x4000, bytes(64))])
+
+   # The string contains "Ü" (0xDC in Latin-1) – would fail with plain ASCII
+   img.write_asam_string(0x4000, "MOTOR_ÜBERDREHZAHL", "ASCII", encoding="latin-1")
+   name = img.read_asam_string(0x4000, "ASCII", encoding="latin-1")
+   # name == 'MOTOR_ÜBERDREHZAHL'
+
+The ``encoding`` parameter is accepted by both ``read_asam_string`` and
+``write_asam_string`` on ``Section`` as well as ``Image``.
+
+Read/write ASAM characteristic maps with ALTERNATE_WITH_X
+---------------------------------------------------------
+
+``ALTERNATE_WITH_X`` stores each X-column preceded by its X-axis coordinate:
+``[x[0], f(0,0), f(0,1), …, x[1], f(1,0), f(1,1), …]``.
+
+.. code-block:: python
+
+   import numpy as np
+   from objutils import Image, Section
+
+   # ASAM shape (X=3, Y=4) → numpy shape (4, 3)
+   matrix = np.array(
+       [[11, 21, 31],
+        [12, 22, 32],
+        [13, 23, 33],
+        [14, 24, 34]],
+       dtype=np.uint8,
+   )
+   x_axis = np.array([10, 20, 30], dtype=np.uint8)
+
+   total = 3 * (1 + 4)   # num_x * (axis_byte + num_y * element_byte)
+   img = Image([Section(0x8000, bytes(total + 8))])
+
+   img.write_asam_ndarray(0x8000, matrix, "UBYTE", "MSB_LAST",
+                          index_mode="ALTERNATE_WITH_X", x_axis=x_axis)
+
+   result = img.read_asam_ndarray(0x8000, 0, "UBYTE",
+                                  shape=(3, 4), byte_order="MSB_LAST",
+                                  index_mode="ALTERNATE_WITH_X")
+   # result.values  →  matrix
+   # result.axis    →  x_axis
+
+Read/write ASAM characteristic maps with ALTERNATE_WITH_Y
+---------------------------------------------------------
+
+``ALTERNATE_WITH_Y`` stores each Y-row preceded by its Y-axis coordinate:
+``[y[0], f(0,0), f(1,0), …, y[1], f(0,1), f(1,1), …]``.
+
+.. code-block:: python
+
+   y_axis = np.array([1, 2, 3, 4], dtype=np.uint8)
+
+   total_y = 4 * (1 + 3)   # num_y * (axis_byte + num_x * element_byte)
+   img2 = Image([Section(0x9000, bytes(total_y + 8))])
+
+   img2.write_asam_ndarray(0x9000, matrix, "UBYTE", "MSB_LAST",
+                           index_mode="ALTERNATE_WITH_Y", y_axis=y_axis)
+
+   result2 = img2.read_asam_ndarray(0x9000, 0, "UBYTE",
+                                    shape=(3, 4), byte_order="MSB_LAST",
+                                    index_mode="ALTERNATE_WITH_Y")
+   # result2.values  →  matrix
+   # result2.axis    →  y_axis
+
 Extract loadable image from ELF
 -------------------------------
 

{objutils-0.10.16 → objutils-0.10.17}/docs/session.rst

@@ -163,6 +163,15 @@ ASAM strings
     >>> img.read_asam_string(0x3020, "UTF8")
     'Drehzahl'
 
+When an ECU stores non-ASCII characters in a nominally ASCII field, override
+the codec with an explicit ``encoding`` keyword argument:
+
+.. code-block:: python
+
+    >>> img.write_asam_string(0x3030, "MOTOR_ÜBERDREHZAHL", "ASCII", encoding="latin-1")
+    >>> img.read_asam_string(0x3030, "ASCII", encoding="latin-1")
+    'MOTOR_ÜBERDREHZAHL'
+
 ASAM numeric arrays
 -------------------
 
@@ -202,6 +211,65 @@ ASAM ndarrays (NumPy)
     >>> np.array_equal(matrix_rt, matrix)
     True
 
+ASAM ndarrays — ALTERNATE_WITH_X / ALTERNATE_WITH_Y
+----------------------------------------------------
+
+For characteristic maps (2-D) the ``ALTERNATE_WITH_X`` and ``ALTERNATE_WITH_Y``
+index modes interleave axis coordinate values with the function values in memory.
+
+**ALTERNATE_WITH_X** — each X-column is preceded by its X-axis coordinate:
+
+.. code-block:: python
+
+    >>> import numpy as np
+    >>> from objutils import Image, Section
+
+    >>> # Value matrix numpy shape (Y=2, X=3); ASAM shape (X=3, Y=2)
+    >>> vals = np.array([[11, 21, 31], [12, 22, 32]], dtype=np.uint8)
+    >>> x_ax = np.array([10, 20, 30], dtype=np.uint8)
+
+    >>> total = 3 * (1 + 2)   # num_x * (axis_byte + num_y)
+    >>> img = Image([Section(0xA000, bytes(total + 8))])
+    >>> img.write_asam_ndarray(0xA000, vals, "UBYTE", "MSB_LAST",
+    ...                        index_mode="ALTERNATE_WITH_X", x_axis=x_ax)
+
+    >>> # Raw memory: [10, 11, 12,  20, 21, 22,  30, 31, 32]
+    >>> list(img.read(0xA000, total))
+    [10, 11, 12, 20, 21, 22, 30, 31, 32]
+
+    >>> result = img.read_asam_ndarray(0xA000, 0, "UBYTE",
+    ...                                shape=(3, 2), byte_order="MSB_LAST",
+    ...                                index_mode="ALTERNATE_WITH_X")
+    >>> np.array_equal(result.values, vals)
+    True
+    >>> np.array_equal(result.axis, x_ax)
+    True
+
+**ALTERNATE_WITH_Y** — each Y-row is preceded by its Y-axis coordinate:
+
+.. code-block:: python
+
+    >>> y_ax = np.array([100, 200], dtype=np.uint8)
+
+    >>> total_y = 2 * (1 + 3)   # num_y * (axis_byte + num_x)
+    >>> img2 = Image([Section(0xB000, bytes(total_y + 8))])
+    >>> img2.write_asam_ndarray(0xB000, vals, "UBYTE", "MSB_LAST",
+    ...                         index_mode="ALTERNATE_WITH_Y", y_axis=y_ax)
+
+    >>> # Raw memory: [100, 11, 21, 31,  200, 12, 22, 32]
+    >>> list(img2.read(0xB000, total_y))
+    [100, 11, 21, 31, 200, 12, 22, 32]
+
+    >>> result2 = img2.read_asam_ndarray(0xB000, 0, "UBYTE",
+    ...                                  shape=(3, 2), byte_order="MSB_LAST",
+    ...                                  index_mode="ALTERNATE_WITH_Y")
+    >>> np.array_equal(result2.values, vals)
+    True
+
+``read_asam_ndarray`` returns an ``AlternateArrayResult`` named tuple for
+these modes.  Access the parts via ``result.values`` / ``result.axis``, or
+unpack: ``values, axis = result``.
+
 What next?
 ----------
 

{objutils-0.10.16 → objutils-0.10.17}/docs/tutorial.rst

@@ -178,13 +178,35 @@ side by side in one small image.
 - ``UTF16``
 - ``UTF32``
 
+.. rubric:: Encoding override for ASAM strings
+
+When an ECU stores text that cannot be decoded with the default ASAM mapping
+(for example Latin-1 characters in a nominally ASCII field), pass an explicit
+``encoding`` keyword argument to override:
+
+.. code-block:: python
+
+   from objutils import Image, Section
+
+   img = Image([Section(0x4000, bytes(64))])
+
+   # Write a string that contains a non-ASCII character (Ü = 0xDC in Latin-1)
+   img.write_asam_string(0x4000, "MOTOR_ÜBERDREHZAHL", "ASCII", encoding="latin-1")
+
+   # Read it back with the same override
+   text = img.read_asam_string(0x4000, "ASCII", encoding="latin-1")
+   # text == 'MOTOR_ÜBERDREHZAHL'
+
+Without ``encoding=...`` the codec is derived from *dtype* as usual
+(``ASCII`` → ``"ascii"``, ``UTF8`` → ``"utf-8"``, …).
+
 .. rubric:: ASAM Array Cheat Sheet
 
 Quick reference for the ASAM array helpers on ``Image`` and ``Section``.
 
 .. list-table::
    :header-rows: 1
-   :widths: 30 18 22 20
+   :widths: 30 18 28 20
 
    * - Method
      - ``length`` semantics
@@ -198,10 +220,14 @@ Quick reference for the ASAM array helpers on ``Image`` and ``Section``.
      - n/a (from ``len(data)``)
      - ``None``
      - scalar lists/tuples
-   * - ``read_asam_ndarray(...)``
+   * - ``read_asam_ndarray(...)`` ROW_DIR / COLUMN_DIR
      - element count
      - ``numpy.ndarray``
      - matrix/tensor data
+   * - ``read_asam_ndarray(...)`` ALTERNATE_WITH_X/Y
+     - ignored (derived from shape)
+     - ``AlternateArrayResult(values, axis)``
+     - interleaved axis+value maps
    * - ``write_asam_ndarray(...)``
      - n/a (from ``array.nbytes``)
      - ``None``
@@ -217,13 +243,77 @@ Quick reference for the ASAM array helpers on ``Image`` and ``Section``.
 .. note::
    **ASAM index modes**
 
-   ``index_mode="ROW_DIR"`` (default) uses C-like row-major layout
-   where X increments fastest.  ``index_mode="COLUMN_DIR"`` swaps only
-   X and Y (not true Fortran-order for dims > 2).
+   +------------------------+---------------------------------------------------+
+   | ``index_mode``         | Memory layout                                     |
+   +========================+===================================================+
+   | ``ROW_DIR`` (default)  | C-order row-major; X increments fastest           |
+   +------------------------+---------------------------------------------------+
+   | ``COLUMN_DIR``         | X and Y swapped; not true Fortran for dims > 2    |
+   +------------------------+---------------------------------------------------+
+   | ``ALTERNATE_WITH_X``   | 2-D maps only: each X-column preceded by its      |
+   |                        | X-axis coordinate value in memory                 |
+   +------------------------+---------------------------------------------------+
+   | ``ALTERNATE_WITH_Y``   | 2-D maps only: each Y-row preceded by its Y-axis  |
+   |                        | coordinate value in memory                        |
+   +------------------------+---------------------------------------------------+
+
+   For ``ALTERNATE_WITH_X`` / ``ALTERNATE_WITH_Y``:
+
+   - Pass axis values with ``x_axis=<array>`` or ``y_axis=<array>`` to
+     ``write_asam_ndarray``.
+   - ``read_asam_ndarray`` returns an ``AlternateArrayResult(values, axis)``
+     named tuple; unpack with ``values, axis = result`` or access as
+     ``result.values`` / ``result.axis``.
+   - The ``length`` parameter of ``read_asam_ndarray`` is ignored for these
+     modes; the byte count is derived from ``shape``.
+
+   ``shape`` always uses **ASAM convention** ``(X, Y, Z, …)`` – reversed
+   compared to numpy ``(…, Z, Y, X)``.
+
+.. rubric:: ALTERNATE_WITH_X example (map, 5 columns × 4 rows)
+
+.. code-block:: python
+
+   import numpy as np
+   from objutils import Image, Section
+
+   # Value matrix: shape (4, 5) in numpy  =  ASAM shape (X=5, Y=4)
+   matrix = np.array(
+       [[11, 21, 31, 41, 51],
+        [12, 22, 32, 42, 52],
+        [13, 23, 33, 43, 53],
+        [14, 24, 34, 44, 54]],
+       dtype=np.uint8,
+   )
+   x_axis = np.array([10, 20, 30, 40, 50], dtype=np.uint8)
+
+   # Memory: x[0]=10, col0=[11,12,13,14], x[1]=20, col1=[21,22,23,24], …
+   img = Image([Section(0x8000, bytes(5 * (1 + 4) + 16))])
+   img.write_asam_ndarray(0x8000, matrix, "UBYTE", "MSB_LAST",
+                          index_mode="ALTERNATE_WITH_X", x_axis=x_axis)
+
+   result = img.read_asam_ndarray(0x8000, 0, "UBYTE",
+                                  shape=(5, 4), byte_order="MSB_LAST",
+                                  index_mode="ALTERNATE_WITH_X")
+   assert np.array_equal(result.values, matrix)
+   assert np.array_equal(result.axis, x_axis)
+
+.. rubric:: ALTERNATE_WITH_Y example (map, 5 columns × 4 rows)
+
+.. code-block:: python
+
+   y_axis = np.array([1, 2, 3, 4], dtype=np.uint8)
+
+   # Memory: y[0]=1, row0=[11,21,31,41,51], y[1]=2, row1=[12,22,32,42,52], …
+   img2 = Image([Section(0x9000, bytes(4 * (1 + 5) + 16))])
+   img2.write_asam_ndarray(0x9000, matrix, "UBYTE", "MSB_LAST",
+                           index_mode="ALTERNATE_WITH_Y", y_axis=y_axis)
 
-   ``shape`` uses **ASAM convention** ``(X, Y, Z, …)`` which is reversed
-   compared to numpy ``(…, Z, Y, X)``.  ``length`` is the **element count**,
-   not byte count.
+   result2 = img2.read_asam_ndarray(0x9000, 0, "UBYTE",
+                                    shape=(5, 4), byte_order="MSB_LAST",
+                                    index_mode="ALTERNATE_WITH_Y")
+   assert np.array_equal(result2.values, matrix)
+   assert np.array_equal(result2.axis, y_axis)
 
 .. warning::
    **Frequent pitfalls**
@@ -232,6 +322,8 @@ Quick reference for the ASAM array helpers on ``Image`` and ``Section``.
    - Forgetting that byte order is applied per element, not per full buffer.
    - Passing unsupported ASAM dtype names (must be values like ``UWORD``/``ULONG``).
    - Assuming MSW swapping affects 8-bit types (it does not).
+   - Using ``ALTERNATE_WITH_X`` / ``ALTERNATE_WITH_Y`` with a 1-D array or
+     without a 2-D ``shape`` parameter.
 
 .. rubric:: Copy/paste example: ULONG array roundtrip
 

{objutils-0.10.16 → objutils-0.10.17}/objutils/__init__.py

@@ -13,7 +13,7 @@ Registers CODECS and implements an interface to them.
 The first parameter is always the codec name.
 """
 
-__version__ = "0.10.16"
+__version__ = "0.10.17"
 
 __all__ = [
     "Image",

{objutils-0.10.16 → objutils-0.10.17}/objutils/image.py

@@ -798,11 +798,29 @@ class Image:
 
         Args:
             addr: Absolute memory address to write to.
-            array: NumPy ndarray (shape in numpy convention).
-            dtype: ASAM datatype name.
-            byte_order: ASAM byte order string.
-            index_mode: ``"ROW_DIR"`` (default) or ``"COLUMN_DIR"``.
-            **kws: Passed through to section method.
+            array: NumPy ndarray (shape in numpy convention, i.e. rows × columns).
+            dtype: ASAM datatype name (e.g. ``"UWORD"``, ``"ULONG"``).
+            byte_order: ASAM byte order string (e.g. ``"MSB_FIRST"``, ``"MSB_LAST"``).
+            index_mode: Memory layout mode:
+
+                - ``"ROW_DIR"`` (default) – C-order row-major; X increments fastest.
+                - ``"COLUMN_DIR"`` – X and Y swapped; not true Fortran-order for
+                  dims > 2.
+                - ``"ALTERNATE_WITH_X"`` – 2-D maps only; each X-column is preceded
+                  by its X-axis coordinate value.  Pass axis values via
+                  ``x_axis=<array>`` in *kws*.
+                - ``"ALTERNATE_WITH_Y"`` – 2-D maps only; each Y-row is preceded by
+                  its Y-axis coordinate value.  Pass axis values via
+                  ``y_axis=<array>`` in *kws*.
+            **kws: Keyword arguments passed through to the section method.
+                Relevant for ALTERNATE modes:
+
+                - ``x_axis`` (array-like): X-axis coordinate values for
+                  ``ALTERNATE_WITH_X``.
+                - ``y_axis`` (array-like): Y-axis coordinate values for
+                  ``ALTERNATE_WITH_Y``.
+                - ``axis_dtype`` (str): ASAM datatype for axis values (defaults
+                  to the same as *dtype*).
         """
         self._call_address_function("write_asam_ndarray", addr, array, dtype, byte_order, index_mode=index_mode, **kws)
 
@@ -847,15 +865,36 @@ class Image:
 
         Args:
             addr: Start address to read from.
-            length: Number of **elements** (not bytes).
-            dtype: ASAM datatype name.
-            shape: Dimensions in **ASAM** order ``(X, Y, Z, ...)``.
-            byte_order: ASAM byte order string.
-            index_mode: ``"ROW_DIR"`` (default) or ``"COLUMN_DIR"``.
-            **kws: Passed through to section method.
+            length: Number of **elements** (not bytes).  Ignored for
+                ``ALTERNATE_WITH_X`` and ``ALTERNATE_WITH_Y`` – the byte count
+                is derived from *shape* in those modes.
+            dtype: ASAM datatype name (e.g. ``"UWORD"``, ``"ULONG"``).
+            shape: Dimensions in **ASAM** order ``(X, Y, Z, ...)``, which is
+                the reverse of numpy order ``(..., Z, Y, X)``.
+                **Required** for ``ALTERNATE_WITH_X`` and ``ALTERNATE_WITH_Y``.
+            byte_order: ASAM byte order string (e.g. ``"MSB_FIRST"``, ``"MSB_LAST"``).
+            index_mode: Memory layout mode:
+
+                - ``"ROW_DIR"`` (default) – C-order row-major; X increments fastest.
+                - ``"COLUMN_DIR"`` – X and Y swapped; not true Fortran-order for
+                  dims > 2.
+                - ``"ALTERNATE_WITH_X"`` – 2-D maps only; each X-column is preceded
+                  by its X-axis coordinate value in memory.
+                - ``"ALTERNATE_WITH_Y"`` – 2-D maps only; each Y-row is preceded by
+                  its Y-axis coordinate value in memory.
+            **kws: Keyword arguments passed through to the section method.
+                Relevant for ALTERNATE modes:
+
+                - ``axis_dtype`` (str): ASAM datatype for axis values (defaults
+                  to the same as *dtype*).
 
         Returns:
-            NumPy ndarray with shape in numpy convention.
+            - ``numpy.ndarray`` with shape in numpy convention for ``ROW_DIR``
+              and ``COLUMN_DIR``.
+            - :class:`~objutils.section.AlternateArrayResult` ``(values, axis)``
+              named tuple for ``ALTERNATE_WITH_X`` and ``ALTERNATE_WITH_Y``.
+              Access via ``result.values`` / ``result.axis`` or unpack:
+              ``values, axis = result``.
         """
         return self._call_address_function(
             "read_asam_ndarray", addr, length, dtype, shape=shape, byte_order=byte_order, index_mode=index_mode, **kws