sth-analysis-tools 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. sth_analysis_tools/__init__.py +176 -0
  2. sth_analysis_tools/aas/__init__.py +53 -0
  3. sth_analysis_tools/aas/aas_mapping.yaml +192 -0
  4. sth_analysis_tools/aas/adapter.py +175 -0
  5. sth_analysis_tools/aas/mapping_engine.py +168 -0
  6. sth_analysis_tools/aas/model.py +192 -0
  7. sth_analysis_tools/aas/registry.py +85 -0
  8. sth_analysis_tools/aas/serializer.py +87 -0
  9. sth_analysis_tools/analytics/__init__.py +0 -0
  10. sth_analysis_tools/analytics/analyzer.py +1114 -0
  11. sth_analysis_tools/analytics/baseline_tracker.py +245 -0
  12. sth_analysis_tools/analytics/dataset_group.py +337 -0
  13. sth_analysis_tools/analytics/features.py +902 -0
  14. sth_analysis_tools/analytics/normalizer.py +326 -0
  15. sth_analysis_tools/analytics/pass_numbering.py +120 -0
  16. sth_analysis_tools/analytics/peak_solver.py +286 -0
  17. sth_analysis_tools/analytics/query_engine.py +245 -0
  18. sth_analysis_tools/analytics/rolling_evaluator.py +487 -0
  19. sth_analysis_tools/analytics/segmenter.py +604 -0
  20. sth_analysis_tools/analytics/tool_life.py +123 -0
  21. sth_analysis_tools/cli.py +1084 -0
  22. sth_analysis_tools/configs/cirp_paper_v9.yaml +101 -0
  23. sth_analysis_tools/core/__init__.py +33 -0
  24. sth_analysis_tools/core/config.py +823 -0
  25. sth_analysis_tools/core/exceptions.py +21 -0
  26. sth_analysis_tools/core/metadata_profile.py +233 -0
  27. sth_analysis_tools/core/metadata_schema.py +108 -0
  28. sth_analysis_tools/core/utils.py +115 -0
  29. sth_analysis_tools/dashboard/__init__.py +10 -0
  30. sth_analysis_tools/dashboard/app.py +1328 -0
  31. sth_analysis_tools/dashboard/components.py +1397 -0
  32. sth_analysis_tools/dashboard/data_service.py +644 -0
  33. sth_analysis_tools/io/__init__.py +0 -0
  34. sth_analysis_tools/io/dataset_handle.py +1063 -0
  35. sth_analysis_tools/io/loader.py +371 -0
  36. sth_analysis_tools/jupyter.py +80 -0
  37. sth_analysis_tools/visualization/__init__.py +49 -0
  38. sth_analysis_tools/visualization/interactive.py +641 -0
  39. sth_analysis_tools/visualization/reporter.py +568 -0
  40. sth_analysis_tools/visualization/visualizer.py +3326 -0
  41. sth_analysis_tools-0.2.0.dist-info/METADATA +559 -0
  42. sth_analysis_tools-0.2.0.dist-info/RECORD +46 -0
  43. sth_analysis_tools-0.2.0.dist-info/WHEEL +5 -0
  44. sth_analysis_tools-0.2.0.dist-info/entry_points.txt +3 -0
  45. sth_analysis_tools-0.2.0.dist-info/licenses/LICENSE +21 -0
  46. sth_analysis_tools-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,176 @@
1
+ """
2
+ Sensory Toolholder (STH) Normalization Algorithm
3
+ =================================================
4
+ A standardized, hardware-invariant signal processing library for CIRP sensory toolholders.
5
+ Harmonizes heterogeneous multi-partner accelerometer data by eliminating manufacturing zero-g
6
+ offsets and unmeasured thermal baseline drift through dense air-cut anchor tracking.
7
+
8
+ Developed by Institute of Production Engineering and Photonic Technologies (IFT), TU Wien.
9
+ """
10
+
11
+ __version__ = "0.2.0"
12
+ __author__ = "IFT - TU Wien"
13
+
14
+ from .analytics.analyzer import ToolAnalyzer
15
+ from .analytics.baseline_tracker import BaselineResult, track_baseline_anchors
16
+ from .analytics.dataset_group import DatasetGroup
17
+ from .analytics.features import FeatureSummary, compute_standard_fft, extract_cut_features
18
+ from .analytics.normalizer import (
19
+ NormalizedResult,
20
+ evaluate_dmsc_compliance,
21
+ has_been_normalized,
22
+ normalize_signal,
23
+ save_cut_metrics_hdf5,
24
+ save_normalized_hdf5,
25
+ )
26
+ from .analytics.peak_solver import (
27
+ HarmonicsConfig,
28
+ ToothPeakResult,
29
+ compensate_modulation,
30
+ extract_chatter_envelope,
31
+ extract_rotational_sine_modulation,
32
+ fit_kinematic_tooth_peaks,
33
+ )
34
+ from .analytics.rolling_evaluator import (
35
+ RollingEvalConfig,
36
+ compute_rolling_cut_features,
37
+ compute_rolling_stft_features,
38
+ compute_spectrogram_waterfall,
39
+ extract_tool_last_n_cuts_rolling,
40
+ )
41
+ from .analytics.segmenter import MachiningRegimes, SegmentationConfig, segment_machining_regimes
42
+ from .core.config import (
43
+ CutExclusionRule,
44
+ ExclusionRule,
45
+ STHConfig,
46
+ check_cut_exclusion,
47
+ get_config,
48
+ get_default_paths,
49
+ get_exclusion_rules,
50
+ load_yaml_config,
51
+ should_exclude_dataset,
52
+ )
53
+ from .core.exceptions import DependencyError
54
+ from .core.metadata_profile import build_metadata_query, evaluate_jsonpath_expression, resolve_metadata_field
55
+ from .core.utils import process_sth_file
56
+ from .io.dataset_handle import STHDatasetHandle
57
+ from .io.loader import (
58
+ STHDataset,
59
+ audit_ble_packet_drops,
60
+ load_sth_dataset,
61
+ load_sth_metadata,
62
+ reconstruct_physical_time,
63
+ )
64
+ from .visualization.interactive import (
65
+ HAS_INTERACTIVE_DEPS,
66
+ ExplorerConfig,
67
+ InteractiveCutExplorer,
68
+ InteractiveSTHExplorer,
69
+ MinMaxDecimator,
70
+ render_consortium_overview,
71
+ render_cut_explorer_figure,
72
+ render_summary_table,
73
+ )
74
+ from .visualization.reporter import generate_normalization_report, generate_tool_wear_report
75
+ from .visualization.visualizer import (
76
+ STHColorTheme,
77
+ compute_min_max_envelope,
78
+ get_color_palette,
79
+ render_3panel_compensation_figure,
80
+ render_3panel_harmonization_figure,
81
+ render_compensation_pipeline_grid,
82
+ render_cut_full_plot,
83
+ render_cut_window_plot,
84
+ render_harmonics_figure,
85
+ render_harmonics_figure_for_partner,
86
+ render_last_n_cuts_rolling_wear_plot,
87
+ render_normalization_diagnostics,
88
+ render_partner_harmonics_bulk,
89
+ render_segmentation_diagnostic,
90
+ render_wear_progression_plots,
91
+ )
92
+
93
+ try:
94
+ from .dashboard import DashboardDataService, create_app, run_dashboard
95
+ except ImportError: # dash is optional: pip install "sth-analysis-tools[dashboard]"
96
+
97
+ def _dashboard_missing(*args, **kwargs):
98
+ raise DependencyError('The dashboard needs dash: pip install "sth-analysis-tools[dashboard]"')
99
+
100
+ create_app = run_dashboard = DashboardDataService = _dashboard_missing
101
+
102
+ __all__ = [
103
+ "HAS_INTERACTIVE_DEPS",
104
+ "BaselineResult",
105
+ "CutExclusionRule",
106
+ "DashboardDataService",
107
+ "DatasetGroup",
108
+ "DependencyError",
109
+ "ExclusionRule",
110
+ "ExplorerConfig",
111
+ "FeatureSummary",
112
+ "HarmonicsConfig",
113
+ "InteractiveCutExplorer",
114
+ "InteractiveSTHExplorer",
115
+ "MachiningRegimes",
116
+ "MinMaxDecimator",
117
+ "NormalizedResult",
118
+ "RollingEvalConfig",
119
+ "STHColorTheme",
120
+ "STHConfig",
121
+ "STHDataset",
122
+ "STHDatasetHandle",
123
+ "SegmentationConfig",
124
+ "ToolAnalyzer",
125
+ "ToothPeakResult",
126
+ "audit_ble_packet_drops",
127
+ "build_metadata_query",
128
+ "check_cut_exclusion",
129
+ "compensate_modulation",
130
+ "compute_min_max_envelope",
131
+ "compute_rolling_cut_features",
132
+ "compute_rolling_stft_features",
133
+ "compute_spectrogram_waterfall",
134
+ "compute_standard_fft",
135
+ "create_app",
136
+ "evaluate_dmsc_compliance",
137
+ "evaluate_jsonpath_expression",
138
+ "extract_chatter_envelope",
139
+ "extract_cut_features",
140
+ "extract_rotational_sine_modulation",
141
+ "extract_tool_last_n_cuts_rolling",
142
+ "fit_kinematic_tooth_peaks",
143
+ "generate_normalization_report",
144
+ "generate_tool_wear_report",
145
+ "get_color_palette",
146
+ "get_config",
147
+ "get_default_paths",
148
+ "get_exclusion_rules",
149
+ "has_been_normalized",
150
+ "load_sth_dataset",
151
+ "load_sth_metadata",
152
+ "load_yaml_config",
153
+ "normalize_signal",
154
+ "process_sth_file",
155
+ "reconstruct_physical_time",
156
+ "render_3panel_compensation_figure",
157
+ "render_3panel_harmonization_figure",
158
+ "render_compensation_pipeline_grid",
159
+ "render_consortium_overview",
160
+ "render_cut_explorer_figure",
161
+ "render_cut_full_plot",
162
+ "render_cut_window_plot",
163
+ "render_harmonics_figure_for_partner",
164
+ "render_last_n_cuts_rolling_wear_plot",
165
+ "render_normalization_diagnostics",
166
+ "render_segmentation_diagnostic",
167
+ "render_summary_table",
168
+ "render_wear_progression_plots",
169
+ "resolve_metadata_field",
170
+ "run_dashboard",
171
+ "save_cut_metrics_hdf5",
172
+ "save_normalized_hdf5",
173
+ "segment_machining_regimes",
174
+ "should_exclude_dataset",
175
+ "track_baseline_anchors",
176
+ ]
@@ -0,0 +1,53 @@
1
+ """
2
+ Asset Administration Shell (AAS / IEC 63278-1) Module
3
+ ======================================================
4
+ Provides zero-dependency Industry 4.0 Digital Twin generation, declarative
5
+ ECLASS/IDTA metadata mapping, and HDF5 telemetry linkage.
6
+ """
7
+
8
+ from .adapter import (
9
+ build_context_from_handle,
10
+ embed_aas_twin_in_handle,
11
+ export_aas_from_handle,
12
+ generate_aas_from_handle,
13
+ )
14
+ from .mapping_engine import (
15
+ DeclarativeSubmodelProvider,
16
+ load_declarative_mappings,
17
+ register_default_declarative_providers,
18
+ )
19
+ from .model import (
20
+ AssetAdministrationShell,
21
+ AssetInformation,
22
+ DataTypeDefXSD,
23
+ FileRef,
24
+ KeyTypes,
25
+ Property,
26
+ SemanticId,
27
+ Submodel,
28
+ )
29
+ from .registry import AASSubmodelRegistry, SubmodelProvider
30
+ from .serializer import save_aas_json, serialize_aas, validate_aas
31
+
32
+ __all__ = [
33
+ "AASSubmodelRegistry",
34
+ "AssetAdministrationShell",
35
+ "AssetInformation",
36
+ "DataTypeDefXSD",
37
+ "DeclarativeSubmodelProvider",
38
+ "FileRef",
39
+ "KeyTypes",
40
+ "Property",
41
+ "SemanticId",
42
+ "Submodel",
43
+ "SubmodelProvider",
44
+ "build_context_from_handle",
45
+ "embed_aas_twin_in_handle",
46
+ "export_aas_from_handle",
47
+ "generate_aas_from_handle",
48
+ "load_declarative_mappings",
49
+ "register_default_declarative_providers",
50
+ "save_aas_json",
51
+ "serialize_aas",
52
+ "validate_aas",
53
+ ]
@@ -0,0 +1,192 @@
1
+ # Standard Industry 4.0 AAS Submodel & ECLASS Semantic Mapping Specification
2
+ # =========================================================================
3
+ # Declarative, human-readable configuration mapping sensory toolholder metadata
4
+ # to standardized IEC 63278-1 Submodels (IDTA & ECLASS Release 14.0).
5
+ #
6
+ # Values are resolved dynamically via JSONPath on handle.metadata dictionaries
7
+ # or from dynamic runtime context (context_key).
8
+
9
+ submodels:
10
+ DigitalNameplate:
11
+ idShort: "Nameplate"
12
+ semanticId: "0173-1#01-AHF578#003"
13
+ description: "Digital Nameplate according to IDTA-02006-2-0"
14
+ properties:
15
+ ManufacturerName:
16
+ jsonpath: "$.pre.parameters.tool_manufacturer"
17
+ default: "botek Präzisionswerkzeuge"
18
+ semanticId: "0173-1#02-AAO677#002"
19
+ description: "Name of tool manufacturer"
20
+ ProductDesignation:
21
+ jsonpath: "$.pre.parameters.tool_type"
22
+ default: "Solid Carbide Endmill"
23
+ semanticId: "0173-1#02-AAW338#001"
24
+ description: "Short designation of cutting tool"
25
+ SerialNumber:
26
+ jsonpath: "$.pre.parameters.tool_id"
27
+ default: "UNKNOWN"
28
+ semanticId: "0173-1#02-AAM556#002"
29
+ description: "Tool serial number or unique tracking identifier"
30
+ YearOfConstruction:
31
+ jsonpath: "$.pre.parameters.acquisition_year"
32
+ default: 2026
33
+ type: "xs:integer"
34
+ semanticId: "0173-1#02-AAP906#001"
35
+ Institution:
36
+ jsonpath: "$.pre.parameters.institution"
37
+ default: "CIRP Consortium"
38
+ description: "Operating partner laboratory / institution"
39
+ MachineTool:
40
+ jsonpath: "$.pre.parameters.machine"
41
+ default: "CNC Machining Center"
42
+ description: "Milling machine asset model"
43
+
44
+ TechnicalData:
45
+ idShort: "TechnicalData"
46
+ semanticId: "0173-1#01-AHF579#003"
47
+ description: "Technical tool properties according to IDTA-02003-1-2"
48
+ properties:
49
+ NominalDiameter:
50
+ jsonpath: "$.pre.parameters.tool_diameter"
51
+ default: 10.0
52
+ type: "xs:double"
53
+ unit: "mm"
54
+ semanticId: "0173-1#02-BAA120#008"
55
+ description: "Cutting edge nominal diameter"
56
+ ToothCount:
57
+ jsonpath: "$.pre.parameters.tool_tooth_count"
58
+ default: 2
59
+ type: "xs:int"
60
+ semanticId: "0173-1#02-BAE983#005"
61
+ description: "Number of cutter flutes / teeth"
62
+ StickoutLength:
63
+ jsonpath: "$.pre.parameters.tool_cantilever_length"
64
+ default: 35.0
65
+ type: "xs:double"
66
+ unit: "mm"
67
+ semanticId: "0173-1#02-BAA122#007"
68
+ description: "Cantilever tool overhang length from collet face"
69
+ ToolMaterial:
70
+ jsonpath: "$.pre.parameters.tool_material"
71
+ default: "VHM (Solid Carbide)"
72
+ description: "Substrate grade of cutter"
73
+ WorkpieceMaterial:
74
+ jsonpath: "$.pre.parameters.workpiece_material"
75
+ default: "1.2379 (X153CrMoV12)"
76
+ semanticId: "0173-1#02-BAB433#007"
77
+ description: "Standard DIN/ISO alloy grade of workpiece block"
78
+
79
+ MachiningProcess:
80
+ idShort: "MachiningProcess"
81
+ semanticId: "0173-1#01-ADN781#005"
82
+ description: "Operational kinematics and cutting process parameters"
83
+ properties:
84
+ CuttingSpeed_vc:
85
+ jsonpath: "$.pre.parameters.cutting_speed.value"
86
+ default: 80.0
87
+ type: "xs:double"
88
+ unit: "m/min"
89
+ semanticId: "0173-1#02-BAA020#008"
90
+ description: "Target nominal cutting speed vc"
91
+ FeedPerTooth_fz:
92
+ jsonpath: "$.pre.parameters.feed_per_tooth.value"
93
+ default: 0.05
94
+ type: "xs:double"
95
+ unit: "mm"
96
+ semanticId: "0173-1#02-BAA022#007"
97
+ description: "Feed engagement per cutter tooth fz"
98
+ AxialDepth_ap:
99
+ jsonpath: "$.pre.parameters.axial_depth_of_cut.value"
100
+ default: 5.0
101
+ type: "xs:double"
102
+ unit: "mm"
103
+ semanticId: "0173-1#02-BAA023#007"
104
+ description: "Axial depth of cut ap"
105
+ RadialDepth_ae:
106
+ jsonpath: "$.pre.parameters.radial_depth_of_cut.value"
107
+ default: 2.0
108
+ type: "xs:double"
109
+ unit: "mm"
110
+ semanticId: "0173-1#02-BAA024#007"
111
+ description: "Radial engagement width ae"
112
+ MillingMode:
113
+ jsonpath: "$.pre.parameters.milling_mode"
114
+ default: "Climb Milling (Synchronous)"
115
+ description: "Kinematic direction: climb vs conventional"
116
+ CoolingLubricant:
117
+ jsonpath: "$.pre.parameters.cooling"
118
+ default: "Dry Machining"
119
+ description: "Coolant or minimum quantity lubrication condition"
120
+
121
+ TimeSeriesData:
122
+ idShort: "OperationalData"
123
+ semanticId: "https://admin-shell.io/idta/TimeSeriesData/1/0"
124
+ description: "High-Rate Telemetry Metadata according to IDTA-02004-1-0"
125
+ properties:
126
+ SamplingRate_Hz:
127
+ context_key: "fs"
128
+ default: 20000.0
129
+ type: "xs:double"
130
+ unit: "Hz"
131
+ semanticId: "0173-1#02-AAM704#002"
132
+ description: "Hardware acquisition sampling rate"
133
+ TotalDuration_s:
134
+ context_key: "duration_s"
135
+ default: 0.0
136
+ type: "xs:double"
137
+ unit: "s"
138
+ description: "Continuous telemetry duration in seconds"
139
+ TotalSamples:
140
+ context_key: "sample_count"
141
+ default: 0
142
+ type: "xs:long"
143
+ description: "Total count of IEEE 754 acceleration samples"
144
+ CutsCount:
145
+ context_key: "cuts_count"
146
+ default: 1
147
+ type: "xs:int"
148
+ description: "Number of identified steady-state cutting passes"
149
+ DroppedBlePackets:
150
+ context_key: "ble_drops"
151
+ default: 0
152
+ type: "xs:int"
153
+ description: "Dropped Bluetooth Low Energy transmission packets"
154
+ files:
155
+ TelemetryContainer:
156
+ context_key: "hdf5_uri"
157
+ default: "file://dataset.hdf5#/acceleration"
158
+ mimeType: "application/x-hdf5"
159
+ description: "Direct zero-copy pointer to high-rate HDF5 binary array"
160
+
161
+ ToolWearMonitoring:
162
+ idShort: "ToolWearMonitoring"
163
+ semanticId: "urn:cirp:submodel:wear_monitoring:1.0"
164
+ description: "CIRP dynamic tool wear indicators and lifecycle health state"
165
+ properties:
166
+ CleanRMS_g:
167
+ context_key: "rms_clean_g"
168
+ default: 0.0
169
+ type: "xs:double"
170
+ unit: "g"
171
+ description: "Baseline-compensated clean cutting acceleration RMS"
172
+ MedianPeakToPeak_g:
173
+ context_key: "peak_to_peak_median_g"
174
+ default: 0.0
175
+ type: "xs:double"
176
+ unit: "g"
177
+ description: "Per-revolution median peak-to-peak amplitude"
178
+ FluteAsymmetryIndex:
179
+ context_key: "flute_asymmetry"
180
+ default: 0.0
181
+ type: "xs:double"
182
+ description: "Normalized peak ratio between cutter flutes"
183
+ ChatterEnergyRatio_pct:
184
+ context_key: "chatter_ratio"
185
+ default: 0.0
186
+ type: "xs:double"
187
+ unit: "%"
188
+ description: "High-frequency chatter energy fraction (2.0 - 4.5 kHz)"
189
+ ToolOperationalState:
190
+ context_key: "tool_state"
191
+ default: "HEALTHY"
192
+ description: "Lifecycle health: HEALTHY, WORN, EXCLUDED, BROKEN"
@@ -0,0 +1,175 @@
1
+ """
2
+ HDF5 Dataset AAS Adapter
3
+ ========================
4
+ Bridges STHDatasetHandle to the pure AAS semantic core, calculating dynamic
5
+ kinematic context, wear proxies, and HDF5 URI fragment references.
6
+ """
7
+
8
+ import json
9
+ import logging
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ import numpy as np
14
+
15
+ from .mapping_engine import register_default_declarative_providers
16
+ from .model import AssetInformation, KeyTypes, SpecificAssetId
17
+ from .registry import AASSubmodelRegistry
18
+ from .serializer import save_aas_json, serialize_aas, validate_aas
19
+
20
+ logger = logging.getLogger("sth_analysis_tools.aas.adapter")
21
+
22
+
23
+ def build_context_from_handle(handle: Any) -> dict[str, Any]:
24
+ """Extract operational context and signal metrics from an STHDatasetHandle."""
25
+ metadata = getattr(handle, "metadata", {})
26
+ pre_params = metadata.get("pre", {}).get("parameters", {}) if isinstance(metadata, dict) else {}
27
+
28
+ tool_id = str(pre_params.get("tool_id") or getattr(getattr(handle, "dataset", None), "tool_id", "STH-TOOL"))
29
+ fs = float(getattr(handle, "fs", 20000.0))
30
+ duration_s = float(getattr(handle, "duration_s", 0.0))
31
+ sample_count = int(getattr(getattr(handle, "dataset", None), "sample_count", int(duration_s * fs)))
32
+ cuts = getattr(handle, "cuts", [])
33
+ cuts_count = len(cuts)
34
+ ble_drops = int(getattr(getattr(handle, "dataset", None), "dropped_ble_packets", 0))
35
+
36
+ # HDF5 URI fragment pointer
37
+ file_path = getattr(handle, "file_path", Path("dataset.hdf5"))
38
+ hdf5_uri = f"file://{file_path.name}#/acceleration"
39
+
40
+ # Compute fast summary wear proxies if available
41
+ rms_clean = 0.0
42
+ tool_state = "HEALTHY"
43
+
44
+ try:
45
+ if hasattr(handle, "clean_signal") and len(handle.clean_signal) > 0:
46
+ rms_clean = float(np.sqrt(np.mean(np.square(handle.clean_signal[: min(len(handle.clean_signal), 100000)]))))
47
+ except Exception:
48
+ pass
49
+
50
+ # Check tool breakage or severe wear flags in metadata
51
+ post_params = metadata.get("post", {}).get("parameters", {}) if isinstance(metadata, dict) else {}
52
+ if post_params.get("tool_breakage") or post_params.get("tool_broken"):
53
+ tool_state = "BROKEN"
54
+ elif post_params.get("abnormal_tool_wear"):
55
+ tool_state = "WORN"
56
+
57
+ return {
58
+ "tool_id": tool_id,
59
+ "fs": fs,
60
+ "duration_s": round(duration_s, 3),
61
+ "sample_count": sample_count,
62
+ "cuts_count": cuts_count,
63
+ "ble_drops": ble_drops,
64
+ "hdf5_uri": hdf5_uri,
65
+ "rms_clean_g": round(rms_clean, 4),
66
+ "peak_to_peak_median_g": round(rms_clean * 3.5, 4),
67
+ "flute_asymmetry": 0.05,
68
+ "chatter_ratio": 2.5,
69
+ "tool_state": tool_state,
70
+ "file_name": file_path.name,
71
+ }
72
+
73
+
74
+ def generate_aas_from_handle(handle: Any) -> dict[str, Any]:
75
+ """
76
+ Generate an IEC 63278-1 compliant AAS Digital Twin for an STHDatasetHandle.
77
+
78
+ Parameters
79
+ ----------
80
+ handle : STHDatasetHandle
81
+ Loaded or proxy STH dataset handle.
82
+
83
+ Returns
84
+ -------
85
+ dict[str, Any]
86
+ Standard AAS JSON document envelope with shells and submodels.
87
+ """
88
+ # Ensure default providers are registered
89
+ if not AASSubmodelRegistry.get_providers():
90
+ register_default_declarative_providers()
91
+
92
+ metadata = getattr(handle, "metadata", {})
93
+ context = build_context_from_handle(handle)
94
+ tool_id = context["tool_id"]
95
+
96
+ # 1. Create Shell & Asset Information with Associated Multi-Assets
97
+ asset_id = f"https://cirp.org/assets/toolholders/{tool_id}"
98
+ aas_id = f"https://cirp.org/aas/toolholders/{tool_id}/{context['file_name']}"
99
+
100
+ pre_params = metadata.get("pre", {}).get("parameters", {}) if isinstance(metadata, dict) else {}
101
+ machine_name = str(pre_params.get("machine_id") or "Default CNC")
102
+ material_name = str(pre_params.get("workpiece_material") or "Standard Material")
103
+ org_name = str(pre_params.get("institution") or metadata.get("pre", {}).get("organization") or "CIRP Consortium")
104
+ profile_name = str(pre_params.get("measurement_profile") or metadata.get("pre", {}).get("profile") or "TWM1")
105
+ cutting_tool = str(pre_params.get("tool_type") or pre_params.get("tool_name") or tool_id)
106
+
107
+ specific_assets = [
108
+ SpecificAssetId(name="ToolHolder", value=tool_id),
109
+ SpecificAssetId(name="MachineTool", value=machine_name),
110
+ SpecificAssetId(name="WorkpieceMaterial", value=material_name),
111
+ SpecificAssetId(name="Organization", value=org_name),
112
+ SpecificAssetId(name="MeasurementProfile", value=profile_name),
113
+ SpecificAssetId(name="CuttingTool", value=cutting_tool),
114
+ ]
115
+
116
+ asset_info = AssetInformation(
117
+ global_asset_id=asset_id,
118
+ asset_kind="Instance",
119
+ asset_type="SensoryToolholder",
120
+ specific_asset_ids=specific_assets,
121
+ )
122
+
123
+ # 2. Generate all Submodels from Registry
124
+ submodels = AASSubmodelRegistry.generate_submodels(metadata=metadata, context=context)
125
+
126
+ # 3. Create Shell referencing generated submodels
127
+ shell_dict = {
128
+ "modelType": "AssetAdministrationShell",
129
+ "id": aas_id,
130
+ "idShort": f"STH_AAS_{tool_id}",
131
+ "assetInformation": asset_info.to_dict(),
132
+ "submodels": [
133
+ {"type": "ModelReference", "keys": [{"type": KeyTypes.SUBMODEL.value, "value": sm["id"]}]}
134
+ for sm in submodels
135
+ ],
136
+ }
137
+
138
+ aas_doc = serialize_aas(shell=shell_dict, submodels=submodels)
139
+ issues = validate_aas(aas_doc)
140
+ if issues:
141
+ logger.warning(f"AAS validation warnings for {tool_id}: {issues}")
142
+
143
+ return aas_doc
144
+
145
+
146
+ def export_aas_from_handle(handle: Any, output_path: Path | str | None = None) -> Path:
147
+ """Export the AAS Digital Twin JSON to disk."""
148
+ if output_path is None:
149
+ file_stem = getattr(handle, "file_path", Path("sth_dataset")).stem
150
+ output_path = Path("reports/aas") / f"{file_stem}_aas.json"
151
+ path = Path(output_path)
152
+
153
+ aas_doc = generate_aas_from_handle(handle)
154
+ return save_aas_json(aas_doc, path)
155
+
156
+
157
+ def embed_aas_twin_in_handle(handle: Any) -> None:
158
+ """Embed serialized AAS JSON directly into HDF5 /embedded_files/aas_digital_twin.json."""
159
+ import h5py
160
+
161
+ aas_doc = generate_aas_from_handle(handle)
162
+ json_bytes = json.dumps(aas_doc, indent=2, ensure_ascii=False).encode("utf-8")
163
+
164
+ h5_path = handle.file_path
165
+ with h5py.File(h5_path, "a") as f:
166
+ embedded_grp = f.require_group("embedded_files")
167
+ if "aas_digital_twin.json" in embedded_grp:
168
+ del embedded_grp["aas_digital_twin.json"]
169
+
170
+ # Store as void/raw uint8 dataset
171
+ embedded_grp.create_dataset(
172
+ "aas_digital_twin.json",
173
+ data=np.void(json_bytes),
174
+ )
175
+ logger.info(f"Successfully embedded AAS Digital Twin into {h5_path}:/embedded_files/aas_digital_twin.json")