\see urg_open()

 センサから距離データを取得します。事前に urg_start_measurement() を #URG_DISTANCE 指定で呼び出しておく必要があります。

 \param[in,out] urg URG センサ管理
 \param[out] data 距離データ [mm]
 \param[out] time_stamp タイムスタンプ [msec]

 \retval >=0 受信したデータ個数
 \retval <0 エラー

 data には、センサから取得した距離データが格納されます。data はデータを格納するのサイズを確保しておく必要があります。data に格納されるデータ数は urg_max_data_size() で取得できます。

 time_stamp には、センサ内部のタイムスタンプが格納されます。time_stamp を取得したくない場合 NULL を指定して下さい。


 Example

      long *data = (long*)malloc(urg_max_data_size(&urg) * sizeof(data[0]));

      ...

      \~japanese
      // データのみ取得する
      \~english
      // Gets only measurement data
      urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
      int n = urg_get_distance(&urg, data, NULL);

      ...

      \~japanese
      // データとタイムスタンプを取得する
      \~english
      // Gets measurement data and timestamp
      long time_stamp;
      urg_start_measurement(&urg, URG_DISTANCE, 1, 0);
      n = urg_get_distance(&urg, data, &time_stamp); 

  \see urg_start_measurement(), urg_max_data_size()

 urg_get_distance() に加え、強度データの取得ができる関数です。事前に urg_start_measurement() を #URG_DISTANCE_INTENSITY 指定で呼び出しておく必要があります。

 \param[in,out] urg URG センサ管理
 \param[out] data 距離データ [mm]
 \param[out] intensity 強度データ
 \param[out] time_stamp タイムスタンプ [msec]

 \retval >=0 受信したデータ個数
 \retval <0 エラー

 強度データとは、距離計算に使った波形の反射強度であり、センサのシリーズ毎に特性が異なります。 強度データを使うことで、物体の反射率や環境の大まかな濃淡を推測できます。

 data, time_stamp については urg_get_distance() と同じです。

 intensity には、センサから取得した強度データが格納されます。intensity はデータを格納するのサイズを確保しておく必要があります。intensity に格納されるデータ数は urg_max_data_size() で取得できます。


 Example

      int data_size = urg_max_data_size(&urg);
      long *data = malloc(data_size * sizeof(long));
      long *intensity = malloc(data_size * sizeof(unsigned short));

      ...

      urg_start_measurement(&urg, URG_DISTANCE_INTENSITY, 1, 0);
      int n = urg_get_distance_intensity(&urg, data, intesnity, NULLL); 

  \see urg_start_measurement(), urg_max_data_size()

 マルチエコー版の距離データ取得関数です。事前に urg_start_measurement() を #URG_MULTIECHO 指定で呼び出しておく必要があります。

 \param[in,out] urg URG センサ管理
 \param[out] data_multi 距離データ [mm]
 \param[out] time_stamp タイムスタンプ [msec]

 \retval >=0 受信したデータ個数
 \retval <0 エラー

 マルチエコーとは複数の距離データです。 マルチエコーは、１つのレーザ発光において複数の距離データが得られたときに得られます。

 \image html multiecho_image.png マルチエコーのイメージ図

 time_stamp については urg_get_distance() と同じです。

 data_multi には、センサから取得した距離データが１つの step あたり最大で #URG_MAX_ECHO (3 つ)格納されます。マルチエコーが存在しない項目のデータ値は -1 が格納されています。

      data_multi[0] ... step n の距離データ (1 つめ)
      data_multi[1] ... step n の距離データ (2 つめ)
      data_multi[2] ... step n の距離データ (3 つめ)
      data_multi[3] ... step (n + 1) の 距離データ (1 つめ)
      data_multi[4] ... step (n + 1) の 距離データ (2 つめ)
      data_multi[5] ... step (n + 1) の 距離データ (3 つめ)
      ... 

  Example

      long *data_multi = malloc(3 * urg_max_data_size(&urg) * sizeof(long));

      ...

      urg_start_measurement(&urg, URG_MULTIECHO, 1, 0);
      int n = urg_get_distance_intensity(&urg, data_multi, NULLL); 

  \see urg_start_measurement(), urg_max_data_size()

 urg_get_multiecho() に加え、強度データの取得できる関数です。事前に urg_start_measurement() を #URG_MULTIECHO_INTENSITY 指定で呼び出しておく必要があります。

 \param[in,out] urg URG センサ管理
 \param[out] data_multi 距離データ [mm]
 \param[out] intensity_multi 強度データ
 \param[out] time_stamp タイムスタンプ [msec]

 \retval >=0 受信したデータ個数
 \retval <0 エラー

 data_multi, time_stamp については urg_get_multiecho() と同じです。

 intensity_multi のデータの並びは data_multi と対応したものになります。intensity_multi に格納されるデータ数は urg_max_data_size() で取得できます。


 Example

      int data_size = urg_max_data_size(&urg);
      long *data_multi = malloc(3 * data_size * sizeof(long));
      long *intensity_multi = malloc(3 * data_size * sizeof(unsigned short));

      ...

      urg_start_measurement(&urg, URG_DISTANCE_INTENSITY, 1, 0);
      int n = urg_get_multiecho_intensity(&urg, data_multi,
      intesnity_multi, NULLL); 

  \see urg_start_measurement(), urg_max_data_size()

 指定したデバイスに接続し、距離を計測できるようにする。

 \param[in,out] urg URG センサ管理
 \param[in] connection_type 通信タイプ
 \param[in] device_or_address 接続デバイス名
 \param[in] baudrate_or_port 接続ボーレート [bps] / TCP/IP ポート

 \retval 0 正常
 \retval <0 エラー

 connection_type には、以下の項目が指定できます。

 - #URG_SERIAL
 - シリアル、USB 接続

 - #URG_ETHERNET
 - イーサーネット接続


 Example

      urg_t urg;

      if (urg_open(&urg, URG_SERIAL, "/dev/ttyACM0", 115200) < 0) {
      return 1;
      }

      ...

      urg_close(&urg); 

  \attention URG C ライブラリの他の関数を呼び出す前に、この関数を呼び出す必要があります。

  \see urg_close()

  センサが計測する範囲を step 値で指定します。urg_get_distance() などの距離データ取得の関数で返されるデータ数は、ここで指定した範囲で制限されます。

  \param[in,out] urg URG センサ管理
  \param[in] first_step 計測の開始 step
  \param[in] last_step 計測の終了 step
  \param[in] skip_step 計測データをグルーピングする個数

  \retval 0 正常
  \retval <0 エラー

  センサの step は、センサ正面を 0 とし、センサ上部から見て反時計まわりの向きが正の値となる順に割り振られます。

  \image html sensor_angle_image.png センサと step の関係

  step の間隔と、最大値、最小値はセンサ依存です。step 値の最大値、最小値は urg_step_min_max() で取得できます。\n

  first_step, last_step でデータの計測範囲を指定します。計測範囲は [first_step, last_step] となります。

  skip_step は、計測データをグルーピングする個数を指定します。指定できる値は [0, 99] です。\n
  skip_step は、指定された数のデータを 1 つにまとめることで、センサから受信するデータ量を減らし、距離取得を行う関数の応答性を高めるときに使います。ただし、データをまとめるため、得られるデータの分解能は減ります。

  例えば以下のような距離データが得られる場合に

      100, 101, 102, 103, 104, 105, 106, 107, 108, 109

      100, 102, 104, 106, 108

  This function allows definining the scope (start and end steps) for measurement. The number of measurement data (steps) returned by urg_get_distance() and similar is defined here.

  \param[in,out] urg URG control structure
  \param[in] first_step start step number
  \param[in] last_step end step number
  \param[in] skip_step step grouping factor

  \retval 0 Successful
  \retval <0 Error

  Observing the sensor from the top, the step 0 corresponds to the very front of the sensor, steps at the left side (counter clockwise) of step 0 are positive numbers and those to the right side (clockwise) are negative numbers.

  \image html sensor_angle_image.png shows the relation between sensor and steps

  The spacing between steps, the minimum and maximum step numbers depend on the sensor. Use urg_step_min_max() to get the minimum and maximum step values.\n

  first_step and last_step define the data measurement scope ([first_step, last_step])。

  skip_step allows setting a step grouping factor, where valid values are [0, 99].\n
  With the skip_step parameter, several adjacent steps are grouped and combined into 1 single step, thus the amount of data transmitted from the sensor is reduced and so the response time of measurement data adquisition functions. Of course, grouping several steps into one means the measurement resolution is reduced.

  For example, for the following range data obtained in the sensor:

      100, 101, 102, 103, 104, 105, 106, 107, 108, 109

      100, 102, 104, 106, 108

      urg_set_scanning_parameter(&urg, urg_deg2step(&urg, -45),
      urg_deg2step(&urg, +45), 1);
      urg_start_measurement(&urg, URG_DISTANCE, 0);
      int n = urg_get_distance(&urg, data, NULL);
      for (int i = 0; i < n; ++i) {
      printf("%d [mm], %d [deg]\n", data[i], urg_index2deg(&urg, i));
      } 

  \see urg_step_min_max(), urg_rad2step(), urg_deg2step()

  \see urg_wakeup()

 距離データの取得を開始します。実際のデータは urg_get_distance(), urg_get_distance_intensity(), urg_get_multiecho(), urg_get_multiecho_intensity() で取得できます。

 \param[in,out] urg URG センサ管理
 \param[in] type データ・タイプ
 \param[in] scan_times データの取得回数
 \param[in] skip_scan データの取得間隔

 \retval 0 正常
 \retval <0 エラー

 type には取得するデータの種類を指定します。

 - #URG_DISTANCE ... 距離データ
 - #URG_DISTANCE_INTENSITY ... 距離データと強度データ
 - #URG_MULTIECHO ... マルチエコー版の距離データ
 - #URG_MULTIECHO_INTENSITY ... マルチエコー版の(距離データと強度データ)

 scan_times は何回のデータを取得するかを 0 以上の数で指定します。ただし、0 または #URG_SCAN_INFINITY を指定した場合は、無限回のデータを取得します。\n
 開始した計測を中断するには urg_stop_measurement() を使います。

 skip_scan はミラーの回転数のうち、１回のスキャン後に何回スキャンしないかを指定します。skip_scan に指定できる範囲は [0, 9] です。

 \image html skip_scan_image.png 何回に１回だけ計測するか

 たとえば、ミラーの１回転が 100 [msec] のセンサで skip_scan に 1 を指定した場合、データの取得間隔は 200 [msec] になります。


 Example

      enum { CAPTURE_TIMES = 10 };
      urg_start_measurement(&urg, URG_DISTANCE, CAPTURE_TIMES, 0);

      for (i = 0; i < CAPTURE_TIMES; ++i) {
      int n = urg_get_distance(&urg, data, &time_stamp);

      \~japanese
      // 受信したデータの利用
      \~english
      // Processing of obtained data
      \~
      ...
      } 

  \see urg_get_distance(), urg_get_distance_intensity(), urg_get_multiecho(), urg_get_multiecho_intensity(), urg_stop_measurement()

 \ref urg_start_measurement() の計測を中断します。

 \param[in,out] urg URG センサ管理

 \retval 0 正常
 \retval <0 エラー


 Example

      urg_start_measurement(&urg, URG_DISTANCE, URG_SCAN_INFINITY, 0);
      for (int i = 0; i < 10; ++i) {
      urg_get_distance(&urg, data, NULL);
      }
      urg_stop_measurement(&urg); 

  \see urg_start_measurement()

 \param[in,out] urg URG センサ管理

 \retval >=0 タイムスタンプ [msec]
 \retval <0 エラー


 Example

      urg_start_time_stamp_mode(&urg);

      before_ticks = get_pc_msec_function();
      time_stamp = urg_time_stamp(&urg);
      after_ticks = get_pc_msec_function();

      \~japanese
      // タイムスタンプについての計算
      \~english
      // Processing of timestamp data
      \~
      ...

      urg_stop_time_stamp_mode(&urg); 

  詳しくは \ref sync_time_stamp.c を参照して下さい。