1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
//! Image plot

#[cfg(feature = "plotly_image")]
use image::{Pixel, RgbImage, RgbaImage};
#[cfg(feature = "plotly_ndarray")]
use ndarray::{Array, Ix2};
use plotly_derive::FieldSetter;
use serde::Serialize;

use crate::color::{Rgb, Rgba};
use crate::common::{Dim, HoverInfo, Label, LegendGroupTitle, PlotType, Visible};
use crate::private::{NumOrString, NumOrStringCollection};
use crate::Trace;

#[derive(Serialize, Clone, Copy, Debug)]
#[serde(untagged)]
pub enum PixelColor {
    Color3(u8, u8, u8),
    Color4(u8, u8, u8, f64),
}

/// A marker trait allowing several ways to describe the pixel data for an
/// `Image` trace.
pub trait ImageData {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>>;
}

impl ImageData for Vec<Vec<Rgb>> {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let mut out = Vec::with_capacity(self.len());
        for row in self {
            let mut new_row = Vec::with_capacity(row.len());
            for pixel in row {
                new_row.push(PixelColor::Color3(pixel.r, pixel.g, pixel.b))
            }
            out.push(new_row);
        }
        out
    }
}

impl ImageData for Vec<Vec<Rgba>> {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let mut out = Vec::with_capacity(self.len());
        for row in self {
            let mut new_row = Vec::with_capacity(row.len());
            for pixel in row {
                new_row.push(PixelColor::Color4(pixel.r, pixel.g, pixel.b, pixel.a))
            }
            out.push(new_row);
        }
        out
    }
}

#[cfg(feature = "plotly_image")]
impl ImageData for RgbImage {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let mut out = Vec::with_capacity(self.height() as usize);
        for row in self.rows() {
            let mut new_row = Vec::with_capacity(row.len());
            for pixel in row {
                let ch = pixel.channels();
                new_row.push(PixelColor::Color3(ch[0], ch[1], ch[2]))
            }
            out.push(new_row);
        }
        out
    }
}

#[cfg(feature = "plotly_image")]
impl ImageData for RgbaImage {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let mut out = Vec::with_capacity(self.height() as usize);
        for row in self.rows() {
            let mut new_row = Vec::with_capacity(row.len());
            for pixel in row {
                let ch = pixel.channels();
                new_row.push(PixelColor::Color4(
                    ch[0],
                    ch[1],
                    ch[2],
                    ch[3] as f64 / 255.0,
                ))
            }
            out.push(new_row);
        }
        out
    }
}

#[cfg(feature = "plotly_ndarray")]
impl ImageData for Array<(u8, u8, u8), Ix2> {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let height = self.shape()[0];
        let mut out = Vec::with_capacity(height);
        let pixels = self.map(|p| PixelColor::Color3(p.0, p.1, p.2));
        for row in pixels.rows() {
            out.push(row.to_vec());
        }
        out
    }
}

#[cfg(feature = "plotly_ndarray")]
impl ImageData for Array<(u8, u8, u8, f64), Ix2> {
    fn to_image_data(&self) -> Vec<Vec<PixelColor>> {
        let height = self.shape()[0];
        let mut out = Vec::with_capacity(height);
        let pixels = self.map(|p| PixelColor::Color4(p.0, p.1, p.2, p.3));
        for row in pixels.rows() {
            out.push(row.to_vec());
        }
        out
    }
}

#[derive(Serialize, Clone, Debug)]
#[serde(rename_all = "lowercase")]
pub enum ColorModel {
    RGB,
    RGBA,
    RGBA256,
    HSL,
    HSLA,
}

#[derive(Clone, Debug)]
pub enum ZSmooth {
    Fast,
    False,
}

impl Serialize for ZSmooth {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        match self {
            Self::Fast => serializer.serialize_str("fast"),
            Self::False => serializer.serialize_bool(false),
        }
    }
}

/// Construct an image trace.
///
/// # Examples
///
/// ```
/// use plotly::{color::Rgb, image::ColorModel, Image};
///
/// let b = Rgb::new(0, 0, 0);
/// let w = Rgb::new(255, 255, 255);
///
/// let z = vec![
///     vec![b, w],
///     vec![w, b],
/// ];
///
/// let trace = Image::new(z).color_model(ColorModel::RGB);
///
/// let expected = serde_json::json!({
///     "type": "image",
///     "z": [[[0, 0, 0], [255, 255, 255]], [[255, 255, 255], [0, 0, 0]]],
///     "colormodel": "rgb"
/// });
///
/// assert_eq!(serde_json::to_value(trace).unwrap(), expected);
/// ```
#[serde_with::skip_serializing_none]
#[derive(Serialize, Clone, Debug, FieldSetter)]
#[field_setter(box_self, kind = "trace")]
pub struct Image {
    #[field_setter(default = "PlotType::Image")]
    r#type: PlotType,

    #[field_setter(skip)]
    z: Option<Vec<Vec<PixelColor>>>,

    /// Sets the trace name. The trace name appear as the legend item and on
    /// hover.
    name: Option<String>,
    /// Determines whether or not this trace is visible. If
    /// `Visible::LegendOnly`, the trace is not drawn, but can appear as a
    /// legend item (provided that the legend itself is visible).
    visible: Option<Visible>,

    /// Sets the legend rank for this trace. Items and groups with smaller ranks
    /// are presented on top/left side while with `"reversed"
    /// `legend.trace_order` they are on bottom/right side. The default
    /// legendrank is 1000, so that you can use ranks less than 1000 to
    /// place certain items before all unranked items, and ranks greater
    /// than 1000 to go after all unranked items.
    #[serde(rename = "legendrank")]
    legend_rank: Option<usize>,
    /// Set and style the title to appear for the legend group.
    #[serde(rename = "legendgrouptitle")]
    legend_group_title: Option<LegendGroupTitle>,

    /// Sets the opacity of the trace.
    opacity: Option<f64>,
    /// Assigns id labels to each datum. These ids for object constancy of data
    /// points during animation. Should be an array of strings, not numbers
    /// or any other type.
    ids: Option<Vec<String>>,

    /// Set the image's x position.
    x0: Option<NumOrString>,
    /// Set the pixel's horizontal size.
    dx: Option<f64>,

    /// Set the image's y position.
    y0: Option<NumOrString>,
    /// Set the pixel's vertical size.
    dy: Option<f64>,

    /// Specifies the data URI of the image to be visualized. The URI consists
    /// of "data:image/[<media subtype>][;base64],<data>".
    source: Option<String>,

    /// Sets text elements associated with each (x,y) pair. If a single string,
    /// the same string appears over all the data points. If an array of
    /// strings the items are mapped in order to the this trace's (x,y)
    /// coordinates. If the trace `HoverInfo` contains a "text" flag and
    /// `hover_text` is not set, these elements will be seen in the hover
    /// labels.
    text: Option<Dim<String>>,
    /// Sets hover text elements associated with each (x,y) pair. If a single
    /// string, the same string appears over all the data points. If an
    /// array of strings, the items are mapped in order to the this trace's
    /// (x,y) coordinates. To be seen, trace `HoverInfo` must contain a
    /// "Text" flag.
    #[serde(rename = "hovertext")]
    hover_text: Option<Dim<String>>,
    /// Determines which trace information appear on hover. If `HoverInfo::None`
    /// or `HoverInfo::Skip` are set, no information is displayed upon
    /// hovering. But, if `HoverInfo::None` is set, click and hover events
    /// are still fired.
    #[serde(rename = "hoverinfo")]
    hover_info: Option<HoverInfo>,
    /// Template string used for rendering the information that appear on hover
    /// box. Note that this will override `HoverInfo`. Variables are
    /// inserted using %{variable}, for example "y: %{y}". Numbers are
    /// formatted using d3-format's syntax %{variable:d3-format}, for example
    /// "Price: %{y:$.2f}".
    /// https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#d3_format for details
    /// on the formatting syntax. Dates are formatted using d3-time-format's
    /// syntax %{variable|d3-time-format}, for example "Day:
    /// %{2019-01-01|%A}". https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md#format for details
    /// on the date formatting syntax. The variables available in
    /// `hovertemplate` are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data.
    /// Additionally, every attributes that can be specified per-point (the ones
    /// that are `arrayOk: true`) are available. Anything contained in tag
    /// `<extra>` is displayed in the secondary box, for example
    /// "<extra>{fullData.name}</extra>". To hide the secondary box
    /// completely, use an empty tag `<extra></extra>`.
    #[serde(rename = "hovertemplate")]
    hover_template: Option<Dim<String>>,

    /// Assigns extra meta information associated with this trace that can be
    /// used in various text attributes. Attributes such as trace `name`,
    /// graph, axis and colorbar `title.text`, annotation `text`
    /// `rangeselector`, `updatemenues` and `sliders` `label` text all support
    /// `meta`. To access the trace `meta` values in an attribute in the same
    /// trace, simply use `%{meta[i]}` where `i` is the index or key of the
    /// `meta` item in question. To access trace `meta` in layout
    /// attributes, use `%{data[n[.meta[i]}` where `i` is the index or key of
    /// the `meta` and `n` is the trace index.
    meta: Option<NumOrString>,
    /// Assigns extra data each datum. This may be useful when listening to
    /// hover, click and selection events. Note that, "scatter" traces also
    /// appends customdata items in the markers DOM elements
    #[serde(rename = "customdata")]
    custom_data: Option<NumOrStringCollection>,

    /// Sets a reference between this trace's x coordinates and a 2D cartesian x
    /// axis. If "x" ( the default value), the x coordinates refer to
    /// `Layout::x_axis`. If "x2", the x coordinates
    /// refer to `Layout::x_axis2`, and so on.
    #[serde(rename = "xaxis")]
    x_axis: Option<String>,
    /// Sets a reference between this trace's y coordinates and a 2D cartesian y
    /// axis. If "y" (the default value), the y coordinates refer to
    /// `Layout::y_axis`. If "y2", the y coordinates
    /// refer to `Layout::y_axis2`, and so on.
    #[serde(rename = "yaxis")]
    y_axis: Option<String>,

    /// Color model used to map the numerical color components described in `z`
    /// into colors. If `source` is specified, this attribute will be set to
    /// `rgba256` otherwise it defaults to `rgb`.
    #[serde(rename = "colormodel")]
    color_model: Option<ColorModel>,

    #[field_setter(skip)]
    #[serde(rename = "zmax")]
    z_max: Option<Vec<Vec<PixelColor>>>,

    #[field_setter(skip)]
    #[serde(rename = "zmin")]
    z_min: Option<Vec<Vec<PixelColor>>>,

    /// Picks a smoothing algorithm used to smooth `z` data. This only applies
    /// for image traces that use the `source` attribute.
    #[serde(rename = "zsmooth")]
    z_smooth: Option<ZSmooth>,

    /// Properties of label displayed on mouse hover.
    #[serde(rename = "hoverlabel")]
    hover_label: Option<Label>,

    /// Controls persistence of some user-driven changes to the trace:
    /// `constraintrange` in `parcoords` traces, as well as some `editable:
    /// True` modifications such as `name` and `colorbar.title`. Defaults to
    /// `layout.uirevision`. Note that other user-driven trace attribute changes
    /// are controlled by `layout` attributes: `trace.visible` is controlled
    /// by `layout.legend.uirevision`, `selectedpoints` is controlled
    /// by `layout.selectionrevision`, and `colorbar.(x|y)` (accessible with
    /// `config: {editable: True}`) is controlled by `layout.editrevision`.
    /// Trace changes are tracked by `uid`, which only falls back on trace
    /// index if no `uid` is provided. So if your app can add/remove traces
    /// before the end of the `data` array, such that the same trace has a
    /// different index, you can still preserve user-driven changes if you give
    /// each trace a `uid` that stays with it as it moves.
    #[serde(rename = "uirevision")]
    ui_revision: Option<NumOrString>,
}

impl Image {
    /// A 2-dimensional array in which each element is an array of 3 or 4
    /// numbers representing a color.
    pub fn new(z: impl ImageData) -> Box<Self> {
        Box::new(Self {
            z: Some(z.to_image_data()),
            ..Default::default()
        })
    }

    /// Array defining the higher bound for each color component. Note that the
    /// default value will depend on the colormodel. For the `rgb`
    /// colormodel, it is [255, 255, 255]. For the `rgba` colormodel, it is
    /// [255, 255, 255, 1]. For the `rgba256` colormodel, it is [255, 255, 255,
    /// 255]. For the `hsl` colormodel, it is [360, 100, 100]. For the
    /// `hsla` colormodel, it is [360, 100, 100, 1].
    pub fn z_max(mut self, z_max: impl ImageData) -> Box<Self> {
        self.z_max = Some(z_max.to_image_data());
        Box::new(self)
    }

    /// Array defining the lower bound for each color component. Note that the
    /// default value will depend on the colormodel. For the `rgb`
    /// colormodel, it is [0, 0, 0]. For the `rgba` colormodel, it is [0, 0, 0,
    /// 0]. For the `rgba256` colormodel, it is [0, 0, 0, 0]. For the `hsl`
    /// colormodel, it is [0, 0, 0]. For the `hsla` colormodel, it is [0, 0,
    /// 0, 0].
    pub fn z_min(mut self, z_min: impl ImageData) -> Box<Self> {
        self.z_min = Some(z_min.to_image_data());
        Box::new(self)
    }
}

impl Trace for Image {
    fn to_json(&self) -> String {
        serde_json::to_string(&self).unwrap()
    }
}

#[cfg(test)]
mod tests {
    use serde_json::{json, to_value};

    use super::*;

    #[test]
    fn test_serialize_pixel_color() {
        assert_eq!(
            to_value(PixelColor::Color3(255, 100, 150)).unwrap(),
            json!([255, 100, 150])
        );
        assert_eq!(
            to_value(PixelColor::Color4(150, 140, 190, 0.5)).unwrap(),
            json!([150, 140, 190, 0.5])
        );
    }

    #[test]
    fn test_serialize_color_model() {
        assert_eq!(to_value(ColorModel::RGB).unwrap(), json!("rgb"));
        assert_eq!(to_value(ColorModel::RGBA).unwrap(), json!("rgba"));
        assert_eq!(to_value(ColorModel::RGBA256).unwrap(), json!("rgba256"));
        assert_eq!(to_value(ColorModel::HSL).unwrap(), json!("hsl"));
        assert_eq!(to_value(ColorModel::HSLA).unwrap(), json!("hsla"));
    }

    #[test]
    fn test_serialize_z_smooth() {
        assert_eq!(to_value(ZSmooth::Fast).unwrap(), json!("fast"));
        assert_eq!(to_value(ZSmooth::False).unwrap(), json!(false));
    }

    #[test]
    fn test_serialize_image() {
        let b = Rgba::new(0, 0, 0, 0.5);
        let w = Rgba::new(255, 255, 255, 1.0);
        let image = Image::new(vec![vec![b, w, b, w, b], vec![w, b, w, b, w]])
            .name("image name")
            .visible(Visible::True)
            .legend_rank(1000)
            .legend_group_title(LegendGroupTitle::new("Legend Group Title"))
            .opacity(0.5)
            .ids(vec!["one"])
            .x0(0.0)
            .dx(1.0)
            .y0(2.0)
            .dy(3.0)
            .source("https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")
            .text("text")
            .text_array(vec!["text"])
            .hover_text("hover_text")
            .hover_text_array(vec!["hover_text"])
            .hover_info(HoverInfo::XAndYAndZ)
            .hover_template("hover_template")
            .hover_template_array(vec!["hover_template"])
            .meta("meta")
            .custom_data(vec!["custom_data"])
            .x_axis("x2")
            .y_axis("y2")
            .color_model(ColorModel::RGBA)
            .z_max(vec![vec![w, w, w, w, w], vec![w, w, w, w, w]])
            .z_min(vec![vec![b, b, b, b, b], vec![b, b, b, b, b]])
            .z_smooth(ZSmooth::Fast)
            .hover_label(Label::new())
            .ui_revision(6);

        let b = (0, 0, 0, 0.5);
        let w = (255, 255, 255, 1.0);
        let expected = json!({
            "type": "image",
            "z": [[b, w, b, w, b], [w, b, w, b, w]],
            "name": "image name",
            "visible": true,
            "legendrank": 1000,
            "legendgrouptitle": {"text": "Legend Group Title"},
            "opacity": 0.5,
            "ids": ["one"],
            "x0": 0.0,
            "dx": 1.0,
            "y0": 2.0,
            "dy": 3.0,
            "source": "https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg",
            "text": ["text"],
            "hovertext": ["hover_text"],
            "hoverinfo": "x+y+z",
            "hovertemplate": ["hover_template"],
            "meta": "meta",
            "customdata": ["custom_data"],
            "xaxis": "x2",
            "yaxis": "y2",
            "colormodel": "rgba",
            "zmax": [[w, w, w, w, w], [w, w, w, w, w]],
            "zmin": [[b, b, b, b, b], [b, b, b, b, b]],
            "zsmooth": "fast",
            "hoverlabel": {},
            "uirevision": 6,
        });

        assert_eq!(to_value(image).unwrap(), expected);
    }
}