non-tinted `stateImage` to support camera devices

[landlessness]

To support a camera device we would like to use the actual photos from the camera as the stateImage instead of a typical icon image.

For example, the demo server called dublin now has a mock camera device. the stateImage is set to http://www.zettaapi.org/public/demo/dublin.jpg, which is meant to be a mock still image of a live camera feed.

To support this we will need a way in the API to indicate when we want and don't want tinting on the stateImage. I think by default we'll want tinting off. To future proof ourselves for additional image metadata I think we also ought turn the value of stateImage into a sub object instead of just a string.

Something like this for a camera with no tinting:

{
  "stateImage": {
    "url": "http://www.zettaapi.org/public/demo/dublin.jpg",
  }
}

And like this for a traditional icon with tinting:

{
  "stateImage": {
    "url": "http://www.zettaapi.org/icons/light-off.png",
    "tintColor": {"decimal": {"red": 255, "green": 202, "blue": 0}, "hex": "#FFCA00"}
  }
}

In this second case we are no longer relying on foregroundColorto drive image tinting. So maybe what we call foregroundColor now ought to become textColor? backgroundColor could remain the same.

Instead of this:

We see this in the app:

[benpackard]

@landlessness My first thought was to consider whether the tintColor of the image shouldn't be named the same as that used for coloring buttons and text (foregroundColor right now, maybe simply color would be more versatile). Then the image could specify its own foregroundColor, or by default inherit that of it's parent (the device). The benefit is that it is flexible and consistent - just as a device can override the colors of its server, now an individual button, label, or (as in this case) an image can do the same to a device. The obvious downside is that it doesn't quite support what you're requesting since you want the default coloring for an image to be nil, which seems like a reasonable expectation.

I think on balance what you have is better. I'm not sure about replacing foregroundColor with textColor since the buttons actually color their background color using this value. Furthermore, I would probably expect the text you see in white above to be the more likely elements affected by textColor.

Another thought - the iOS nomenclature for distinguishing between image tinting modes is original and template, the latter being the version that re-colors the image. The tintColor is then an independent attribute. So perhaps foregroundColor remains (including the cascading behavior from my first paragraph), but images have a tintMode which is original by default. template can be specified when required. Or, perhaps simpler, an image has a boolean colorTinted attribute which is false by default. When true, it would use the most specific foregroundColor it can find, whether specified by the image, the device or the server.

//this image would not be tinted since 'tintMode' is 'original' by default
{
  "stateImage": {
    "url": "http://www.zettaapi.org/icons/light-off.png",
  }
}

//this image would be tinted according to the device's 'foregroundColor'
{
  "stateImage": {
    "url": "http://www.zettaapi.org/icons/light-off.png",
    "tintMode": "template"
  }
}

//this image is tinted to a custom color
{
  "stateImage": {
    "url": "http://www.zettaapi.org/icons/light-off.png",
    "foregroundColor": {"decimal": {"red": 255, "green": 202, "blue": 0}, "hex": "#FFCA00"},
    "tintMode": "template"
  }
}

//this image is not tinted - a color is specified but the default tint mode is 'original', so it doesn't do anything.
{
  "stateImage": {
    "url": "http://www.zettaapi.org/icons/light-off.png",
    "foregroundColor": {"decimal": {"red": 255, "green": 202, "blue": 0}, "hex": "#FFCA00"}
  }
}

Mostly just splurging some ideas here, not especially attached to any of them.

[landlessness]

@benpackard i like your approach. we'll keep foregroundColor with cascading scope. and use tintMode as the param name. one tweak, though. because most of our images will be icons instead of photos, let's make the default "tintMode": "template". The API will have to specify "tintMode": "original" if it doesn't want tinting applied.

[benpackard]

@landlessness Sounds good, are there any devices that have this set yet?

[landlessness]

I'm setting up a new staging environment so that we can get a better Dev flow for API changes while not disrupting existing demos.

It will be at http://stage.zettaapi.org

I'll let you know once I have it up.

Sent from my iPhone

On Mar 25, 2016, at 9:52 AM, Ben Packard notifications@github.com wrote:

@landlessness Sounds good, are there any devices that have this set yet?

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub

[landlessness]

@benpackard i now have one server on stage that has the new API for stateImage. all the devices have tinting still. I'll let you know once I get the mock camera going with a non tinted image.

[landlessness]

@benpackard the detroit server on stage now has a camera that includes a "tintMode": "original" stateImage if the state is ready and a "tintMode": "template" stateImage if the state is not-ready: http://stage.zettaapi.org

[landlessness]

so if you toggle with the make-ready and make-not-ready buttons you should be able to see both approaches in one device.

[benpackard]

Got it, thanks.