Following the MAVLink Camera API call conversation, I put together a draft XML camera definition file. This is by no means complete or even close to it. It’s just a starting point so we can discuss what goes in, how to format it, etc.
I put this together from the perspective of building an UI offering the user the options available to set the camera. Given the vast number of different cameras with different capabilities, I tried to keep a minimum set of options that would be common to most cameras and options that are relevant in this context. For example, I felt unnecessary to include options related to things like “Flash”, which is quite unlikely to be used. With that said, don’t take my word for it. If someone has a compelling reason to add it, we can add it.
Nothing is fixed. Not even the format. XML is easier to “read” but if the majority decides it should be Json (or something else), I’m open to anything.
The idea is to describe the camera, list the settings and the options for each setting. The GCS sends a MAVLink message requesting the camera settings and an URL is returned. That URL would point to this file. In addition to the URL, the response would also include a version for the definition file. That way, if the GCS already has it cached, it won’t need to download it again. The GCS can then build the UI on the fly based on the information contained within the definition file.
Options have an “index” (the numerical value used in their respective MAVLink command) and the text used to fill the UI elements. A setting may also have a “Title” to be used in the UI. There can be one or more “settings” element in order to deal with localization. Each element defines a set of settings for a given locale. If a desired language is not found, the default is used.
Most things are optional. For example, if the camera has no setting for “Aspect Ratio”, the element is simply not included. The options within a setting are completely up to the camera. The GCS will simply present the list and use the “index" when setting the values in the MAVLink command.
Note that all settings in the final list will need a counterpart MAVLink command. See CAMERA_SETTINGS for what is there now.
We need to sort out how to define exclusion rules. For instance, when you set the camera’s exposure mode to “Auto”, usually you don’t change ISO, Shutter Speed or Aperture. That’s what’s “Auto” is for. However, you are allowed to change “Exposure Compensation” (EV Value). When in “Manual” mode, the opposite is true.
I’ve added “Metering Mode” as this is common in most cameras. I’m not sure about the value of it though. This could be a case like “Flash” options described above. It may not apply in this context. Anything other than “Average” would require further settings, which can easily turn this into an unmanageable nightmare. I’m open to opinions.
<camera>
<description>
<infoVersion>1</infoVersion>
<cameraModel>Super Duper SDII</cameraModel>
<manufacturerName>Super Duper Inc.</manufacturerName>
<minFocalLength>12</minFocalLength>
<maxFocalLength>12</maxFocalLength>
<sensorWidthPixels>4000</sensorWidthPixels>
<sensorHeightPixels>3000</sensorHeightPixels>
<sensorWidth>12.4</sensorWidth>
<sensorHeight>9.3</sensorHeight>
<hasVideoStream>1</hasVideoStream>
</description>
<settings locale="en_US" default="1">
<mode title="Camera Mode" command="530" parameter="2">
<value index="0">Still</value>
<value index="1">Movie</value>
</mode>
<videoStream>
<size title="Stream Resolution" command="???" parameter="???">
<value index="0">480P</value>
<value index="1">720P</value>
<value index="2">1080P</value>
</size>
</videoStream>
<exposure>
<mode title="Exposure Mode" command="523" parameter="5">
<value index="0">Program Auto</value>
<value index="1">Auto</value>
<value index="2">Shutter Priority</value>
<value index="3">Aperture Priority</value>
<value index="4">Manual</value>
</mode>
<aperture title="Aperture" command="523" parameter="2">
<value index="0">1.4</value>
<value index="1">1.8</value>
<value index="2">2.0</value>
<value index="3">2.2</value>
<value index="4">2.4</value>
</aperture>
<shutter title="Shutter Speed" command="523" parameter="3">
<value index="0">1s</value>
<value index="1">1/8</value>
<value index="2">1/15</value>
<value index="3">1/30</value>
<value index="4">1/60</value>
<value index="5">1/125</value>
<value index="6">1/250</value>
<value index="7">1/500</value>
<value index="8">1/1000</value>
</shutter>
<iso title="ISO" command="523" parameter="4">
<value index="0">100</value>
<value index="1">200</value>
<value index="2">400</value>
<value index="3">800</value>
<value index="4">1600</value>
<value index="5">3200</value>
</iso>
<ev tile="Exposure Compensation" command="523" parameter="6">
<value index="0">-2.0</value>
<value index="1">-1.5</value>
<value index="2">-1.0</value>
<value index="3">-0.5</value>
<value index="4">0</value>
<value index="5">+0.5</value>
<value index="6">+1.0</value>
<value index="7">+1.5</value>
<value index="8">+2.0</value>
</ev>
<metering title="Metering Mode" command="524" parameter="3">
<value index="0">Average</value>
<value index="1">Center</value>
<value index="2">Spot</value>
</metering>
</exposure>
<color title="Color Mode" command="524" parameter="6">
<value index="0">Neutral</value>
<value index="1">Vivid</value>
<value index="2">Black and White</value>
</color>
<stabilization title="Image Stabilization" command="???" parameter="???">
<value index="0">Off</value>
<value index="1">On</value>
</stabilization>
<whiteBalance title="White Balance" command="523" parameter="7">
<value index="0">Auto</value>
<value index="1">Daylight</value>
<value index="2">Shade</value>
<value index="3">Cloudy</value>
<value index="4">Incandescent</value>
<value index="5">Fluorescent</value>
</whiteBalance>
<still>
<aspectRatio title="Aspect Ratio" command="???" parameter="???">
<value index="0">16:9</value>
<value index="1">4:3</value>
<value index="2">3:2</value>
<value index="3">1:1</value>
</aspectRatio>
<format title="Image Format" command="524" parameter="4">
<value index="0">JPEG</value>
<value index="1">RAW</value>
<value index="2">RAW + JPEG</value>
</format>
</still>
<movie>
<format title="Movie Format" command="???" parameter="???">
<value index="0">MP4</value>
<value index="1">MOV</value>
<value index="2">MPEG</value>
</format>
<size title="Movie Resolution" command="???" parameter="???">
<value index="0">3840x2160 30p</value>
<value index="1">3840x2160 24p</value>
<value index="2">1920x1080 60p</value>
<value index="3">1920x1080 30p</value>
<value index="4">1920x1080 24p</value>
</size>
<audio title="Audio Recording" command="530" parameter="3">
<value index="0">Off</value>
<value index="1">On</value>
</audio>
</movie>
</settings>
</camera>