Scan Process
The scanning process happens entirely through the TireTreadScanView
and should be performed in Landscape mode.
The TireTreadSDK
allows for a variety of options on how to set up the scan process. In the following sections we will show the most convenient and quick options to get started with scanning.
Setup with JSON config
The most convenient way to configure the TireTreadScanView
is via a JSON config located in your application’s asset folder. You can also use the full JSON string as an input.
The file name and the name used for the JSON config must be identical. |
-
Compose
-
XML + ViewBinding
@Composable
private fun Content() {
// You can pass the tire width as an integer
val tireWidth = 200
TireTreadScanView(context = this@ScanActivity,
config = "scan_config.json", //you can also use the full JSON string as an input!
tireWidth = tireWidth,
callback = object : TireTreadScanViewCallback {
// handle callback methods
}) {
// handle possible errors
}
}
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<io.anyline.tiretread.sdk.scanner.TireTreadScanView
android:id="@+id/tireTreadScanView"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</androidx.constraintlayout.widget.ConstraintLayout>
Setup with a config object
If there is a need for a more fine grained or dynamic configuration in code the scan process can be set up via a configuration class.
-
Compose
-
Xml + ViewBinding
@Composable
private fun Content() {
// You can pass the tire width as an integer
val tireWidth = 200
TireTreadScanView(context = this@ScanActivity,
config = TireTreadScanViewConfig().apply {
defaultUiConfig = DefaultUiConfig().apply {
tireOverlayConfig = TireOverlayConfig().apply {
visible = true
}
// ...
}
measurementSystem = MeasurementSystem.Imperial
scanSpeed = ScanSpeed.Fast
},
tireWidth = tireWidth,
callback = object : TireTreadScanViewCallback {
// handle callback methods
}) {
}
}
binding.tireTreadScanView.apply {
// You can pass the tire width as an integer
val tireWidth = 200
withScanConfig(tireTreadScanViewConfig = TireTreadScanViewConfig().apply {
defaultUiConfig = DefaultUiConfig().apply {
tireOverlayConfig = TireOverlayConfig().apply {
visible = true
}
// ...
}
measurementSystem = MeasurementSystem.Imperial
scanSpeed = ScanSpeed.Fast
},
tireWidth = tireWidth,
tireTreadScanViewCallback = object : TireTreadScanViewCallback {
// handle callback methods
}
) {
// handle initialization failed
}
setViewCompositionStrategy(
ViewCompositionStrategy.DisposeOnLifecycleDestroyed(
this@ScanActivity
)
)
}
Additional Context
The AdditionalContext
is an optional property which allows you to provide more context to a scan. This makes sense in a workflow, where a scan is connected to other TireTread scans or other information in a larger context.
Its initialization requires a TirePosition
.
The TirePosition
identifies the position where the tire is mounted on the vehicle, considering the primary direction of travel. E.g. the front left tire of a passenger car would be specified as axle=1, side=TireSide.Left, position_on_axle=1
and the rear right tire of a passenger car as axle=2
, side=TireSide.Right
, position_on_axle=1
The TirePosition
's parameters are as follows:
-
axle
: Number of the axle, whereas 1 is the front axle (in direction of travel). Its value must be at least 1. -
side
: Enum, representing the side where the Tire is located (Left, Center, Right). -
positionOnAxle
: Position on the axle, whereas 1 is the outermost tire and higher values represent the following inner tires. If the side is set tocenter
, 1 is the leftmost tire (in direction of travel), if there are multiple tires on the center axle. Its value must be at least 1.
If the AdditionalContext
is provided, it will also be returned with the results in the TreadDepthResult
object, in the measurement
property.
TirePosition initialization will throw an IllegalArgumentException if axle or positionOnAxle are 0.
|
Audio Feedback
The Tire Tread SDK can provide audio feedback to guide users through the scan process.
To make use of these audio feedbacks, your application needs to provide (and thus can customize) the audio files inside its Assets
folder.
The audio feedbacks (with their respective files names) on Android are played on:
-
Scan Started
-
tiretread_sound_start.wav
-
-
Scan Stopped
-
tiretread_sound_stop.wav
-
-
Phone too close to the Tire
-
tiretread_sound_beep_too_close.wav
-
-
Phone too distant from the Tire
-
tiretread_sound_beep_too_far.wav
-
The SDK only supports these file names, and the .wav
extension.
An example implementation, and the example audio files, can be found in our GitHub Example implementation.
To disable the audio feedback, remove these audio files from the applications' Assets folder or rename them. |
Make sure that your "ScanActivity" runs in Landscape mode. |
Start Scanning
In the previous example, we are not disabling the Default UI (disableDefaultUi
) in the TireTreadScanView. This means that the ScanView will draw and control all the required components for the scan process.
When using the default UI, your application only needs to implement behavior in a few callbacks from the SDK: onScanAbort
, onUploadCompleted
, onUploadFailed
, and onUploadAborted
. Jump to the Handling the SDK’s events section if you are using the default UI.
When not using the default UI, your application can define the UX of the entire scan process. For that, start by adding a button alongside with the TireTreadScanView. This button will be responsible for starting and stopping the scan process. Here is a Kotlin example with its functionality:
fun onClickedBtnStartScan(view: View) {
val scannerInstance = TireTreadScanner.instance
val btnStartScan = (view as Button)
if (!scannerInstance.isScanning) {
// Here we start scanning
scannerInstance.startScanning()
btnStartScan.text = "Stop"
} else {
btnStartScan.visibility = View.GONE
btnStartScan.isEnabled = false
btnStartScan.isClickable = false
// Here we stop scanning
scannerInstance.stopScanning()
}
}
The TireTreadScanner.instance
also provides the captureDistanceStatus
property, with which your application can check if the user is positioning the device at the correct distance from the tire. This property can be used to prevent scans from initiating at an incorrect distance, e.g.:
if (TireTreadScanner.instance.captureDistanceStatus == DistanceStatus.OK)
TireTreadScanner.instance.startScanning()
else {
Toast.makeText(
this,
"Move the phone to the correct position before starting.",
Toast.LENGTH_SHORT
).show()
}
The scanning process can be stopped at any time. If not manually stopped, the scan process is automatically stopped after 10 seconds. |
Besides the "Start/Stop" button, when not using the default UI, add also an "Abort" button (or e.g., an 'x' icon), through which the users can abort the Scan Process without waiting for the results. This button should call the TireTreadScanner.instance.abortScanning()
function.
Enabling volume keys to start scanning
Optionally can override the functionality of the phone’s volume buttons to start and stop the scan by adding this function to your Activity code.
override fun dispatchKeyEvent(event: KeyEvent): Boolean {
return when (event.keyCode) {
KeyEvent.KEYCODE_VOLUME_UP, KeyEvent.KEYCODE_VOLUME_DOWN -> {
if (event.action == ACTION_UP) return true
if (TireTreadScanner.instance.isScanning) {
TireTreadScanner.instance.stopScanning()
} else {
if (TireTreadScanner.instance.captureDistanceStatus == DistanceStatus.OK) TireTreadScanner.instance.startScanning()
else {
Toast.makeText(
this,
"Move the phone to the correct position before starting.",
Toast.LENGTH_SHORT
).show()
}
}
true
}
else -> super.dispatchKeyEvent(event)
}
}
Handling the SDK’s events
The TireTreadScanViewCallback
is the interface through which the TireTreadScanView
communicates back to your application. With these callbacks, you can react on changes and implement your own workflow around the scan process. The callbacks available are:
-
onScanStart
: Invoked when the scanning process begins -
onScanStop
: Invoked when the scanning process ends -
onScanAbort
: Invoked when the scanning process is aborted-
Should be implemented also when using the default UI
-
-
onImageUploaded
: Invoked after each frame is uploaded -
onUploadCompleted
: Invoked once all the frames were successfully uploaded for processing-
Should be implemented also when using the default UI
-
-
onUploadAborted
: Invoked when the upload process is aborted.-
Should be implemented also when using the default UI
-
-
onUploadFailed
: Invoked if any issue has occurred during upload-
Should be implemented also when using the default UI
-
-
onDistanceChanged
: Invoked whenever the distance between the device and the tire changes-
This information serves as a guide to assist your app’s users in scanning correctly
-
The callback "onFocusFound" will not be invoked - and should be used - on Android. |
Once your "myTireTreadScanView" object is available, add your callback implementation to it. In this example, we will use our own Activity as the callback implementation.
Implement the TireTreadScanViewCallback
interface, and override the desired methods, e.g.:
// Implement the TireTreadScanViewCallback interface
class MyScanActivity : AppCompatActivity(), TireTreadScanViewCallback {
private var aborted = false
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_scan)
val myTireTreadScanView = findViewById<TireTreadScanView>(R.id.tireTreadScanView)
myTireTreadScanView.scanViewCallback = this
}
// These callbacks should always be implemented
override fun onScanAbort(uuid: String?) {
super.onScanAbort(uuid)
Log.d("MY_APP", "scan was aborted!")
aborted = true
// Leave the scan activity
finish()
}
override fun onUploadCompleted(uuid: String?) {
super.onUploadCompleted(uuid)
Log.d("MY_APP", "upload is completed!")
// redirect to the result loading screen
if (!aborted && !uuid.isNullOrEmpty()) {
openLoadAndResultScreen(uuid)
}
}
override fun onUploadAborted(uuid: String?) {
super.onUploadAborted(uuid)
mainHandler.post {
Toast.makeText(applicationContext, "Upload Aborted", Toast.LENGTH_SHORT).show()
}
finish()
}
override fun onUploadFailed(uuid: String?, exception: Exception) {
super.onUploadFailed(uuid, exception)
Log.e("MY_APP", "onUploadFailed: ", exception)
Toast.makeText(applicationContext, "Upload Failed. Check your internet and try again.", Toast.LENGTH_SHORT).show()
finish()
}
// When not using the 'default UI', you will need to implement (at least) the following functions to control the scan process
fun startScanning(view: View) {
TireTreadScanner.instance.startScanning()
}
fun stopScanning() {
TireTreadScanner.instance.stopScanning()
}
fun abortScan() {
TireTreadScanner.instance.abortScanning()
finish()
}
// When not using the "default UI", use this callback to provide guidance to the users
override fun onDistanceChanged(uuid: String?, previousStatus: DistanceStatus, newStatus: DistanceStatus, previousDistance: Float, newDistance: Float,
) {
super.onDistanceChanged(uuid, previousStatus, newStatus, previousDistance, newDistance)
val measurementSystem = if (PreferencesUtils.shouldUseImperialSystem(this@ScanActivity)) {
MeasurementSystem.Imperial
} else {
MeasurementSystem.Metric
}
// newDistance will be in millimeters if you choose Metric, or in inches, if you choose Imperial
val distanceString: String = if (measurementSystem == MeasurementSystem.Imperial) {
"$newDistance in"
} else {
"${(newDistance / 10).toInt()} cm"
}
var message = ""
message = when (newStatus) {
DistanceStatus.TOO_CLOSE -> {
"Increase Distance: "
}
DistanceStatus.TOO_FAR -> {
"Decrease Distance: "
}
else -> {
"Distance OK"
}
}
message += distanceString
findViewById<TextView>(R.id.tvDistance).text = message
}
}
You can check out our GitHub example repository for a full implementation of the Scan Activity. |
Check out the next section to learn how to handle the measurement results after the scan process is finished.