jgdtrans.transformer module

jgdtrans.transformer module#

Provides Transformer etc.

class jgdtrans.transformer.Transformer(data: ParameterSet)#

Bases: object

The coordinate Transformer, and represents a deserializing result of par file.

If the parameters is zero, such as the unsupported components, the transformations are identity transformation on such components. For example, the transformation by the TKY2JGD and the PatchJGD par is identity transformation on altitude, and by the PatchJGD(H) par is so on latitude and longitude.

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )

Forward transformation

>>> tf.forward(36.10377479, 140.087855041, 2.34)
Point(latitude=36.103773017086695, longitude=140.08785924333452, altitude=2.4363138578103)

Backward transformation

>>> tf.backward(36.103773017086695, 140.08785924333452, 2.4363138578103)
Point(latitude=36.10377479, longitude=140.087855041, altitude=2.34)

Backward transformation compatible to GIAJ web app/APIs

>>> tf.backward_compat(36.103773017086695, 140.08785924333452, 2.4363138578103)
Point(latitude=36.10377479000002, longitude=140.087855041, altitude=2.339999999578243)

data: ParameterSet#

MAX_ERROR: ClassVar[float] = 5e-14#: Max error of Transformer.backward() and Transformer.backward_corr().

classmethod from_dict(obj: _types.ParDataLikeMappingType) → Self#

Makes a Transformer obj from Mapping obj.

This parses meshcode, the key of parameter, into int.

See FormatType for detail of 'PatchJGD_HV'.

Parameters:: obj – the Mapping of the format, the parameters, and the description (optional)
Returns:: the Transformer obj
Raises:: DeserializeError – when fail to parse the meshcode

Examples

>>> mapping = {
...     'format': 'SemiDynaEXE',
...     'parameter': {
...         12345678: {
...             'latitude': 0.1,
...             'longitude': 0.2,
...             'altitude': 0.3,
...         },
...         ...
...     },
...     'description': 'important my param',  # optional
... }
>>> tf = Transformer.from_dict(mapping)
>>> tf.data
ParData(
    format='SemiDynaEXE',
    parameter={
        12345678: Parameter('latitude': 0.1, 'longitude': 0.2, 'altitude': 0.3),
        ...
    },
    description='important my param'
)

>>> mapping = {
...     'format': 'SemiDynaEXE',
...     'parameter': {
...         '12345678': {
...             'latitude': 0.1,
...             'longitude': 0.2,
...             'altitude': 0.3,
...         },
...         ...
...     },
... }
>>> tf = Transformer.from_dict(mapping)
>>> tf.data
ParData(
    format='SemiDynaEXE',
    parameter={
        12345678: Parameter('latitude': 0.1, 'longitude': 0.2, 'altitude': 0.3),
        ...
    },
    description='important my param'
)

transform(latitude: float, longitude: float, altitude: float = 0.0, backward: bool = False) → Point#

Returns the transformed position.

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.00333… <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0
altitude – the altitude [m] of the point
backward – when True, this performs backward transformation

Returns:

the transformed point

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
ValueError – when latitude or longitude is unsupported value

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=Pardata(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.transform(36.10377479, 140.087855041, 2.34, backward=False)
Point(latitude=36.103773017086695, longitude=140.08785924333452, altitude=2.4363138578103)
>>> tf.transform(
...     36.103773017086695, 140.08785924333452, 2.4363138578102994, backward=True
... )
Point(latitude=36.10377479, longitude=140.087855041, altitude=2.34)

Following identities hold:

>>> tf.transform(*point, backward=False) == tf.forward(*point)
True
>>> tf.transform(*point, backward=True) == tf.backward(*point)
True

forward(latitude: float, longitude: float, altitude: float = 0.0) → Point#

Returns the forward-transformed position.

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.0 <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0
altitude – the altitude [m] of the point

Returns:

the transformed point

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.forward(36.10377479, 140.087855041, 2.34)
Point(latitude=36.103773017086695, longitude=140.08785924333452, altitude=2.4363138578103)

backward_compat(latitude: float, longitude: float, altitude: float = 0.0) → Point#

Returns the backward-transformed position compatible to GIAJ web app/APIs.

This is compatible to GIAJ web app/APIs, and is not exact as the original as.

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.00333… <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0
altitude – the altitude [m] of the point

Returns:

the transformed point

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

Notes, the exact solution is Point(36.10377479, 140.087855041, 2.34).

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.backward_compat(36.103773017086695, 140.08785924333452, 2.4363138578103)
Point(latitude=36.10377479000002, longitude=140.087855041, altitude=2.339999999578243)

backward(latitude: float, longitude: float, altitude: float = 0.0)#

Returns the backward-transformed position.

The result’s error from an exact solution is suppressed under Transformer::ERROR_MAX.

Notes, the error is less than 1e-9 deg, which is error of GIAJ latitude and longitude parameter. This implies that altitude’s error is (practically) less than 1e-5 [m], which is error of the GIAJ altitude parameter.

Notes, this is not compatible to GIAJ web app/APIs (but more accurate).

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.0 <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0
altitude – the altitude [m] of the point

Returns:

the transformed point

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
CorrectionNotFoundError – when the error from the exact solution is larger than Transformer.ERROR_MAX.
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

Notes, the exact solution is Point(36.10377479, 140.087855041, 2.34). In this case, no error remains.

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.backward(36.103773017086695, 140.08785924333452, 2.4363138578103)
Point(latitude=36.10377479, longitude=140.087855041, altitude=2.34)

forward_corr(latitude: float, longitude: float) → Correction#

Return the correction on forward-transformation.

Used by Transformer.forward().

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.0 <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0

Returns:

the correction on forward transformation

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.forward_corr(36.10377479, 140.087855041)
Correction(latitude=-1.7729133100878255e-06, longitude=4.202334510058886e-06, altitude=0.09631385781030007)

backward_compat_corr(latitude: float, longitude: float) → Correction#

Return the correction on backward-transformation compatible to GIAJ web app/APIs.

Used by Transformer.backward_compat().

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.00333… <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0

Returns:

the correction on backward transformation

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.backward_compat_corr(36.103773017086695, 140.08785924333452)
Correction(latitude=1.7729133219831587e-06, longitude=-4.202334509042613e-06, altitude=-0.0963138582320569)

backward_corr(latitude: float, longitude: float) → Correction#

Return the correction on backward-transformation.

Used by Transformer.backward().

Parameters:

latitude – the latitude [deg] of the point which satisfies 0.0 <= and <= 66.666…
longitude – the longitude [deg] of the point which satisfies 100.0 <= and <= 180.0

Returns:

the correction on backward transformation

Raises:

ParameterNotFoundError – when latitude and longitude points to an area where the parameter does not support
CorrectionNotFoundError – when verification failed
PointOutOfBoundsError – when latitude or longitude is out-of-bounds

Examples

From SemiDynaEXE2023.par

>>> tf = Transformer(
...     data=ParData(
...         format="SemiDynaEXE",
...         parameter={
...             54401005: Parameter(-0.00622, 0.01516, 0.0946),
...             54401055: Parameter(-0.0062, 0.01529, 0.08972),
...             54401100: Parameter(-0.00663, 0.01492, 0.10374),
...             54401150: Parameter(-0.00664, 0.01506, 0.10087),
...         },
...     )
... )
>>> tf.backward_corr(36.103773017086695, 140.08785924333452)
Correction(latitude=1.7729133100878255e-06, longitude=-4.202334510058886e-06, altitude=-0.09631385781030007)

class jgdtrans.transformer.Correction(latitude: float, longitude: float, altitude: float)#

Bases: NamedTuple

The transformation correction.

latitude: float#: The latitude correction [deg].

longitude: float#: The longitude correction [deg].

altitude: float#: The altitude correction [m].

property horizontal: float#: \(\sqrt{\text{latitude}^2 + \text{longitude}^2}\) [deg].

class jgdtrans.transformer.ParameterSet(*args, **kwargs)#

Bases: Protocol

Interface for Transformer.

get(meshcode: int) → Parameter | None#: Returns Parameter associated with meshcode, otherwise None.

mesh_unit() → Literal[1, 5]#: Returns a mesh unit.

jgdtrans.transformer.load(fp: TextIO, format: _types.FormatType, *, description: str | None = None) → Transformer#

Deserialize a par-formatted file-like obj into a Transformer.

This fills by 0.0 for altituse parameter when 'TKY2JGD' or 'PatchJGD' given to format, and for latitude and longitude when 'PatchJGD_H' or 'HyokoRev' given.

See FormatType for detail of 'PatchJGD_HV'.

Parameters:

fp – a par-formatted file-like obj
format – the format of fp
description – the description of the parameter, defaulting the fp header

Returns:

the Transformer obj

Raises:

ParseParFileError – when invalid data found

Examples

>>> with open("SemiDyna2023.par") as fp:
...     tf = load(fp, format="SemiDynaEXE")
>>> result = tf.transform(35.0, 145.0)

>>> s = '''<15 lines>
... MeshCode dB(sec)  dL(sec) dH(m)
... 12345678   0.00001   0.00002   0.00003'''
>>> with io.StringIO(s) as fp:
...     tf = load(fp, format="SemiDynaEXE")
Parameter(latitude=0.00001, longitude=0.0002, altitude=0.0003)

jgdtrans.transformer.loads(s: str, format: _types.FormatType, *, description: str | None = None) → Transformer#

Deserialize a par-formatted str into a Transformer.

This fills by 0.0 for altituse parameter when 'TKY2JGD' or 'PatchJGD' given to format, and for latitude and longitude when 'PatchJGD_H' or 'HyokoRev' given.

See FormatType for detail of 'PatchJGD_HV'.

Parameters:

s – a par-formatted text
format – the format of s
description – the description of the parameter, defaulting the s header

Returns:

the Transformer obj

Raises:

ParseParFileError – when invalid data found

Examples

>>> s = '''<15 lines>
... MeshCode dB(sec)  dL(sec) dH(m)
... 12345678   0.00001   0.00002   0.00003'''
>>> tf = loads(s, format="SemiDynaEXE")
>>> result = tf.transform(35.0, 145.0)

>>> s = '''<15 lines>
... MeshCode dB(sec)  dL(sec) dH(m)
... 12345678   0.00001   0.00002   0.00003'''
>>> loads(s, format="SemiDynaEXE").parameter[12345678]
Parameter(latitude=0.00001, longitude=0.0002, altitude=0.0003)

jgdtrans.transformer.from_dict(obj) → Transformer#

Makes a Transformer obj from Mapping obj.

This parses meshcode, the key of parameter, into int.

See FormatType for detail of 'PatchJGD_HV'.

Parameters:: obj – the Mapping of the format, the parameters, and the description (optional)
Returns:: the Transformer obj
Raises:: DeserializeError – when fail to parse the meshcode

Examples

>>> mapping = {
...     'format': 'SemiDynaEXE',
...     'parameter': {
...         12345678: {
...             'latitude': 0.1,
...             'longitude': 0.2,
...             'altitude': 0.3,
...         },
...         ...
...     },
...     'description': 'important my param',  # optional
... }
>>> tf = from_dict(mapping)
>>> tf.data
ParData(
    format='SemiDynaEXE',
    parameter={
        12345678: Parameter('latitude': 0.1, 'longitude': 0.2, 'altitude': 0.3),
        ...
    },
    description='important my param'
)

>>> mapping = {
...     'format': 'SemiDynaEXE',
...     'parameter': {
...         '12345678': {
...             'latitude': 0.1,
...             'longitude': 0.2,
...             'altitude': 0.3,
...         },
...         ...
...     },
... }
>>> tf = from_dict(mapping)
>>> tf.data
ParData(
    format='SemiDynaEXE',
    parameter={
        12345678: Parameter('latitude': 0.1, 'longitude': 0.2, 'altitude': 0.3),
        ...
    },
    description=None
)

jgdtrans.transformer module

Contents

jgdtrans.transformer module#