Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# OpenTest chart time terminology

These terms distinguish the capture instant, a position within a measurement, and the visible range. Other domain boundaries are documented in CONTEXT.md.

## Time

**Acquisition Timestamp**: A trustworthy time marker for the instant data was captured, corresponding to a complete calendar date and time. A file's creation or modification date is not an acquisition timestamp.
_Avoid_: File time, accumulated measurement seconds

**Task-relative Time**: A position relative to the origin of one measurement task, without a calendar date.
_Avoid_: Acquisition timestamp, clock label

**Time-axis Display Mode**: The representation of a time position presented to the user, including relative seconds and clock time with milliseconds.
_Avoid_: Acquisition time source, fixed-range binding mode

**Chart Viewport**: The currently visible range of the chart axes. It does not itself determine which points are copied or exported.
_Avoid_: Original data range, export data range

**Absolute Fixed Range**: A range bounded by two complete acquisition instants. Changing records or measuring again does not change those instants.
_Avoid_: Fixed seconds after the start of each measurement
20 changes: 20 additions & 0 deletions GLOSSARY.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# OpenTest 图谱时间术语

以下术语区分采集时刻、测量内的位置及用户看到的范围;其余领域边界见 CONTEXT.md。

## 时间

**采集绝对时间(Acquisition Timestamp)**:数据实际采集时刻的可信时间标记,可对应完整日期和时间;文件创建或修改时间不构成采集绝对时间。
_Avoid_:文件时间、测量累计秒数

**任务相对时间(Task-relative Time)**:数据在一次测量任务内相对于任务原点的位置,不表达日历日期。
_Avoid_:采集绝对时间、时钟刻度

**时间轴显示方式(Time-axis Display Mode)**:同一时间位置面向用户的表达方式,包括相对秒及带毫秒的时钟显示。
_Avoid_:采集时间来源、固定范围绑定方式

**图谱视口(Chart Viewport)**:当前图谱坐标轴可见的范围;它本身不决定复制或数据导出的取点范围。
_Avoid_:原始数据范围、导出数据范围

**绝对固定范围(Absolute Fixed Range)**:以两个完整采集绝对时刻界定的固定范围;更换记录或再次测量不改变这两个时刻。
_Avoid_:固定测量起点后的同一秒数区间
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,15 @@ public Axis() {
* 是否自适应
*/
private Boolean autoScale;

/** Acquisition instants are decimal nanoseconds, never floating-point axis coordinates. */
private AbsoluteTimeRange absoluteTimeRange;
}

@Data
public static class AbsoluteTimeRange implements Serializable {
private String startNs;
private String endNs;
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,20 @@ public class HeatmapChartConfig extends BaseChartConfig {
public void setAxisInfo(Axis xAxis, Axis yAxis) {
if (heatmap != null) {
Axis realXAxis = new Axis( true);
realXAxis.setUnit(UnitEnum.SECOND.getCode());
realXAxis.setUnit(getTimeDisplayUnit());
heatmap.setXAxis(realXAxis);
heatmap.setYAxis(xAxis);
heatmap.setZAxis(yAxis);
}
}

/** Time is independent of the frequency coordinate carried by the result. */
@JsonIgnore
public String getTimeDisplayUnit() {
String stored = getUnitX();
return "h:m:s".equals(stored) || "hms".equals(stored) ? "h:m:s" : UnitEnum.SECOND.getCode();
}

@Override
public void applyAxisDefaults(Axis xAxis, Axis yAxis) {
if (heatmap != null) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import com.opentest.common.model.dto.*;
import com.opentest.common.model.dto.algorithm.AlgorithmResultCodeResponseDto;
import com.opentest.common.model.dto.chart.BaseChartConfig;
import com.opentest.common.model.dto.chart.HeatmapChartConfig;
import com.opentest.common.model.dto.dashboard.TimeWindowConfigDto;
import com.opentest.common.model.dto.node.AbstractNodeConfig;
import com.opentest.common.model.dto.parameters.BaseVariableParameters;
Expand Down Expand Up @@ -189,8 +190,14 @@ public static BaseChartConfig convertChartConfig(String unitX, String unitY, Str
}
// Heatmaps use elapsed time horizontally; the result's X coordinate
// is frequency and belongs to their Y axis, including legacy records.
chartConfig.setUnitX(StrUtil.equals(ChartTypeEnum.HEATMAP.getCode(), chartType)
? UnitEnum.SECOND.getCode() : unitX);
if (chartConfig instanceof HeatmapChartConfig heatmap) {
if ("s".equals(unitX) || "h:m:s".equals(unitX) || "hms".equals(unitX)) {
heatmap.setUnitX(unitX);
}
chartConfig.setUnitX(heatmap.getTimeDisplayUnit());
} else {
chartConfig.setUnitX(unitX);
}
// 先执行基础单位处理 双轴最多两个
processBasicUnitDesc(chartConfig, resultCodes, unitY, windowAxis);
assembleDefaultTitle(chartConfig, resultCodes, semanticResultCount);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,16 @@
class ChartConfigAxisRoundTripTest {
private final ObjectMapper mapper = new ObjectMapper();

@Test
void absoluteAxisEndpointsRemainDecimalNanosecondsAcrossStorage() {
String json = "{\"chartType\":\"heatmap\",\"heatmap\":{\"xAxis\":{\"unit\":\"h:m:s\",\"absoluteTimeRange\":{\"startNs\":\"1795075990180123456\",\"endNs\":\"1795075991180123456\"}}}}";
var source = CryBusinessUtil.parseChartConfig(json);
var stored = ChartConfigStorageCodec.copy(source);
var node = mapper.valueToTree(stored).path("heatmap").path("xAxis").path("absoluteTimeRange");
assertEquals("1795075990180123456", node.path("startNs").asText());
assertEquals("1795075991180123456", node.path("endNs").asText());
}

@Test
void heatmapReadKeepsTimeCoordinateSeparateFromTheFrequencyResultUnit() {
String stored = "{\"chartType\":\"heatmap\",\"heatmap\":{\"xAxis\":{\"unit\":\"Hz\"},\"yAxis\":{\"unit\":\"Hz\"},\"zAxis\":{\"unit\":\"dBV rms\"}}}";
Expand All @@ -23,6 +33,25 @@ void heatmapReadKeepsTimeCoordinateSeparateFromTheFrequencyResultUnit() {
assertEquals("dBV rms", chart.getUnitZ());
}

@Test
void heatmapClockSelectionSurvivesDefaultsAndReadback() {
String stored = "{\"chartType\":\"heatmap\",\"heatmap\":{\"xAxis\":{\"unit\":\"h:m:s\"}}}";
var chart = (HeatmapChartConfig) CryBusinessUtil.convertChartConfig("Hz", "Hz", stored, List.of(), null);
assertEquals("h:m:s", chart.getUnitX());
chart.applyAxisDefaults(null, null);
assertEquals("h:m:s", chart.getUnitX());
}

@Test
void heatmapRequestUnitSurvivesRebuiltConfigurationAndSwitchesBackToSeconds() {
var chart = (HeatmapChartConfig) CryBusinessUtil.convertChartConfig("h:m:s", "Hz",
"{\"chartType\":\"heatmap\"}", List.of(), null);
assertEquals("h:m:s", chart.getUnitX());
String stored = ChartConfigStorageCodec.encode(chart);
assertEquals("h:m:s", CryBusinessUtil.convertChartConfig("Hz", "Hz", stored, List.of(), null).getUnitX());
assertEquals("s", CryBusinessUtil.convertChartConfig("s", "Hz", stored, List.of(), null).getUnitX());
}

@org.junit.jupiter.api.Test
void snapshotDtoCopyUsesRegisteredConverterWithoutRevivingAxes() throws Exception {
var registry = cn.hutool.core.convert.ConverterRegistry.getInstance();
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
package com.opentest.core.export;

import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.Locale;

/** Presentation of trusted acquisition timestamps, shared by binary and tabular exports. */
public final class AcquisitionClock {
private static final DateTimeFormatter CLOCK = DateTimeFormatter.ofPattern("HH:mm:ss.SSS", Locale.ROOT)
.withZone(ZoneId.systemDefault());
private AcquisitionClock() { }
public static boolean selected(String unit) { return "h:m:s".equals(unit) || "hms".equals(unit); }
public static String zone() { return CLOCK.getZone().getId(); }
public static String format(long nanos) {
return nanos > 0 ? CLOCK.format(Instant.ofEpochSecond(0, nanos)) : "—";
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,13 @@ static void validate(Path path,
fileId = H5.H5Fopen(path.toString(), HDF5Constants.H5F_ACC_RDONLY,
HDF5Constants.H5P_DEFAULT);
validateUserBlock(fileId);
validateRootVariableCount(fileId, curves.size() * 2L + 2L + tableVariables.size()
validateRootVariableCount(fileId, curves.size() * 2L + 2L + curves.stream().filter(ResultMat73Writer.CurveLayout::isClock).count() * 2L + tableVariables.size()
+ (tableManifestLength > 0 ? 1L : 0L));
for (ResultMat73Writer.CurveLayout curve : curves) {
if (curve.isClock()) {
validateTimeVariable(fileId, "/" + curve.getKey() + "_x_timestamp_ns", 1, curve.getPointCount(), "int64", HDF5Constants.H5T_STD_I64LE);
validateTimeVariable(fileId, "/" + curve.getKey() + "_x_clock", 12, curve.getPointCount(), "char", HDF5Constants.H5T_STD_U16LE);
}
validateCurveVariable(fileId, "/" + curve.getKey() + "_x",
curve.getPointCount());
validateCurveVariable(fileId, "/" + curve.getKey() + "_y",
Expand Down Expand Up @@ -146,6 +150,21 @@ private static void validateCurveVariable(long fileId,
}
}

private static void validateTimeVariable(long fileId, String path, int rows, long count, String matlabClass, long type) throws IOException {
long dataset = HDF5Constants.H5I_INVALID_HID;
long dataType = HDF5Constants.H5I_INVALID_HID;
try {
dataset = openRequiredDataset(fileId, path);
validateDimensions(dataset, new long[]{rows, count}, path);
validateMatlabClass(dataset, matlabClass.getBytes(StandardCharsets.US_ASCII), path);
dataType = H5.H5Dget_type(dataset);
if (!H5.H5Tequal(dataType, type)) throw new IOException("Invalid acquisition time type: " + path);
} finally {
closeDataType(dataType);
closeDataset(dataset);
}
}

private static void validateJsonVariable(long fileId,
String path,
int byteLength) throws IOException {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package com.opentest.core.export.result.mat;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.opentest.core.export.AcquisitionClock;
import hdf.hdf5lib.H5;
import hdf.hdf5lib.HDF5Constants;

Expand Down Expand Up @@ -61,6 +62,8 @@ public final class ResultMat73Writer implements AutoCloseable {
private long fileId = HDF5Constants.H5I_INVALID_HID;
private long activeXDatasetId = HDF5Constants.H5I_INVALID_HID;
private long activeYDatasetId = HDF5Constants.H5I_INVALID_HID;
private long activeTimestampDatasetId = HDF5Constants.H5I_INVALID_HID;
private long activeClockDatasetId = HDF5Constants.H5I_INVALID_HID;
private String activeKey;
private ResultMatCurveMetadata activeMetadata;
private long activePointCount;
Expand Down Expand Up @@ -147,6 +150,10 @@ public void startCurve(ResultMatCurveMetadata metadata) throws IOException {
String key = String.format(Locale.ROOT, "curve_%04d", curves.size() + 1);
activeXDatasetId = createExtendibleDoubleDataset("/" + key + "_x");
activeYDatasetId = createExtendibleDoubleDataset("/" + key + "_y");
if (metadata.isClock()) {
activeTimestampDatasetId = createExtendibleDataset("/" + key + "_x_timestamp_ns", HDF5Constants.H5T_STD_I64LE, "int64", 1);
activeClockDatasetId = createExtendibleDataset("/" + key + "_x_clock", HDF5Constants.H5T_STD_U16LE, "char", 12);
}
activeKey = key;
activeMetadata = metadata;
activePointCount = 0L;
Expand Down Expand Up @@ -183,9 +190,15 @@ public void append(double[] xValues,
double[] yValues,
int offset,
int length) throws IOException {
append(xValues, yValues, offset, length, null);
}

public void append(double[] xValues, double[] yValues, int offset, int length, long[] timestamps) throws IOException {
requireOpen();
try {
requireActiveCurve();
if (timestamps != null && (offset < 0 || offset > timestamps.length - length))
throw new IllegalArgumentException("Acquisition timestamps must align with X points");
if (xValues == null || yValues == null) {
throw new IllegalArgumentException("结果曲线 X/Y 数据块不能为空");
}
Expand All @@ -202,6 +215,7 @@ public void append(double[] xValues,
activePointCount, nextPointCount);
extendAndWrite(activeYDatasetId, yValues, offset, length,
activePointCount, nextPointCount);
if (activeMetadata.isClock()) writeClockBlock(timestamps, offset, length, activePointCount, nextPointCount);
activePointCount = nextPointCount;
} catch (IllegalArgumentException | IllegalStateException failure) {
failAndCleanup(failure);
Expand Down Expand Up @@ -409,21 +423,25 @@ private void createFile() throws IOException {
}

private long createExtendibleDoubleDataset(String datasetPath) {
return createExtendibleDataset(datasetPath, HDF5Constants.H5T_IEEE_F64LE, "double", 1);
}

private long createExtendibleDataset(String datasetPath, long type, String matlabClass, int rows) {
long dataSpaceId = HDF5Constants.H5I_INVALID_HID;
long creationPropertyId = HDF5Constants.H5I_INVALID_HID;
long datasetId = HDF5Constants.H5I_INVALID_HID;
RuntimeException failure = null;
try {
dataSpaceId = H5.H5Screate_simple(2,
new long[]{1L, 0L}, new long[]{1L, HDF5Constants.H5S_UNLIMITED});
new long[]{rows, 0L}, new long[]{rows, HDF5Constants.H5S_UNLIMITED});
creationPropertyId = H5.H5Pcreate(HDF5Constants.H5P_DATASET_CREATE);
H5.H5Pset_chunk(creationPropertyId, 2,
new long[]{1L, CURVE_CHUNK_POINTS});
new long[]{rows, CURVE_CHUNK_POINTS});
datasetId = H5.H5Dcreate(fileId, datasetPath,
HDF5Constants.H5T_IEEE_F64LE, dataSpaceId,
type, dataSpaceId,
HDF5Constants.H5P_DEFAULT, creationPropertyId,
HDF5Constants.H5P_DEFAULT);
writeMatlabClass(datasetId, MATLAB_DOUBLE_CLASS);
writeMatlabClass(datasetId, matlabClass.getBytes(StandardCharsets.US_ASCII));
} catch (RuntimeException createFailure) {
failure = createFailure;
} finally {
Expand Down Expand Up @@ -527,6 +545,37 @@ private void extendAndWrite(long datasetId,
}
}

private void writeClockBlock(long[] timestamps, int offset, int length, long start, long end) {
long[] stamps = new long[length];
short[] characters = new short[12 * length];
for (int i = 0; i < length; i++) {
stamps[i] = timestamps == null ? 0 : timestamps[offset + i];
String clock = String.format(Locale.ROOT, "%-12s", AcquisitionClock.format(stamps[i]));
for (int column = 0; column < 12; column++) characters[column * length + i] = (short) clock.charAt(column);
}
writeTimeValues(activeTimestampDatasetId, HDF5Constants.H5T_NATIVE_LLONG, stamps, 1, length, start, end);
writeTimeValues(activeClockDatasetId, HDF5Constants.H5T_NATIVE_USHORT, characters, 12, length, start, end);
}

private void writeTimeValues(long dataset, long type, Object values, int rows, int length, long start, long end) {
long fileSpace = HDF5Constants.H5I_INVALID_HID;
long memorySpace = HDF5Constants.H5I_INVALID_HID;
RuntimeException failure = null;
try {
H5.H5Dset_extent(dataset, new long[]{rows, end});
fileSpace = H5.H5Dget_space(dataset);
H5.H5Sselect_hyperslab(fileSpace, HDF5Constants.H5S_SELECT_SET, new long[]{0, start}, null, new long[]{rows, length}, null);
memorySpace = H5.H5Screate_simple(2, new long[]{rows, length}, null);
H5.H5Dwrite(dataset, type, memorySpace, fileSpace, HDF5Constants.H5P_DEFAULT, values);
} catch (RuntimeException writeFailure) {
failure = writeFailure;
} finally {
failure = closeHandle(HandleType.DATA_SPACE, memorySpace, failure);
failure = closeHandle(HandleType.DATA_SPACE, fileSpace, failure);
}
if (failure != null) throw failure;
}

private void writeMatlabHeader() throws IOException {
byte[] header = new byte[128];
Arrays.fill(header, 0, 124, (byte) ' ');
Expand Down Expand Up @@ -599,6 +648,10 @@ private IOException closeHdf5Handles() {

private IOException closeActiveCurveDatasets() {
RuntimeException firstFailure = null;
firstFailure = closeHandle(HandleType.DATASET, activeClockDatasetId, firstFailure);
activeClockDatasetId = HDF5Constants.H5I_INVALID_HID;
firstFailure = closeHandle(HandleType.DATASET, activeTimestampDatasetId, firstFailure);
activeTimestampDatasetId = HDF5Constants.H5I_INVALID_HID;
if (activeYDatasetId >= 0L) {
try {
H5.H5Dclose(activeYDatasetId);
Expand Down Expand Up @@ -698,6 +751,8 @@ private CurveLayout(String key,
this.metadata = metadata;
}

boolean isClock() { return metadata.isClock(); }

String getKey() {
return key;
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.opentest.core.export.result.mat;

import com.opentest.core.export.AcquisitionClock;
import java.util.LinkedHashMap;
import java.util.Map;

Expand Down Expand Up @@ -40,6 +41,8 @@ public static Builder builder(String resultSetId,
return new Builder(resultSetId, resultCode, channelId);
}

public boolean isClock() { return AcquisitionClock.selected(unitX); }

Map<String, Object> toManifestMap(String key, long pointCount) {
Map<String, Object> json = new LinkedHashMap<>();
json.put("key", key);
Expand All @@ -52,7 +55,14 @@ Map<String, Object> toManifestMap(String key, long pointCount) {
json.put("channelName", channelName);
json.put("channelType", channelType);
json.put("domainType", domainType);
json.put("unitX", unitX);
json.put("unitX", isClock() ? "s" : unitX);
if (isClock()) {
json.put("timeDisplayUnit", "h:m:s");
json.put("timeZone", AcquisitionClock.zone());
json.put("timestampVariable", key + "_x_timestamp_ns");
json.put("clockVariable", key + "_x_clock");
json.put("missingAcquisitionTime", "timestamp 0; clock —");
}
json.put("unitY", unitY);
json.put("pointCount", pointCount);
if (valueShape != null) { json.put("valueShape", valueShape); }
Expand Down
Loading
Loading