Smart Vision V2 Python 接口文档

Smart Vision V2 Python API

tip

To use Smart Vision SDK, first import the smartvisionsdk package:

from pysmartvision import smartvisionsdk

Python API Overview

Class	Public Member Functions	Type	Description
Camera	open(GetImageCB)	function	Open camera in parameterless mode
	open(DeviceParam, GetImageCB)	function	Open camera with parameters
	start_capture()	function	Start streaming
	stop_capture()	function	Stop streaming
	close()	function	Close camera
Image	data	str	Pointer to buffer containing image data
	w	int	Target image width
	h	int	Target image height
	c	int	Number of image channels (typically 3)
	length	int	Memory length occupied by image data
	srcWidth	int	Internal image width, usually larger than final width
	srcHeight	int	Internal image height
	memCopyStartIndex	int	Index indicating data in buffer
	memCopyEndIndex	int	End index indicating data in buffer
	planeOffset	int	YUV data offset value
TcpConfig	ip	str	IP address
	port	int	Port number
SVSdkMemfdInfo	srcYPlaneStride	int	Width of YUV data
	srcSliceHeight	int	Height of YUV data
	memCopyStartIndex	int	Start index value (Note: Start index equals End index)
	memCopyEndIndex	int	End index value
	planeOffset	int	YUV offset value
	cam_id	int	Camera ID
MediaInfo	duration	int	Video duration
	width	int	Video width
	height	int	Video height
	frame_rate	int	Video frame rate
	file_size	int	Video file size
	file_name	str	Video file name

Public Function	Description
`set_log_level(SVLogLevel log_level)`	Set log level
`set_log_destination(str destinationPath, bool also_to_stderr)`	Set log file name and path
`log_to_stderr()`	Output logs to terminal. Once set, log files will not be saved. Generally not recommended.
`GetImageCB(const Image, int)`	Used as input parameter for open() function to acquire image resources. This function is user-defined. The interface only provides type definition to standardize callback function definition.
`set_off_mode()`	Set OFF mode to disable signal output.
`int8_t get_tcp_setting(int cam_id, TcpConfig& tcp_setting)`	Get TCP settings.
`int8_t tcp_send_signal(int cam_id, std::string message)`	Send TCP signal.
`int8_t tcp_send(std::string message, TcpConfig& tcp_setting)`	Send TCP string message.
`int8_t io_send(std::string io_str, std::string io_control_file)`	Write specified string to specific file.
`int8_t send_signal_on(int device_id)`	Send up signal to specified device (e.g., do1, do2, do3), keeptime read from configuration.
`int8_t send_signal_on(int device_id, int keeptime)`	Send up signal to specified device (e.g., do1, do2, do3), keeptime passed as parameter.
`int8_t send_signal_off(int device_id)`	Send clear signal to specified device (e.g., do1, do2, do3).
`string get_camera_info(int8_t idx = 0)`	Get corresponding configuration file path based on camera index, read and parse JSON format camera configuration.
`string get_camera_default_setting(int8_t idx = 0)`	Load default configuration via camera index, get complete configuration string and sync to system singleton.
`string get_sensor_model_info(int idx)`	Get sensor model information.
`get_all_cam_ids(disable_cache=False)`	Decide whether to read from local configuration or detect all camera model names in real-time based on cache disabling.
`vector<int> get_all_cam_index()`	Get all indices.
`get_all_cameras(disable_cache=False)`	Call underlying detection logic to get all camera information.
`int get_idx_by_loc_id(int loc_id)`	Find corresponding logical index (cam_id or idx) based on camera's physical location ID (loc_id).
`int get_loc_id_by_idx(int idx)`	Reverse lookup physical location ID (loc_id) based on camera's logical index (idx).
`int get_cam_index(std::string cam_id)`	Find corresponding logical index by camera name.
`string get_cam_id(int cam_index)`	Find and return corresponding camera name based on logical index.
`cv::Mat image_read(int8_t idx = 0)`	Safely read current preview frame from specified camera (JPEG format).
`int8_t get_camera_status(int8_t idx = 0)`	Record and return current status code of specified camera index via logs.
`void start_camera_capture(int idx = 0)`	Start image capture for specified camera.
`void stop_camera_capture(int idx = 0)`	Stop image capture for specified camera.
`int get_dst_width(int8_t idx = 0)`	Get target width of output image from specified camera.
`int get_dst_height(int8_t idx = 0)`	Get target height of output image from specified camera.
`int8_t notify_sve(SPhase phase_enum)`	Send current task phase notification to local SVE service via HTTP (POST) request.
`int8_t save_result(const char release_id, const char release_version, const char origin_file, const char mask_file, const char final_file, const char additional = "")`	Package image analysis task result file paths and additional information as JSON and report to local SVE service.
`get_cvimage(img, idx, max_timeout_ms)`	Get image data from specified index, convert to image object directly usable by Python.
`void qmm_cleanup(int cam_id = 0)`	Send control signal in specific format to stop specified or all camera services.
`void qmm_cleanup_all()`	Send control signal in specific format to stop specified or all camera services.
`void qmm_cleanup_invalid()`	Clean up qmm processes with abnormal status.
`int qmm_status(int idx = 0)`	Check if service process corresponding to specified camera index is alive, implemented based on Redis heartbeat mechanism.
`int start_record(int idx)`	Safely start camera video recording with multiple pre-checks.
`get_record_status()`	Query current video recording status.
`MediaInfo stop_record(int idx)`	Stop camera recording process and extract recording result metadata from internal state.
`int set_bpp_binning(std::string cam_id, int binning_flag, int hb, int vb, int bpp_flag, int bpp)`	Specify camera pixel binning and bit depth.

Enum	Member Variable	Type	Description
SVLogLevel	SINFO	int	Log level SINFO
	SWARNING	int	Log level SWARNING
	SERROR	int	Log level SERROR
	SDEBUG	int	Log level SDEBUG
	SOFF	uint8_t	Log level SOFF
SignalType	OFF	int	Disable signal output
	NG_SIGNAL	uint8_t	NG signal output mode
	ALARM_SIGNAL	uint8_t	Alarm signal output mode
	OK_SIGNAL	uint8_t	OK signal output mode
SignalMode	IO_MODE	uint8_t	IO mode
	TCP_MODE	uint8_t	TCP mode
	MODBUS_MODE	uint8_t	MODBUS mode
	UART_MODE	uint8_t	UART mode

Camera Class

Operations related to instantiating Camera objects. Camera operations such as opening and capturing images are all based on instantiated Camera objects.

tip

This version is compatible with the first generation camera's open function open, start capture function start_capture, stop capture function stop_capture, and close camera function close.

For the latest functions:

Open camera with parameters: refer to start_camera_with_parameter
Open camera without parameters: refer to start_camera_without_parameter
Start capture: refer to start_camera_capture
Stop capture: refer to stop_camera_capture
Close camera: refer to close_camera

warning

Unlike C++, Python code does not require namespace import. Instead, import the smartvisionsdk module using:

from pysmartvision import smartvisionsdk

See the following interfaces for specific usage.

Open Camera in Parameterless Mode

Parameterless mode: Use default camera parameter configuration

API	`open(cb)`
Description	Open camera in parameterless mode.
Parameters	Input parameter is a callback function. Callback function is user-defined. See Callback Function GetImageCB for details.
Return Value	0: Success. -1: Failure.

Example (camera_instance is an instance of Camera class, same below):

python

# Open camera in parameterless mode
camera_instance = smartvisionsdk.Camera()
res = camera_instance.open(my_get_img_cb)

Open Camera with Parameters

Parameter mode: Use custom parameter configuration, see DeviceParam

API	`open(dev_param, cb)`
Description	Open camera with parameters.
Parameters	dev_param: Instance of DeviceParam class. cb: Callback function. Callback function is user-defined. See Callback Function GetImageCB for details.
Return Value	0: Success. -1: Failure.

Example:

python

# Open camera with parameters
camera_instance = smartvisionsdk.Camera()
res = camera_instance.open(device_param, my_get_img_cb)

Start Streaming

API	`start_capture()`
Description	Start streaming
Parameters	None
Return Value	None

Example:

python

# Start streaming
camera_instance.start_capture()

Stop Streaming

API	`stop_capture()`
Description	Stop streaming
Parameters	None
Return Value	None

Example:

python

# Stop streaming
camera_instance.stop_capture()

Close Camera

API	`close()`
Description	Close camera
Parameters	None
Return Value	0: Success. -1: Failure.

Example:

python

# Close camera
res = camera_instance.close()

DeviceParam Class

Defines parameter configuration file path with path. This configuration file is used to configure camera parameters. Therefore, it is only used when opening camera with parameters.

Member Variable	Type	Default	Description
cfg_name	str		Path to parameter configuration file

Set DeviceParam Configuration File

API	`set_cfgname(config_file)`
Description	Set path to parameter configuration file. This interface sets the cfg_name variable.
Parameters	`config_file`: Camera parameter configuration file
Return Value	None

Example:

python

# Set configuration file
device_param = smartvisionsdk.DeviceParam()
device_param.set_cfgname("./config.json")

Image Class

Defines image data related information, including image configuration and pointer variables.

Member Variable	Type	Description
data	str	String pointer to buffer containing data
w	int	Target image width
h	int	Target image height
c	int	Number of image channels (typically 3)
length	int	Memory length occupied by image data
srcWidth	int	Internal image width, usually larger than final width
srcHeight	int	Internal image height
memCopyStartIndex	int	Index indicating data in buffer
memCopyEndIndex	int	End index indicating data in buffer
planeOffset	int	YUV data offset value

TcpConfig Class

Defines TCP signal output configuration.

Member Variable	Type	Default	Description
ip	str		IP address
port	int		Port number

SVSdkMemfdInfo Class

Defines data buffer information.

Member Variable	Type	Description
srcYPlaneStride	int	Width of YUV data
srcSliceHeight	int	Height of YUV data
memCopyStartIndex	int	Start index value (Note: Start index equals End index)
memCopyEndIndex	int	End index value
planeOffset	int	YUV offset value
cam_id	int	Camera ID

Set Log Level (Function set_log_level)

API	`set_log_level(log_level)`
Description	Set log level.
Parameters	`log_level`: SVLogLevel enum. See SVLogLevel Enum for details.
Return Value	None

Example:

python

# Set log level
smartvisionsdk.set_log_level(smartvisionsdk.SVLogLevel.SINFO)

Set Log File Name and Path (Function set_log_destination)

API	`set_log_destination(destinationPath, also_to_stderr)`
Description	Set log file name and path
Parameters	destinationPath: Log file path, default is `"./aidclog_smart_vision_"`. also_to_stderr: Whether to output to terminal, default is False
Return Value	None

Example:

python

# Set log file name and path
log_path = "./aidclog_smart_vision_setting_"
smartvisionsdk.set_log_destination(log_path, False)

Output Logs to Terminal (Function log_to_stderr)

API	`log_to_stderr()`
Description	Output logs to terminal. Once set, log files will not be saved. Generally not recommended.
Parameters	None
Return Value	None

Example:

python

# Output logs to terminal
smartvisionsdk.log_to_stderr()

Log Level (Enum SVLogLevel)

Member Variable	Type	Default	Description
SINFO	int	0	Log level SINFO
SWARNING	int		Log level SWARNING
SERROR	int		Log level SERROR
SDEBUG	int		Log level SDEBUG
SOFF	int		Log level SOFF

Callback Function GetImageCB

API	`GetImageCB(image, mem_info)`
Description	Used as input parameter for open() function to acquire image resources. This function is user-defined. The interface only provides type definition to standardize callback function definition.
Parameters	First parameter is Image class instance through which data is passed. Second parameter is SVSdkMemfdInfo class instance containing buffer index, YUV data width/height, etc.
Return Value	User-defined

Example:

python

# Callback function definition
def my_get_img_cb(cap_img, mem_info):
    # Process image data
    print(f"Image width: {cap_img.w}, height: {cap_img.h}")
    return 0

Set OFF Mode to Disable Signal Output (Function set_off_mode)

API	`set_off_mode()`
Description	Set OFF mode to disable signal output.
Parameters	None
Return Value	-1: Failure. 0: Success.

Example:

python

# Set OFF mode to disable signal output
res = smartvisionsdk.set_off_mode()

Get Camera Configuration (Function get_camera_info)

API	`get_camera_info(idx)`
Description	Get corresponding configuration file path based on camera index, read and parse JSON format camera configuration.
Parameters	idx: Camera index.
Return Value	Success: JSON format string containing camera configuration. Failure: Empty string ("").

Example:

python

info = smartvisionsdk.get_camera_info(0)

Get Complete Configuration (Function get_camera_default_setting)

API	`get_camera_default_setting(idx)`
Description	Load default configuration via camera index, get complete configuration string and sync to system singleton.
Parameters	idx: Camera index.
Return Value	Success: JSON format string containing camera configuration. Failure: Empty string ("").

Example:

python

setting = smartvisionsdk.get_camera_default_setting(0)

Get Sensor Model Information (Function get_sensor_model_info)

API	`get_sensor_model_info(idx)`
Description	Get sensor model information.
Parameters	idx: Camera index.
Return Value	Success: String containing sensor model information. Failure: Empty string ("").

Example:

python

model_info = smartvisionsdk.get_sensor_model_info(0)

Get All Camera IDs (Function get_all_cam_ids)

API	`get_all_cam_ids(disable_cache)`
Description	Decide whether to read from local configuration or detect all camera model names in real-time based on cache disabling.
Parameters	disable_cache (True: Force re-detection, clear cache. False: Use cached data, no re-detection).
Return Value	List of SensorName strings for all successfully identified cameras.

Example:

python

# Use cache
camera_list = smartvisionsdk.get_all_cam_ids(False)

Get All Camera Information (Function get_all_cameras)

API	`get_all_cameras(disable_cache)`
Description	Call underlying detection logic to get all camera information.
Parameters	disable_cache (True: Force re-detection, clear cache. False: Use cached data, no re-detection).
Return Value	Dictionary where key is camera physical location ID (e.g., 0, 1, 2) and value is corresponding sensor name.

Example:

python

# Use cache
cameras = smartvisionsdk.get_all_cameras(False)

Get SDK Version Information (Function get_build_version)

API	`get_build_version()`
Description	Get SDK version information.
Parameters	None
Return Value	SDK version string

Example:

python

# Get SDK version information
res = smartvisionsdk.get_build_version()

Get Mat Object Data (Function get_cvimage)

API	`get_cvimage(img, idx, max_timeout_ms)`
Description	Get image data from specified index, convert to image object directly usable by Python.
Parameters	img: Image object. idx: Camera logical index. max_timeout_ms: Maximum wait time in milliseconds.
Return Value	Converted image object

Example:

python

# Get Mat object data, where cap_img is input image object containing YUV data
im = smartvisionsdk.get_cvimage(cap_img, 0, 1000)

Get Latest Log Message (Function log_last_msg)

API	`log_last_msg(log_level)`
Description	Get latest log message
Parameters	SVLogLevel log level
Return Value	Latest log record

Example:

python

# Get latest log message
res = smartvisionsdk.log_last_msg(log_level)

Get FPS (Function get_fps)

API	`get_fps(idx)`
Description	Get real-time FPS from callback function, which represents camera capture frame rate.
Parameters	Camera index idx. MIPI camera: 0~2. Default is 0.
Return Value	FPS value

Example:

python

# Get real-time camera capture FPS
fps_v = smartvisionsdk.get_fps()

Configure Camera (Function configure_camera)

API	`configure_camera(file_path, set_property, validation)`
Description	Set camera parameters.
Parameters	file_path: Configuration file. set_property: Apply immediately (True: yes, False: no). validation: Validate parameters (True: yes, False: no)
Return Value	0: Success. -1: Failure

Example:

python

# Configure camera parameters
res = smartvisionsdk.configure_camera("./param.json", True, True)

Start Image Capture (Function start_camera_capture)

API	`start_camera_capture(idx)`
Description	Start image capture for specified camera.
Parameters	idx: Camera logical index.
Return Value	None

Example:

python

smartvisionsdk.start_camera_capture(0)

Stop Image Capture (Function stop_camera_capture)

API	`stop_camera_capture(idx)`
Description	Stop image capture for specified camera.
Parameters	idx: Camera logical index.
Return Value	None

Example:

python

smartvisionsdk.stop_camera_capture(0)

Close Camera Service (Function qmm_cleanup)

API	`qmm_cleanup(cam_id)`
Description	Send control signal in specific format to stop specified camera service.
Parameters	cam_id: Camera logical index.
Return Value	None

Example:

python

# Stop camera 0
smartvisionsdk.qmm_cleanup(0)

Close All Camera Services (Function qmm_cleanup_all)

API	`qmm_cleanup_all()`
Description	Send control signal in specific format to stop all camera services.
Parameters	None
Return Value	None

Example:

python

smartvisionsdk.qmm_cleanup_all()

Process Check (Function qmm_status)

API	`qmm_status(idx)`
Description	Check if service process corresponding to specified camera index is alive, implemented based on Redis heartbeat mechanism.
Parameters	idx: Camera logical index.
Return Value	2: Service running. 0: Not registered. 4: Service abnormal.

Example:

python

status = smartvisionsdk.qmm_status(0)

Start Recording (Function start_record)

API	`start_record(idx)`
Description	Safely start camera video recording with multiple pre-checks.
Parameters	idx: Camera logical index.
Return Value	0: Success. -1: Failure.

Example:

python

cam_idx = 0
if smartvisionsdk.get_camera_status(cam_idx) == 2:
    ret = smartvisionsdk.start_record(cam_idx)
    if ret == 0:
        print("Started successfully!")
    else:
        print("Failed to start recording")

Recording Status Check (Function get_record_status)

API	`get_record_status()`
Description	Query current video recording status.
Parameters	None
Return Value	0: Recording. -1: Not recording.

Example:

python

record_status = smartvisionsdk.get_record_status()
if record_status == 0:
    print("Recording video...")
else:
    print("Not recording")

Stop Recording (Function stop_record)

API	`stop_record(idx)`
Description	Stop camera recording process and extract recording result metadata from internal state.
Parameters	idx: Camera logical index.
Return Value	MediaInfo object containing recording result information.

Example:

python

cam_idx = 0
# Stop recording and get information
record_info = smartvisionsdk.stop_record(cam_idx)

Signal Type Definition (Enum SignalType)

Member Variable	Type	Default	Description
OFF	int	0	Disable signal output
NG_SIGNAL	uint8_t		NG signal output mode
ALARM_SIGNAL	uint8_t		Alarm signal output mode
OK_SIGNAL	uint8_t		OK signal output mode

Signal Mode Definition (Enum SignalMode)

Member Variable	Type	Default	Description
IO_MODE	uint8_t	0	IO mode
TCP_MODE	uint8_t	1	TCP mode
MODBUS_MODE	uint8_t	2	MODBUS mode
UART_MODE	uint8_t	3	UART mode

Smart Vision V2 Python 接口文档 ​

Smart Vision V2 Python API ​

Python API Overview ​

Camera Class ​

Open Camera in Parameterless Mode ​

Open Camera with Parameters ​

Start Streaming ​

Stop Streaming ​

Close Camera ​

DeviceParam Class ​

Set DeviceParam Configuration File ​

Image Class ​

TcpConfig Class ​

SVSdkMemfdInfo Class ​

Set Log Level (Function set_log_level) ​

Set Log File Name and Path (Function set_log_destination) ​

Output Logs to Terminal (Function log_to_stderr) ​

Log Level (Enum SVLogLevel) ​

Callback Function GetImageCB ​

Set OFF Mode to Disable Signal Output (Function set_off_mode) ​

Get Camera Configuration (Function get_camera_info) ​

Get Complete Configuration (Function get_camera_default_setting) ​

Get Sensor Model Information (Function get_sensor_model_info) ​

Get All Camera IDs (Function get_all_cam_ids) ​

Get All Camera Information (Function get_all_cameras) ​

Get SDK Version Information (Function get_build_version) ​

Get Mat Object Data (Function get_cvimage) ​

Get Latest Log Message (Function log_last_msg) ​

Get FPS (Function get_fps) ​

Configure Camera (Function configure_camera) ​

Start Image Capture (Function start_camera_capture) ​

Stop Image Capture (Function stop_camera_capture) ​

Close Camera Service (Function qmm_cleanup) ​

Close All Camera Services (Function qmm_cleanup_all) ​

Process Check (Function qmm_status) ​

Start Recording (Function start_record) ​

Recording Status Check (Function get_record_status) ​

Stop Recording (Function stop_record) ​

Signal Type Definition (Enum SignalType) ​

Signal Mode Definition (Enum SignalMode) ​

Smart Vision V2 Python 接口文档

Smart Vision V2 Python API

Python API Overview

Camera Class

Open Camera in Parameterless Mode

Open Camera with Parameters

Start Streaming

Stop Streaming

Close Camera

DeviceParam Class

Set DeviceParam Configuration File

Image Class

TcpConfig Class

SVSdkMemfdInfo Class

Set Log Level (Function set_log_level)

Set Log File Name and Path (Function set_log_destination)

Output Logs to Terminal (Function log_to_stderr)

Log Level (Enum SVLogLevel)

Callback Function GetImageCB

Set OFF Mode to Disable Signal Output (Function set_off_mode)

Get Camera Configuration (Function get_camera_info)

Get Complete Configuration (Function get_camera_default_setting)

Get Sensor Model Information (Function get_sensor_model_info)

Get All Camera IDs (Function get_all_cam_ids)

Get All Camera Information (Function get_all_cameras)

Get SDK Version Information (Function get_build_version)

Get Mat Object Data (Function get_cvimage)

Get Latest Log Message (Function log_last_msg)

Get FPS (Function get_fps)

Configure Camera (Function configure_camera)

Start Image Capture (Function start_camera_capture)

Stop Image Capture (Function stop_camera_capture)

Close Camera Service (Function qmm_cleanup)

Close All Camera Services (Function qmm_cleanup_all)

Process Check (Function qmm_status)

Start Recording (Function start_record)

Recording Status Check (Function get_record_status)

Stop Recording (Function stop_record)

Signal Type Definition (Enum SignalType)

Signal Mode Definition (Enum SignalMode)