V-REP 常规API(在lua脚本中使用的API)---(1)

V-REP API框架

V-REP API框架将V-REP周围的所有接口分组。 它有4 + 1种不同分类：

Regular API—常规API
The remote API—远程API
The ROS interfaces—ROS接口
The auxiliary API—辅助API
Other interface—其他接口

可以从仿真器中访问常规API（例如，从嵌入式脚本，插件，插件或主客户端应用程序），也可以几乎任何可能的外部应用程序或硬件访问远程API和ROS接口。 （包括真正的机器人，远程计算机等）。 辅助API本身不是一个接口，而是一个可以嵌入并且可以自行运行的辅助函数集合。 其他接口项将用户扩展可用接口的所有可能性分组。 下图说明了各种接口的概述：

Regular API 常规API

常规API

常规API是V-REP API框架的一部分。

常规API由几百个可以从C / C ++应用程序（插件或主客户端应用程序）或嵌入式脚本调用的函数组成。 V-REP函数和常量可以通过它们的“sim” - 或“_sim”-prefix（例如simHandleCollision）轻松识别。 确保不要将常规API（有时也简称为“API”）与远程API混淆。

常规API可以通过自定义lua函数，插件或主客户端应用程序寄存器进行扩展。 可以从“simExt”–prefix中识别自定义lua函数。

进入或来自API的所有单位均以米，千克，秒和弧度或其组合（除非另有明确说明）。 
用户界面单位以米，千克，秒和度为单位。

Regular API function list (by category) 常规API函数列表（按类别）

File operations 文件操作

simCloseScene:
关闭当前场景，并切换到另一个打开的场景。 如果没有其他打开场景，则创建新场景。 另请参见simLoadScene和simSaveScene。

simSaveScene:
保存场景。 任何具有相同名称的现有文件都将被覆盖。 另请参见simLoadScene，simCloseScene，simSaveModel和simSaveUI。

simLoadScene:
加载以前保存的场景。 如果当前场景不为空，则在切换到场景并加载场景之前将创建一个新场景。 另请参见simSaveScene，simLoadModel，simLoadUI，simCloseScene和simSetBoolParameter以及sim_boolparam_scene_and_model_load_messages。

simSaveModel
保存一个模型(一个被标记为“object is model base”的对象及其层次树中的所有其他对象)。任何具有相同名称的现有文件都将被覆盖。参见simLoadModel、simSaveUI和simSaveScene。

simLoadModel
加载先前保存的模型，并选择它。还请参见simSaveModel、simLoadUI、simLoadScene和simSetBoolParameter，其中包含sim_param_scene_and_model_load_messages。
simSaveUI
将一个或多个基于OpenGl的自定义UI保存到UI文件（* .ttb文件）中。 任何具有相同名称的现有文件都将被覆盖。 另请参见simLoadUI，simSaveModel和simSaveScene。
simLoadUI
加载以前保存的基于OpenGl的自定义UI文件（* .ttb文件）。 另请参见simSaveUI，simLoadModel，simLoadScene和simSetBoolParameter以及sim_boolparam_scene_and_model_load_messages。 在与来自附加组件的UI交互时，您可能必须将属性标志sim_ui_property_pauseactive添加到UI，以便在模拟暂停时让它响应。
simDoesFileExist
指示文件是否存在。
simImportShape
从文件导入形状（首先导入网格，然后将它们组合/合并为形状）。 另见simImportMesh。
simImportMesh
从文件导入网格。 另请参见simExportMesh，simImportShape和simCreateMeshShape
simExportMesh
将网格导出到文件。参见simImportMesh和simGetShapeMesh
simExportIk
导出场景的IK内容。 生成的文件可以与外部IK一起使用，以在外部应用程序中执行IK计算。
simLaunchExecutable
启动可执行文件。 与os.execute或io.popen类似，但与系统无关。
simFileDialog
打开一个对话框，允许选择用于保存或加载操作的文件。 另请参见simMsgBox。
simCreateTexture
创建一个平面形状，使用新的或导入的纹理进行纹理化。 另请参见simGetTextureId，simReadTexture，simWriteTexture和simSetShapeTexture。

General object handle retrieval 一般对象句柄检索

simGetObjectHandle
远程API等价：simxGetObjectHandle
RosPlugin API等价：simRosGetObjectHandle

根据名称检索对象句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid和simGetObjectUniqueIdentifier。
simGetUIHandle
远程API等价：simxGetUIHandle
相当于RosPlugin的API：simRosGetUIHandle
检索基于OpenGl的自定义UI的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。
simGetCollectionHandle
远程API等价物：simxGetCollectionHandle
相当于RosPlugin的API：simRosGetCollectionHandle
根据名称检索集合句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simCreateCollection，simAddObjectToCollection，simGetCollectionObjects和simIsHandleValid。
simGetCollisionHandle
远程API等价物：simxGetCollisionHandle
相当于RosPlugin的API：simRosGetCollisionHandle
检索碰撞对象的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。
simGetDistanceHandle
远程API等价物：simxGetDistanceHandle
相当于RosPlugin的API：simRosGetDistanceHandle
检索距离对象的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。
simGetMechanismHandle
检索要由几何约束求解器求解的机制的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。
simGetIkGroupHandle
检索IK组的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。
simGetScriptHandle
检索脚本的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 脚本不直接指定名称，但如果脚本是子脚本并与场景对象关联，则脚本名称是关联的场景对象的名称。 另请参见simIsHandleValid。
simIsHandleValid
检查通用对象句柄是否仍然有效。 当一般对象被销毁时（例如，以编程方式或通过用户界面），其相关句柄不再有效，并且在使用时将触发错误。 使用此功能可避免触发错误。 另请参见simGetObjectHandle，simGetUIHandle，simGetCollectionHandle，simGetCollisionHandle，simGetDistanceHandle，simGetMechanismHandle，simGetIkGroupHandle，simGetScriptHandle和simGetObjectUniqueIdentifier
simGetObjectAssociatedWithScript
重新处理脚本附加到的对象的句柄。 另请参见simGetScriptAssociatedWithObject，simGetCustomizationScriptAssociatedWithObject和simAssociateScriptWithObject。
simGetObjects
检索对象句柄。 在索引从0开始的循环中使用它，并递增以获取场景中的所有对象句柄。 另请参见simGetObjectsInTree。
simGetObjectsInTree
检索给定层次结构树中的对象句柄。 另请参见simGetObjects。
simGetCollectionObjects
检索组成给定集合的对象句柄。
simGetNameSuffix
返回对象名称的名称后缀（例如“myRobot＃42”的名称后缀为42），或检索为当前脚本或c / c ++ API调用设置的名称后缀。 另请参见simSetNameSuffix，并阅读有关访问常规类型对象的部分。
simSetNameSuffix
设置名称后缀调整编号（有关详细信息，请阅读有关访问常规类型对象的部分）。在V-REP中，所有对象都由名称和句柄标识。当一个对象（场景对象或通用类型对象）与子脚本同时被复制时，新创建的对象的名称将变为“oldName＃0”，如果同一个对象被粘贴另一次，则下一个名称将是“oldName＃1”等

在子脚本中，检索对象句柄是通过自动将名称后缀附加到对象名称来执行的（每个脚本都使用其附加的对象的名称后缀编号进行初始化）。这允许复制粘贴对象和脚本，而无需手动调整脚本（脚本将根据设置的名称后缀自动知道他们必须访问哪个对象）。在脚本中，大多数情况下您不需要设置名称后缀，但在某些特殊情况下，您可能需要暂时禁用它（例如“myChildScript＃42”（其名称后缀自动设置为42）将其自身与其附加的机器人（“myRobot＃42”）一起复制，现在从“myChildScript＃42”中移动“myRobot＃43”以避免碰撞。在这种情况下，将名称后缀设置为43，移动“myRobot” （使用simGetObjectHandle（“myRobot”）检索其句柄，然后将后缀设置回42）。在脚本中，simSetNameSuffix命令仅影响当前脚本。

但是，当从脚本外部访问API时，需要手动调整名称调整机制（确保在完成检索句柄后将名称后缀重置为其初始状态）。想象一下，你的场景中有一个名为“机器人”的机器人。您可以使用simGetObjectHandle（“robot”）从C / C ++应用程序访问机器人。如果机器人是复制的，第二个机器人的名字将是“机器人＃0”，第三个将是“机器人＃1”等。从您的C / C ++应用程序中，您现在可以访问具有相同代码的所有机器人，您只需需要调整名称后缀号。例如。 simSetNameSuffix（42），然后simGetObjectHandle（“机器人”）将检索“机器人＃42”的句柄。完成访问对象后，将名称后缀编号重置为-1（simSetNameSuffix（-1））。

将名称后缀设置为-1将禁用名称调整机制（从脚本外部访问API时的默认值）

另请参见simGetNameSuffix函数。

General functionality handling 一般功能处理

simHandleMainScript
处理（执行）主脚本，即主模拟循环。
simHandleChildScripts
执行位于当前场景层次结构分支中的非线程子脚本。 默认情况下，子脚本将以级联方式执行，并且只能从主脚本调用此命令，特殊情况除外（在这种情况下还要参考函数调用simSetScriptAttribute（scriptHandle，sim_childscriptattribute_automaticcascadingcalls，false））。
simHandleGeneralCallbackScript
说明调用常规回调脚本。 仅从模拟线程调用此函数，而不是从GUI线程调用。
simLaunchThreadedChildScripts
启动或重新启动（如果适当标记）所有线程子脚本。 只应从主脚本调用此命令。 另请参阅以下相关函数：simSwitchThread，simSetThreadSwitchTiming，simSetThreadAutomaticSwitch，simSetThreadIsFree，simSetThreadResumeLocation和simResumeThreads。
simResetScript
重置链接到特定脚本的脚本解释器。

simHandleCollision
处理（检查碰撞等）已注册的碰撞对象。 编辑场景时可以注册碰撞对象。 另请参阅simReadCollision，simResetCollision，simCheckCollision和simCheckCollisionEx。

simResetCollision
清除已注册碰撞对象的碰撞状态，颜色，交叉点等。 另见simHandleCollision。

simHandleDistance
处理（测量距离等）已注册的距离对象。 编辑场景时可以注册距离对象。 另请参见simReadDistance，simResetDistance和simCheckDistance。

simResetDistance
清除已注册距离对象的距离状态，距离段等。 另请参见simHandleDistance。

simHandleMechanism
处理使用几何约束求解器功能注册的机制。 编辑场景时可以注册机制。

simHandleGraph
处理图形对象（即记录已注册数据流的当前值）。 可以在编辑场景时添加/注册图形和数据流。 另请参见simResetGraph。

simResetGraph
清除图形对象（重置其所有数据流）。 另见simHandleGraph。

simHandleIkGroup
处理（求解）已注册的IK组。 编辑场景时可以注册IK组。 另请参见simCheckIkGroup，simComputeJacobian和simGenerateIkPath。

simHandleModule
处理插件。 此功能仅适用于Lua API。 其注册的自定义Lua函数旁边的插件可能需要定期执行操作，而不是从线程脚本调用时（例如，用于同步目的）。 他们可以在调用simHandleModule时执行此操作（但是之前应该调用simOpenModule）。 有关更多详细信息，请参阅中继到插件的消息。 simHandleModule只能从主脚本中调用，并且在C-API中不可用。 查看默认主脚本以了解如何使用simOpenModule，simHandleModule和simCloseModule。

simHandleProximitySensor
处理（执行感测等）已注册的接近传感器对象。 另请参见simReadProximitySensor，simCheckProximitySensor，simCheckProximitySensorEx和simResetProximitySensor。

simResetProximitySensor
清除接近传感器对象的检测状态，检测颜色，检测段等。 另请参见simHandleProximitySensor。

simHandleVisionSensor
处理（执行感测等）注册的视觉传感器对象。 不推荐从一个线程调用此函数，然后从另一个线程调用此函数，这可能会减慢模拟速度。 另请参见simReadVisionSensor，simCheckVisionSensor，simCheckVisionSensorEx和simResetVisionSensor。

simResetVisionSensor
清除接近传感器对象的检测状态等。 另见simHandleVisionSensor。

simHandleMill
处理（执行切割）已注册的铣削对象。 另请参见simResetMill。

simResetMill
清除所有先前设置的铣削计算结果（切削对象列表，已切削的曲面和体积）。 另见simHandleMill。

simApplyMilling
将铣削操作期间所做的更改应用于可切割对象（例如形状）。 这需要一些计算时间。 一旦应用了更改，它们就不能再重置。 如果铣削操作铣削掉整个对象，则从场景中移除对象。 删除链接到对象的计算结构，并可能计算更新的计算结构（可能需要一些计算时间）。 另请参见simResetMilling，simHandleMill和simResetMill。

simResetMilling
将可切割对象（例如形状）重置为其初始形状（在铣削之前），从而取消铣削更改。 删除链接到对象的计算结构，并可能计算更新的计算结构（可能需要一些计算时间）。 另请参见simApplyMilling，simHandleMill和simResetMill。

simHandleVarious
处理各种功能（例如，在模拟期间的相机跟踪等）。 如果可能，每个模拟通道只应调用一次。
simGetExplicitHandling
检索常规对象的显式处理标志。 另请参见simSetExplicitHandling。
simSetExplicitHandling
设置常规对象的显式处理标志。 另请参见simGetExplicitHandling。

Collision detection functionality 碰撞检测功能

simGetCollisionHandle
相当于 remote API：simxGetCollisionHandle
相当于RosPlugin的API：simRosGetCollisionHandle
检索碰撞对象的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。

simIsHandleValid
检查通用对象句柄是否仍然有效。 当一般对象被销毁时（例如，以编程方式或通过用户界面），其相关句柄不再有效，并且在使用时将触发错误。 使用此功能可避免触发错误。 另请参见simGetObjectHandle，simGetUIHandle，simGetCollectionHandle，simGetCollisionHandle，simGetDistanceHandle，simGetMechanismHandle，simGetIkGroupHandle，simGetScriptHandle和simGetObjectUniqueIdentifier

simHandleCollision
处理（检查碰撞等）已注册的碰撞对象。 编辑场景时可以注册碰撞对象。 另请参阅simReadCollision，simResetCollision，simCheckCollision和simCheckCollisionEx。

simReadCollision
相当于远程API：simxReadCollision
相当于RosPlugin API：simRosReadCollision
读取已注册的碰撞对象的碰撞状态。 此函数不执行冲突检测，它只读取上一次调用simHandleCollision的结果（在默认主脚本中调用simHandleCollision）。 另请参见simResetCollision，simCheckCollision和simCheckCollisionEx。

simResetCollision
清除已注册碰撞对象的碰撞状态，颜色，交叉点等。 另见simHandleCollision。

simCheckCollision
检查两个实体是否发生冲突。 与simHandleCollision相比，检测是静默的（没有视觉反馈）。 此外，如果实体是对象，则覆盖实体的可碰撞标志。 另请参见simReadCollision和simCheckCollisionEx。

simCheckCollisionEx
检查两个实体是否发生冲突。 这是simCheckCollision的扩展功能版本，将返回两个实体之间的所有交叉点。 与simHandleCollision相比，检测是静默的（没有视觉反馈）。 此外，如果实体是对象，则覆盖实体的可碰撞标志。 另见simReadCollision。

Minimum distance calculation functionality 最小距离计算功能

simGetDistanceHandle
相当于remote API：simxGetDistanceHandle
相当于RosPlugin的API：simRosGetDistanceHandle
检索距离对象的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。

simIsHandleValid
检查通用对象句柄是否仍然有效。 当一般对象被销毁时（例如，以编程方式或通过用户界面），其相关句柄不再有效，并且在使用时将触发错误。 使用此功能可避免触发错误。 另请参见simGetObjectHandle，simGetUIHandle，simGetCollectionHandle，simGetCollisionHandle，simGetDistanceHandle，simGetMechanismHandle，simGetIkGroupHandle，simGetScriptHandle和simGetObjectUniqueIdentifier

simHandleDistance
处理（测量距离等）注册距离对象。 编辑场景时可以注册距离对象。 另请参见simReadDistance，simResetDistance和simCheckDistance。

simReadDistance
相当于remote API等：simxReadDistance
相当于RosPlugin的API：simRosReadDistance
读取已注册距离对象的距离。 此函数不执行距离测量，它只读取先前调用simHandleDistance的结果（在默认主脚本中调用simHandleDistance）。 另请参见simResetDistance和simCheckDistance。

simResetDistance
清除已注册距离对象的距离状态，距离段等。 另请参见simHandleDistance。

simCheckDistance
检查两个实体之间的最小距离。 与simHandleDistance相比，检测是静默的（无视觉反馈）。 此外，如果实体是对象，则覆盖实体的可测量标志。 另请参见simReadDistance。

另请参见simSetObjectXXXParameter和simGetObjectXXXParameter函数
和它们的碰撞对象相关的参数。

IK and geometric constraint solver functionalities IK和几何约束求解器功能

simGetIkGroupHandle
检索IK组的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。

simIsHandleValid
检查通用对象句柄是否仍然有效。 当一般对象被销毁时（例如，以编程方式或通过用户界面），其相关句柄不再有效，并且在使用时将触发错误。 使用此功能可避免触发错误。 另请参见simGetObjectHandle，simGetUIHandle，simGetCollectionHandle，simGetCollisionHandle，simGetDistanceHandle，simGetMechanismHandle，simGetIkGroupHandle，simGetScriptHandle和simGetObjectUniqueIdentifier

simHandleIkGroup
处理（解决）已注册的IK组。 编辑场景时可以注册IK组。 另请参见simCheckIkGroup，simComputeJacobian和simGenerateIkPath。

simCheckIkGroup
求解已注册的IK组，但与simHandleIkGroup函数不同，simCheckIkGroup不会应用计算的关节值，而是将它们返回到数组中。 另请参见simHandleIkGroup，simComputeJacobian和simGenerateIkPath。

simComputeJacobian
计算已注册IK组的雅可比行列式。 然后可以通过simGetIkGroupMatrix读取结果。 另请参见simHandleIkGroup和simCheckIkGroup。

simSetIkElementProperties
设置特定反向运动学元素（IK元素）的属性。 另请参见simSetIkGroupProperties和simGetIkGroupHandle。

simGetIkGroupMatrix
从IK组中检索各种信息，例如雅可比行列式。 为了使结果有效，雅可比必须先通过simComputeJacobian，simHandleIkGroup或simCheckIkGroup函数计算。 以下情况必须区分：
a）如果在调用simGetIkGroupMatrix之前调用simComputeJacobian，则返回的雅可比行列式将是该机制的当前状态/配置。 这是检索雅可比行列式的推荐方法。
b）如果在调用simGetIkGroupMatrix之前调用simHandleIkGroup或simCheckIkGroup，则返回的雅可比行列式将是最后计算的，同时尝试到达目标（因为线性化通常需要至少2-3次迭代才能到达目标） ，这不是机制的当前状态/配置，除非目标与尖端重叠。
另请参见simGetIkGroupHandle。

simGetMechanismHandle
检索要由几何约束求解器求解的机制的句柄。 此函数的操作取决于当前名称后缀设置（请参阅simGetNameSuffix，simSetNameSuffix和有关访问常规类型对象的部分）。 另请参见simIsHandleValid。

simHandleMechanism
处理使用几何约束求解器功能注册的机制。 编辑场景时可以注册机制。

simGetLinkDummy
检索链接到此虚拟对象的对象句柄。 另请参见simSetLinkDummy。

simGenerateIkPath
生成一条路径，将机器人从其当前配置驱动到直线（即笛卡尔空间中的最短路径）。

simCreateIkGroup
创建IK组。 另请参见simRemoveIkGroup和simCreateIkElement。

simRemoveIkGroup
删除IK组。 另请参见simGetIkGroupHandle和simCreateIkGroup。

simCreateIkElement
创建IK元素。 另请参见simCreateIkGroup。

simExportIk
导出场景的IK内容。 生成的文件可以与外部IK一起使用，以在外部应用程序中执行IK计算。

另请参见simSetObjectXXXParameter和simGetObjectXXXParameter函数
和它们的IK组和几何约束求解器对象相关的参数。

Path/Motion planning functionality 路径/运动规划功能

OMPL插件API在这里有一些解释
simGetConfigForTipPose
搜索与空间中给定的末端效应器位置/方向匹配的操纵器配置。 搜索是随机的。

simGenerateIkPath
生成一条路径，将机器人从其当前配置驱动到直线（即笛卡尔空间中的最短路径）。