Snapshots & Changelog

Parameter Snapshot

Mỗi phiên bản được xuất bản đều lưu trữ một parameter snapshot: các tham số recipe và test-set được ghi lại theo một schema cố định, có phiên bản, để mỗi phiên bản chứa toàn bộ nội dung có cấu trúc bên trong nó. Mỗi phiên bản cũng có một tệp README trình bày snapshot đó ở dạng dễ đọc.

Một phiên bản có hai tệp snapshot:

• parameters/recipe/<version>.json — snapshot của recipe
• parameters/testset/<version>.json — snapshot của test-set

Cả hai đều mang một schema_version mô tả cấu trúc của tệp (hiện tại là 1.1). Các trường sử dụng đường dẫn dấu chấm bên dưới; [] đánh dấu một danh sách, vì vậy blocks[].type_config.labels[].name là name của mỗi nhãn của mỗi block.

Recipe snapshot

parameters/recipe/<version>.json

Trường	Kiểu	Ý nghĩa
schema_version	string	Phiên bản cấu trúc schema của tệp này.
extracted_at	string	Thời điểm snapshot được tạo.
recipe_name	string	Tên recipe.
description	string | null	Mô tả recipe.
plc_recipe_id	integer | null	ID recipe của PLC.
meta_version	integer	Phiên bản metadata của recipe.
database_version	integer	Phiên bản database của recipe.
software_version	string	Phiên bản phần mềm của recipe.
imaging.preview_image.sha	string	SHA của ảnh preview.
imaging.preview_image.path	string	Đường dẫn của ảnh preview.
imaging.exposure	integer | null	Thời gian phơi sáng.
imaging.gain	number | null	Gain của cảm biến.
imaging.brightness	integer | null	Độ sáng.
imaging.gamma	integer | null	Gamma.
imaging.focal_length	number | null	Tiêu cự.
imaging.focus	number | null	Focus.
imaging.focus_distance	number | null	Khoảng cách focus.
imaging.rotation_mode	integer | null	Chế độ xoay ảnh.
imaging.acq_mode	integer | null	Chế độ thu nhận ảnh.
imaging.hdr_mode_enabled	boolean | null	Bật/tắt chế độ HDR.
imaging.led_mode	integer | null	Chế độ chiếu sáng LED.
imaging.led_gain	integer | null	Gain của LED.
imaging.led_strobe_mode	boolean | null	Bật/tắt strobe của LED.
imaging.lens_correct	boolean | null	Bật/tắt hiệu chỉnh méo ống kính.
imaging.photometric_enabled	boolean | null	Bật/tắt hiệu chỉnh photometric.
imaging.photometric_mode	integer | null	Chế độ photometric.
imaging.awb_red	integer | null	Kênh đỏ auto white-balance.
imaging.awb_green	integer | null	Kênh xanh lá auto white-balance.
imaging.awb_blue	integer | null	Kênh xanh dương auto white-balance.
imaging.awb_op	boolean | null	Bật auto white-balance.
imaging.calibration_pixels_per_unit	number | null	Tỉ lệ hiệu chuẩn (pixel trên đơn vị).
imaging.calibration_unit	string | null	Đơn vị hiệu chuẩn.
imaging.trigger_debounce	integer | null	Debounce của trigger.
imaging.trigger_delay	integer | null	Delay của trigger.
imaging.raw	object	Toàn bộ nguồn imaging chưa phân tích.
blocks[].block_type	string	Loại block (alignment, classification, segmentation, measurement, ocr, unsupervised).
blocks[].uuid	string	Định danh ổn định của block.
blocks[].name	string	Tên block.
blocks[].status	string	Trạng thái block.
blocks[].is_enabled	boolean	Block có được chạy hay không.
blocks[].has_model	boolean	Có mô hình đã huấn luyện được gắn hay không.
blocks[].search_area.search_area_id	integer | null	ID của search-area.
blocks[].search_area.search_area_bbox	list of number | null	Bounding box của search-area.
blocks[].search_area.roi_regions[].bbox	list of number	Bounding box của ROI.
blocks[].search_area.roi_regions[].angle	number	Góc xoay của ROI.
blocks[].type_config	object	Cấu hình đặc thù theo loại (xem bên dưới).
blocks[].model_ref.sha	string	SHA của tệp mô hình đã huấn luyện.
blocks[].model_ref.path	string	Đường dẫn tệp mô hình đã huấn luyện.
blocks[].model_ref.file_extension	string	Phần mở rộng của tệp mô hình đã huấn luyện.
aligner_reference_image.sha	string	SHA của ảnh tham chiếu alignment.
aligner_reference_image.path	string	Đường dẫn ảnh tham chiếu alignment.
aligner_reference_image.full_repo_path	string	Đường dẫn ảnh tham chiếu alignment trong repo.
node_red_flow.basic_mode	boolean	Flow có đang ở chế độ basic hay không.
node_red_flow.basic_flow_id	string | null	ID của flow ở chế độ basic.
node_red_flow.basic_flow_metadata	object | null	Metadata của flow ở chế độ basic.
node_red_flow.nodes[].id	string	ID của node.
node_red_flow.nodes[].node_type	string	Loại node.
node_red_flow.nodes[].name	string	Tên node.
node_red_flow.nodes[].x	integer | null	Vị trí X của node trên canvas.
node_red_flow.nodes[].y	integer | null	Vị trí Y của node trên canvas.
node_red_flow.nodes[].wires	list of list of string	Các kết nối đi ra (theo từng output, ID của node đích).
node_red_flow.nodes[].func	string | null	Mã của function-node.
node_red_flow.nodes[].raw	object	Toàn bộ nguồn node chưa phân tích.

Cấu hình block

Các trường dưới blocks[].type_config phụ thuộc vào blocks[].block_type.

Trường	Kiểu	Ý nghĩa
blocks[].type_config.angle_tolerance_left	number | null	alignment — dung sai góc bên trái.
blocks[].type_config.angle_tolerance_right	number | null	alignment — dung sai góc bên phải.
blocks[].type_config.confidence_score_threshold	number | null	alignment / segmentation / unsupervised — ngưỡng khớp/độ tin cậy.
blocks[].type_config.sensitivity	number | null	alignment / unsupervised — độ nhạy.
blocks[].type_config.version	integer | null	alignment — phiên bản cấu hình.
blocks[].type_config.scale_invariant	boolean | null	alignment — bật/tắt khớp bất biến theo tỷ lệ.
blocks[].type_config.inference_mode	string | null	alignment — chế độ inference.
blocks[].type_config.dl_performance_mode	integer | null	alignment — chế độ hiệu năng deep-learning.
blocks[].type_config.skip_block	boolean | null	alignment — bỏ qua block này.
blocks[].type_config.template_image_id_path	string | null	alignment — đường dẫn tham chiếu hình ảnh template.
blocks[].type_config.labels[].name	string	classification — tên nhãn.
blocks[].type_config.labels[].confidence_threshold	number | null	classification — ngưỡng độ tin cậy cho từng nhãn.
blocks[].type_config.labels[].is_positive	boolean | null	classification — nhãn này có được tính là pass hay không.
blocks[].type_config.labels[].inspection_type	integer | null	classification — kiểu inspection.
blocks[].type_config.labels[].color	string | null	classification — màu hiển thị.
blocks[].type_config.segmentation_type	string | null	segmentation — kiểu segmentation.
blocks[].type_config.classes[].class_name	string	segmentation — tên class.
blocks[].type_config.classes[].mask_pixel_value	integer | null	segmentation — giá trị pixel của mask.
blocks[].type_config.classes[].color	string | null	segmentation — màu hiển thị.
blocks[].type_config.classes[].mask_sha	string | null	segmentation — SHA của tệp mask.
blocks[].type_config.classes[].mask_path	string | null	segmentation — đường dẫn tệp mask.
blocks[].type_config.measurement_regions[]	object	measurement — các vùng đo lường.
blocks[].type_config.min_text_area	integer | null	ocr — diện tích văn bản tối thiểu.
blocks[].type_config.text_segmentation_threshold	number | null	ocr — ngưỡng phân đoạn văn bản.
blocks[].type_config.unclip_ratio	number | null	ocr — tỷ lệ unclip.
blocks[].type_config.unclip_ceiling	number | null	ocr — giới hạn trên của unclip.
blocks[].type_config.unsupervised_type	string | null	unsupervised — kiểu phương pháp.
blocks[].type_config.epochs	integer | null	unsupervised — số epochs huấn luyện.
blocks[].type_config.encoder	string | null	unsupervised — encoder.
blocks[].type_config.learning_rate	number | null	unsupervised — learning rate.
blocks[].type_config.downsampling_ratio	number | null	unsupervised — tỷ lệ downsampling.
blocks[].type_config.tiled_mode	boolean | null	unsupervised — bật/tắt chế độ tiled.
blocks[].type_config.min_blob_area	number | null	unsupervised — diện tích blob tối thiểu.
blocks[].type_config.max_blob_area	number | null	unsupervised — diện tích blob tối đa.
blocks[].type_config.hyperparameters	object	classification / segmentation / measurement / ocr / unsupervised — hyperparameters huấn luyện.

Ảnh chụp Test-set

parameters/testset/<version>.json

Trường	Kiểu	Ý nghĩa
schema_version	string	Phiên bản cấu trúc schema của tệp này.
extracted_at	string	Thời điểm ảnh chụp được thực hiện.
name	string	Tên test-set.
description	string | null	Mô tả test-set.
author	string | null	Tác giả test-set.
image_count	integer	Số lượng hình ảnh.
images_with_ground_truth	integer	Số lượng hình ảnh có ground truth.
search_area_ids[]	string	ID vùng tìm kiếm được test set tham chiếu.
per_class_distribution[].class_name	string	Tên lớp. Được dành riêng; hiện luôn để trống (xem như "phân phối không khả dụng").
per_class_distribution[].count	integer	Số lượng hình ảnh cho lớp. Được dành riêng; hiện luôn để trống.
images[].image_id	string	ID hình ảnh.
images[].ground_truth_fingerprint	string | null	Dấu vân của ground truth của hình ảnh.
images[].has_ground_truth	boolean	Hình ảnh có ground truth hay không.

README

Mỗi phiên bản cũng có một tệp README.md được commit để hiển thị ảnh chụp ở dạng dễ đọc. Các phần của nó bao gồm:

• Imaging Settings — bảng các tham số chụp ảnh.
• Aligner Reference Image — hình ảnh tham chiếu căn chỉnh và mã SHA-256 của nó (chỉ khi recipe có).
• Inspection Blocks — một tiểu mục cho mỗi block, với tiêu đề <name> (<block type>), bao gồm UUID của block, trạng thái và cờ enabled, tiếp theo là một phần đặc thù theo loại — Classification Labels, Segmentation Classes, OCR Parameters, Unsupervised Parameters, Alignment Parameters, hoặc số lượng vùng đo lường.
• Node-RED Flow — cờ basic-mode, số lượng node và bảng danh sách các node (ID, Type, Name).
• Test Set — tên, mô tả, tác giả, số lượng hình ảnh, số hình ảnh có ground truth và các vùng tìm kiếm.

Changelog

Khi một phiên bản được xuất bản, ảnh chụp tham số của nó được so sánh với phiên bản trước để tạo ra changelog. Việc so sánh mang tính cấu trúc — theo từng trường trên toàn bộ schema ở trên, với các danh sách (blocks, labels, classes, Node-RED nodes) được đối chiếu theo định danh ổn định thay vì theo vị trí, vì vậy việc sắp xếp lại thứ tự sẽ không bao giờ hiện ra như một thay đổi. Recipe và test set được so sánh độc lập, và changelog được suy ra từ các ảnh chụp đã commit theo yêu cầu, do đó nó luôn khả dụng cho bất kỳ cặp phiên bản nào.

Các thay đổi được nhóm vào cùng các phần như trong ảnh chụp, và một phần chỉ xuất hiện nếu có gì đó bên trong đã thay đổi. Phiên bản không có khác biệt sẽ được ghi chú như vậy, và phiên bản đầu tiên hiển thị toàn bộ nội dung khởi tạo thay vì diff.