search

j0ono0 / pinout

An open source Python package that generates hardware pinout diagrams as SVG images.
https://pinout.readthedocs.io
MIT License
390 stars 18 forks source link

Random thoughts on 0.0.9 #16

Closed arturo182 closed 3 years ago

arturo182 commented 3 years ago

These are a few random thoughts I had while working with 0.0.9, not sure how useful they are, so take them as you will, 0.0.9 is great as-is anyways! :)

Feels a bit weird to have YAML and the py files, in the main branch the data is in py and just the style stuff is in CSS, that makes sense to me. It also feels weird that half of the legend info (i.e. position) is in py but then width and radius are in YAML. I guess my confusion comes from the fact that the YAML mixes two types of information: styles (colors, fonts, etc.) and data (tag names).

It feels a bit weird that the tags info is spread between YAML and py, I get that the categories param for add_legend is optional and only useful if you want to hide some tags, but if you want to add a new tag, you have to do it in two places. Maybe it would be better to add a visible property to the tags in YAML, have them be true by default s you only set false for the ones you want to hide.

I wish I could provide colors as #112233 hex values for the tags :D

I was surprised to find out that the labels don't adjust their width to fit the whole text they contain, but I do understand it might be hard to calculate that dynamically with custom fonts, weights, and all that. Not a big deal.

It would be great to be able to provide background AND text colors for tags as I did in my fork. Some colors don't work as well with black text, but some do.

Can't wait to be able to add custom text in random places!

Thanks!

arturo182 commented 3 years ago

Two more:

  1. On the main branch you can use CSS to add a margin to the diagram so there is some breathing room in the SVG, not sure if there's a way to do this in 0.0.9
  2. Would love an option to export as png, with specified background color (or transparent), specified margins, and size.
j0ono0 commented 3 years ago

Thanks for giving pinout a workout. The feedback and real user experience is invaluable. I'll type out some thoughts here - to help clarify things to myself as much as a response to your thoughts (so please excuse rambling)...

[edit] rambling finished - I'll do a second post for the small stuff

TL;DR: The confused implementation reflects early project indecision. Critical feedback and more iterations are needed and under way.

YAML: Initial thoughts when I was trying this out was ALL user data (content and styling) could be supplied as yaml - A user could generate a diagram from the command-line, no python script at all. I'm not sold on my own idea and currently I've settled on 'configuration' in yaml and content in python. As a hangover from my initial thought, the division not well defined. The legend content is an example of trying out content-as-yaml, I like the concise and clear format but thematically it is confusing and needs resolving one way or the other. All this might be heading down the wrong track though - possibly everything should described in native python with 'cookbook' suggestions of alternative data handling. The user could then choose their mix to suit.

YAML and inline styles: "path of least resistance" resulted with yaml data being inserted as inline attributes into templates effectively removing the css requirement. Parsing yaml to css and implementing as an embedded or external asset has merits for online destinations and is a serious consideration.

CSS: There is still an important place for CSS in pinout, it's removal entirely has been a 'friendly fire' incident - the 'tags' (used as css classes) will be reinstated at some point. I envisage advance users might further style or add interactive aspects for browser based destinations.

j0ono0 commented 3 years ago

off the top of my head... text color in labels can be controlled in config:

pinlabel:
    label:
        text:
            fill: [<R>, <G>, <B>]

hex colors: yes, agreed it should go in. I semi-looked into this already investigating alpha transparency. abandoned progress on discovering SVG doesn't support alpha in colors (eg rgba and the hex equivalent). I should auto detect the alpha value and populate fill-opacity attribute too.

padding on the edge: yes, needs addressing to make output a 'finished document'. poor-work-a-round would be to place the diagram in a wrapper component. wrapper sits at (0,0) whilst diagram can be moved to (x,y) as suits. wrapper = diagram.Component() diagram = diagram.Diagram(x=10, y=10) wrapper.children.append(diagram)

png export: agreed, it'd be useful for me too. Research so far suggests pycairo is the go-to package for this. Open to suggestion on this.

Widths and text: It doesn't seem possible to determine the width of text accurately so elements do not auto adjust to fit. potential solutions I've thought about:

davidoccam commented 3 years ago

In order to alleviate the color definition issue in config.yaml I have included the following suggestion HTML color names The extended colors are the result of merging specifications from HTML 4.01, CSS 2.0, SVG 1.0 and CSS3 User Interfaces (CSS3 UI)

Pink colors

color: &MediumVioletRed [199, 21, 133] color: &DeepPink [255, 20, 147] color: &PaleVioletRed [219, 112, 147] color: &HotPink [255, 105, 180] color: &LightPink [255, 182, 193] color: &Pink [255, 192, 203]

Red colors

color: &DarkRed [139, 0, 0] color: &Red [255, 0, 0] color: &Firebrick [178, 34, 34] color: &Crimson [220, 20, 60] color: &IndianRed [205, 92, 92] color: &LightCoral [240, 128, 128] color: &Salmon [250, 128, 114] color: &DarkSalmon [233, 150, 122] color: &LightSalmon [255, 160, 122]

Orange colors

color: &OrangeRed [255, 69, 0] color: &Tomato [255, 99, 71] color: &DarkOrange [255, 140, 0] color: &Coral [255, 127, 80] color: &Orange [255, 165, 0]

Yellow colors

color: &DarkKhaki [189, 183, 107] color: &Gold [255, 215, 0] color: &Khaki [240, 230, 140] color: &PeachPuff [255, 218, 185] color: &Yellow [255, 255, 0] color: &PaleGoldenrod [238, 232, 170] color: &Moccasin [255, 228, 181] color: &PapayaWhip [255, 239, 213] color: &LightGoldenrodYellow [250, 250, 210] color: &LemonChiffon [255, 250, 205] color: &LightYellow [255, 255, 224]

Brown colors

color: &Maroon [128, 0, 0] color: &Brown [165, 42, 42] color: &SaddleBrown [139, 69, 19] color: &Sienna [160, 82, 45] color: &Chocolate [210, 105, 30] color: &DarkGoldenrod [184, 134, 11] color: &Peru [205, 133, 63] color: &RosyBrown [188, 143, 143] color: &Goldenrod [218, 165, 32] color: &SandyBrown [244, 164, 96] color: &Tan [210, 180, 140] color: &Burlywood [222, 184, 135] color: &Wheat [245, 222, 179] color: &NavajoWhite [255, 222, 173] color: &Bisque [255, 228, 196] color: &BlanchedAlmond [255, 235, 205] color: &Cornsilk [255, 248, 220]

Green colors

color: &DarkGreen [0, 100, 0] color: &Green [0, 128, 0] color: &DarkOliveGreen [85, 107, 47] color: &ForestGreen [34, 139, 34] color: &SeaGreen [46, 139, 87] color: &Olive [28, 128, 0] color: &OliveDrab [107, 142, 35] color: &MediumSeaGreen [60, 179, 113] color: &LimeGreen [50, 205, 50] color: &Lime [0, 255, 0] color: &SpringGreen [0, 255, 127] color: &MediumSpringGreen [0, 250, 154] color: &DarkSeaGreen [143, 188, 143] color: &MediumAquamarine [102, 205, 170] color: &YellowGreen [154, 205, 50] color: &LawnGreen [124, 252, 0] color: &Chartreuse [127, 255, 0] color: &LightGreen [144, 238, 144] color: &GreenYellow [173, 255, 47] color: &PaleGreen [152, 251, 152]

Cyan colors

color: &Teal [0, 128, 128] color: &DarkCyan [0, 139, 139] color: &LightSeaGreen [32, 178, 170] color: &CadetBlue [95, 158, 160] color: &DarkTurquoise [0, 206, 209] color: &MediumTurquoise [72, 209, 204] color: &Turquoise [64, 224, 208] color: &Aqua [0, 255, 255] color: &Cyan [0, 255, 255] color: &Aquamarine [127, 255, 212] color: &PaleTurquoise [175, 238, 238] color: &LightCyan [224, 255, 255]

Blue colors

color: &Navy [0, 0, 128] color: &DarkBlue [0, 0, 139] color: &MediumBlue [0, 0, 205] color: &Blue [0, 0, 255] color: &MidnightBlue [25, 25, 112] color: &RoyalBlue [65, 105, 225] color: &SteelBlue [70, 130, 180] color: &DodgerBlue [30, 144, 255] color: &DeepSkyBlue [0, 191, 255] color: &CornflowerBlue [100, 149, 237] color: &SkyBlue [135, 206, 235] color: &LightSkyBlue [135, 206, 250] color: &LightSteelBlue [176, 196, 222] color: &LightBlue [173, 216, 230] color: &PowderBlue [176, 224, 230]

Purple, violet, and magenta colors

color: &Indigo [75, 0, 130] color: &Purple [128, 0, 128] color: &DarkMagenta [139, 0, 139] color: &DarkViolet [148, 0, 211] color: &DarkSlateBlue [72, 61, 139] color: &BlueViolet [138, 43, 226] color: &DarkOrchid [153, 50, 204] color: &Fuchsia [255, 0, 255] color: &Magenta [255, 0, 255] color: &SlateBlue [106, 90, 205] color: &MediumSlateBlue [123, 104, 238] color: &MediumOrchid [186, 85, 211] color: &MediumPurple [147, 112, 219] color: &Orchid [218, 112, 214] color: &Violet [238, 130, 238] color: &Plum [221, 160, 221] color: &Thistle [216, 191, 216] color: &Lavender [230, 230, 250]

White colors

color: &MistyRose [255, 228, 225] color: &AntiqueWhite [250, 235, 215] color: &Linen [250, 240, 230] color: &Beige [245, 245, 220] color: &WhiteSmoke [245, 245, 245] color: &LavenderBlush [255, 240, 245] color: &OldLace [253, 245, 230] color: &AliceBlue [240, 24, 255] color: &Seashell [255, 245, 238] color: &GhostWhite [248, 248, 255] color: &Honeydew [240, 255, 240] color: &FloralWhite [255, 250, 240] color: &Azure [240, 255, 255] color: &MintCream [245, 255, 250] color: &Snow [255, 250, 250] color: &Ivory [255, 255, 240] color: &White [255, 255, 255]

Gray and black colors

color: &Black [0, 0, 0] color: &DarkSlateGray [47, 79, 79] color: &DimGray [105, 105, 105] color: &SlateGray [112, 128, 144] color: &Gray [128, 128, 128] color: &LightSlateGray [119, 136, 153] color: &DarkGray [169, 169, 169] color: &Silver [192, 192, 192] color: &LightGray [211, 211, 211] color: &Gainsboro [220, 220, 220]

Usage tags:

#   title: <title>
#   color: [<0-255>, <0-255>, <0-255>]

analog:
  title: Analog
  color: *Silver

dac:
  title: DAC
  color: *MediumPurple

comms:
  title: Communication
  color: *SandyBrown .....etc.
j0ono0 commented 3 years ago

Nice extension with colours. The circles I'm in make no use of the pre-named colours available in web so I'm a bit blind to their use or potential popularity to other users. I had no idea there were even so many of them!

I have some similar-ish styling ideas but they are a long way off with other fundamental changes getting priority - The crux of them involves providing a library of stylistic 'themes' and tools to help with legibility and accessibility.

j0ono0 commented 3 years ago

I think reinstating css and removing yaml has resolved much of confusion. A few revisions later I'm still feeling it was the right move too. Closing this one but feel free to open new issues to reraise aspects of these (or new) thoughts.