Oops. I already noted I made a mistake. The ImageView class contains a pq.GraphicsView attribute, not a QGraphicsView attribute. I fixed it. I changed one line and half the classes have a different location lol.

This looks great, and is really useful! Could I suggest referencing the image as a page in the docs, with a one-liner saying what the colors, diamonds and arrows represent?

@titusjan Sorry I haven't followed up, we're still crafting our proposal for the grant we're applying for, and I'm trying to wrap up my PR from forever ago (1318); ... I want to experiment and see what this looks like with more of a hierarchy.

The other thing I'm going to want to see if viable is making a dark mode variant; I embed pyqtgraph docs within dash and it looks like this presently:

I think having one image that works for both light and dark mode won't work, and I'm not sure how "easy" it would be to have multiple images that the docs can pick from for this sort of thing either...

Sorry I haven't followed up

No worries @j9ac9k. I understand that maintaining PyQtGraph takes a lot of your time. I'm already impressed by the amount of time you spend on it.

I want to experiment and see what this looks like with more of a hierarchy.

What do you mean by this? If you mean using PlantUML name spaces then I would say don't do it :-)
I tried this in the beginning and I think this makes it very cluttered and unclear (see below). This is because the Qt classes and PyQtGraph classes are at many different levels in the dependency graph. It's not case that the Qt classes are on top and the PyQtGraph classes are at the bottom.

If you make a dark mode variant, please use different colors for the inheritance lines and the aggregation lines. This greatly improves the readability IMO.

No worries @j9ac9k. I understand that maintaining PyQtGraph takes a lot of your time. I'm already impressed by the amount of time you spend on it.

The contributors make it worth the effort 👍🏻

Regarding the hierarchy, I definitely would want the Qt and PyQtGraph objects together (to better highlight their relationship to one another). I meant that the inheritance is demonstrated via vertical spacing.

I just sketched something out on a tablet, hopefully it makes a bit more sense.

Idea here being that the the "parent" objects are at the top, and the inheritance flows in a vertical space. From the looks of your most recent screenshot, it looks like you largely have that (you just have the Qt and PyQtGraph classes also separated).

re-looking at my picture, I want to point out that GraphicsItem, QGraphicsView and QGraphicsScene should likely be laid out horizontally at the "top" of the plot, not vertically as I have done (did this due to my tablet being in portrait mode, ...probably should have rotated it first :|

Idea here being that the the "parent" objects are at the top, and the inheritance flows in a vertical space. From the looks of your most recent screenshot, it looks like you largely have that

...

I want to point out that GraphicsItem, QGraphicsView and QGraphicsScene should likely be laid out horizontally at the "top" of the plot

In the first two screen shots parent classes are positioned above their children in all cases. Also the GraphicsItem, QGraphicsView and QGraphicsScene classes are nearly at the top. It's just that their parents and the ImageView class (which contains a QGraphicsScene) are located above them.

I'm curious to see your diagrams when they are finished.

First off, I just want to reiterate, this diagram is amazing, and very much needed. I want this merged into the documentation, thanks for this PR.

In the first two screen shots parent classes are positioned above their children in all cases. Also the GraphicsItem, QGraphicsView and QGraphicsScene classes are nearly at the top. It's just that their parents and the ImageView class (which contains a QGraphicsScene) are located above them.

You do have that, I got a little crossed up by the curved/angled/overlapping lines, my apologies. I had a mental model of lines that were straight at right angles (horizontal or vertical); might not be best in this case though. Also not sure how feasible it would be to not have overlapping darker lines for inheritance (for the lighter colored lines will have to overlap, but given what they represent, I think that's ok).

I'm talking myself in and out of the benefits of having QObject listed, on one hand, (just about) everything except GraphicsItem points to QObject, and QObject does have methods/properties which could be of use; probably should keep it.

and that diagram reminded me...

We should probably modify PlotItem to use GraphicsLayout for a layout instead of QGraphicsGridLayout.... but that's a whole other issue!

@j9ac9k ：

The picture of your help file is very good!

Where can I get it?

Hi @titusjan I'm playing with this in the PlantUML website; is there a UML example/tutorial/guide you like? I want to experiment with this some.

@j9ac9k I only read the Class Diagram chapter of the reference guide. It contains a lot of examples so it worked for me.

ok, I'm messing with it now, PlantUML is really punishing if you try and force the situation with a layout isn't it...

The following UML code generates this:

@startuml
' Made in PlantUml. You can try it out here: http://plantuml.com/plantuml
' Based on commit eb7a60fcf83cd4e7a41ae5955e57935e39928fbd


hide empty members
hide circles
hide stereotypes
top to bottom direction

skinparam class {
    BorderColor Black
    ArrowColor Black

    ' Using stereotypes to define the background colors
    BackgroundColor<<qt>> #e5f2da
    BackgroundColor<<pg>> #e5e5f4
}
skinparam shadowing false


'----------- Qt package ----------`


class QGraphicsGridLayout <<qt>>

class QGraphicsItem <<qt>>

class QGraphicsLayout <<qt>>

class QGraphicsLayoutItem <<qt>>

class QGraphicsObject <<qt>>

class QGraphicsScene <<qt>> { 
    items 
}

class QGraphicsWidget <<qt>>

class QGraphicsView <<qt>> {
    scene
}

class QObject <<qt>>

class QPaintDevice <<qt>>

class QWidget <<qt>>


'----------- PyQtGraph package ----------`


class GraphicsItem <<pg>>

class GraphicsLayout <<pg>> {
    layout
}

class GraphicsLayoutWidget <<pg>> {
    graphicsLayout
}

class GraphicsObject <<pg>>

class GraphicsView <<pg>>

class GraphicsWidget <<pg>> 

class ImageItem <<pg>>

class ImageView <<pg>> {
    graphicsView
    imageItem
    scene
    view
}

class PlotCurveItem <<pg>>

class PlotDataItem <<pg>> {
    curve
    scatter
}

class PlotItem <<pg>> {
    layout
    vb
}

class PlotWidget <<pg>> {
    plotItem
}

class ScatterPlotItem <<pg>>

class ViewBox <<pg>>


'---------- Inheritance within Qt ----------'
QGraphicsItem <-- QGraphicsObject
QObject <-- QGraphicsObject
'QGraphicsItem -[hidden]> QObject
QGraphicsObject <-- QGraphicsWidget
QGraphicsLayoutItem <-- QGraphicsWidget
QGraphicsLayoutItem <-- QGraphicsLayout
QGraphicsLayout <-- QGraphicsGridLayout
QPaintDevice <-- QWidget
QObject <-- QWidget
QObject <-- QGraphicsScene
QWidget <-- QGraphicsView


'---------- Inheritance from Qt to PyQtGraph ----------'
QGraphicsWidget <-- GraphicsWidget
QGraphicsObject <-- GraphicsObject
QGraphicsView <-- GraphicsView
QWidget <---- ImageView


'---------- Inheritance  within PyQtGraph ----------'
GraphicsItem <-- GraphicsObject
GraphicsItem <-- GraphicsWidget
GraphicsWidget <-- GraphicsLayout
GraphicsWidget <-- PlotItem
GraphicsWidget <-- ViewBox
GraphicsObject <--- ScatterPlotItem
GraphicsObject <--- PlotCurveItem
GraphicsObject <--- ImageItem
GraphicsObject <-- PlotDataItem
GraphicsView <-- PlotWidget
GraphicsView <-- GraphicsLayoutWidget


'---------- Aggregation ----------'

' Shorter arrow so at same height in the diagram
QGraphicsScene::items o-[norank]- QGraphicsItem                      #b8b8b8
QGraphicsView::scene o-[norank]- QGraphicsScene                      #b8b8b8

' Longer (regular) arrows
PlotWidget::plotItem o-[norank]- PlotItem                           #b8b8b8
GraphicsLayoutWidget::graphicsLayout o-[norank]- GraphicsLayout     #b8b8b8
PlotDataItem::curve o-[norank]- PlotCurveItem                       #b8b8b8
PlotDataItem::scatter o-[norank]- ScatterPlotItem                   #b8b8b8
PlotItem::vb o-[norank]- ViewBox                                    #b8b8b8
PlotItem::layout o-[norank]- QGraphicsGridLayout                    #b8b8b8
GraphicsLayout::layout o-[norank]- QGraphicsGridLayout              #b8b8b8
ImageView::graphicsView o-[norank]- GraphicsView                    #b8b8b8
ImageView::imageItem o-[norank]- ImageItem                          #b8b8b8
ImageView::scene o-[norank]- QGraphicsScene                         #b8b8b8
ImageView::view o-[norank]- ViewBox                                 #b8b8b8
@enduml

ok, I'm messing with it now, PlantUML is really punishing if you try and force the situation with a layout isn't it...

Yes indeed :-). And small changes in the connections lead to big changes in the layout. I more or less stopped trying to fight it.

Ok, I fixed some issues involving GraphicsScene and removed one component of ImageView that I didn't think was needed to reference

@startuml
' Made in PlantUml. You can try it out here: http://plantuml.com/plantuml
' Based on commit eb7a60fcf83cd4e7a41ae5955e57935e39928fbd


hide empty members
hide circles
hide stereotypes
top to bottom direction

skinparam class {
    BorderColor Black
    ArrowColor Black

    ' Using stereotypes to define the background colors
    BackgroundColor<<qt>> #e5f2da
    BackgroundColor<<pg>> #e5e5f4
}
skinparam shadowing false


'----------- Qt package ----------`


class QGraphicsGridLayout <<qt>>

class QGraphicsItem <<qt>>

class QGraphicsLayout <<qt>>

class QGraphicsLayoutItem <<qt>>

class QGraphicsObject <<qt>>

class QGraphicsScene <<qt>> { 
    items 
}

class QGraphicsWidget <<qt>>

class QGraphicsView <<qt>> {
    scene
}

class QObject <<qt>>

class QPaintDevice <<qt>>

class QWidget <<qt>>


'----------- PyQtGraph package ----------`


class GraphicsItem <<pg>> {
    scene
}

class GraphicsLayout <<pg>> {
    layout
}

class GraphicsScene <<pg>>

class GraphicsLayoutWidget <<pg>> {
    graphicsLayout
}

class GraphicsObject <<pg>>

class GraphicsView <<pg>> {
    scene
}

class GraphicsWidget <<pg>> 

class ImageItem <<pg>>

class ImageView <<pg>> {
    graphicsView
    imageItem
    view
}

class PlotCurveItem <<pg>>

class PlotDataItem <<pg>> {
    curve
    scatter
}

class PlotItem <<pg>> {
    layout
    vb
}

class PlotWidget <<pg>> {
    plotItem
}

class ScatterPlotItem <<pg>>

class ViewBox <<pg>>


'---------- Inheritance within Qt ----------'
QGraphicsItem <-- QGraphicsObject
QObject <-- QGraphicsObject
'QGraphicsItem -[hidden]> QObject
QGraphicsObject <-- QGraphicsWidget
QGraphicsLayoutItem <-- QGraphicsWidget
QGraphicsLayoutItem <-- QGraphicsLayout
QGraphicsLayout <-- QGraphicsGridLayout
QPaintDevice <-- QWidget
QObject <-- QWidget
QObject <-- QGraphicsScene
QWidget <-- QGraphicsView


'---------- Inheritance from Qt to PyQtGraph ----------'
QGraphicsWidget <-- GraphicsWidget
QGraphicsObject <-- GraphicsObject
QGraphicsView <-- GraphicsView
QWidget <--- ImageView
QGraphicsScene <-- GraphicsScene


'---------- Inheritance  within PyQtGraph ----------'
GraphicsItem <-- GraphicsObject
GraphicsItem <-- GraphicsWidget
GraphicsWidget <-- GraphicsLayout
GraphicsWidget <-- PlotItem
GraphicsWidget <-- ViewBox
GraphicsObject <-- ScatterPlotItem
GraphicsObject <-- PlotCurveItem
GraphicsObject <-- ImageItem
GraphicsObject <-- PlotDataItem
GraphicsView <-- PlotWidget
GraphicsView <-- GraphicsLayoutWidget


'---------- Aggregation ----------'

' Shorter arrow so at same height in the diagram
QGraphicsScene::items o-[norank]- QGraphicsItem                      #b8b8b8
QGraphicsView::scene o-[norank]- QGraphicsScene                      #b8b8b8
GraphicsView::scene o-[norank]- GraphicsScene                      #b8b8b8


' Longer (regular) arrows
PlotWidget::plotItem o-[norank]- PlotItem                           #b8b8b8
GraphicsItem::scene o-[norank]- GraphicsScene                       #b8b8b8
GraphicsLayoutWidget::graphicsLayout o-[norank]- GraphicsLayout     #b8b8b8
PlotDataItem::curve o-[norank]- PlotCurveItem                       #b8b8b8
PlotDataItem::scatter o-[norank]- ScatterPlotItem                   #b8b8b8
PlotItem::vb o-[norank]- ViewBox                                  #b8b8b8
PlotItem::layout o-[norank]- QGraphicsGridLayout                    #b8b8b8
GraphicsLayout::layout o-[norank]- QGraphicsGridLayout              #b8b8b8
ImageView::graphicsView o-[norank]- GraphicsView                    #b8b8b8
ImageView::imageItem o-[norank]- ImageItem                          #b8b8b8
ImageView::view o-[norank]- ViewBox                                 #b8b8b8
@enduml

tool-tips and hyperlinks work when exported as SVG! ...hopefully that means they'll stay working when embedded with sphinx. I'll have to test this with a branch on the main repository.

FYI, this is what I currently have

I'm debating if I want to add more objects (axis items come to mind).

@titusjan how "complete" should we try and get this diagram do you think?

@titusjan would you be ok with me pushing commits on this branch, attempting to embed this PlantUML code within the docs?

@j9ac9k. Sorry for not reacting sooner. I'm busy at work so it's hard to find the free time. I'm still looking in to this. Would you mind waiting a little bit longer? I will try to give a reply this evening.

No problem, due to other events us maintainers have been involved with, documentation is front and center on our mind

I offered to help because I think it might be a bit tricky to merge the plantuml code into readthedocs. Let me know if I can help.

Hi @titusjan

I'd like to get this PR merged before much longer; I'm likely going to spend some time trying to integrate the construction of the chart that you did into our CI pipeline (or see if it's feasible at least).

Sorry we let this get stale!

Sorry we let this get stale!

No problem. I didn't follow up either.

I notice that we never made a final decision between the last two options. I see that you prefer the compact layout. I assume you mean this one. That one has my preference as well, so let's go with that.

I'm curious to the final result.

I do prefer the one you linked, but my feelings between the two are close enough, that I would let the author have the discretion of which one they want to use.

I loaded the graph inside yEd; everything looks good there 👍🏻

My main gripe/sticking point is that I'm not seeing an obvious way to generate the SVG as part of the docs build process, so we can have it in the CI. Ideally we would be able to have just the code, and not have to worry about the SVG being committed to the repo. I'll try and dig around and see if there is a way I can build/export the SVG from that file via an automated process outside of the desktop app.

I should also note, that while that is my main sticking point, I no longer feel that not being able to export the image in the CI pipeline is a deal breaker. This chart has a sufficient utility that I would be willing to handle some inconvenience.

What should likely also happen is a reference to this diagram, and how to update it should be made to CONTRIBUTING.md

Ok, we can't use this as part of an automated build process:

From their license agreement:

The Licensee is granted a non-exclusive and non-transferable right to install one copy of the Software and use it as an application. The Software may not be used as part of an automated process. The Licensee may not reverse engineer, disassemble, decompile, or unjar the Software, or otherwise attempt to derive the source code of the Software.

I started tinkering with mermaid; and I'll say right off the bat, the output doesn't look anywhere near as good as what you have created using yEd; that said, I think we can do away w/ the light arrows and just specify the types in the entries.

There is something nice about the code being just that simple tho... this size diagram might just be too big for mermaid to render nicely.

classDiagram
    QPaintDevice <|-- QWidget
    QObject <|-- QWidget
    QObject <|-- QGraphicsScene
    QObject <|-- QGraphicsObject

    QWidget <|-- ImageView
    QWidget <|-- QGraphicsView

    QGraphicsItem <|-- QGraphicsObject

    QGraphicsView <|-- GraphicsView

    QGraphicsScene <|-- GraphicsScene

    GraphicsView <|-- GraphicsLayoutWidget

    GraphicsView <|-- PlotWidget

    GraphicsItem <|-- GraphicsObject
    GraphicsItem <|-- GraphicsWidget
    QGraphicsObject <|-- GraphicsObject
    QGraphicsObject <|-- QGraphicsWidget
    QGraphicsLayoutItem <|-- QGraphicsWidget
    QGraphicsLayoutItem <|-- QGraphicsLayout

    GraphicsObject <|-- ImageItem
    GraphicsObject <|-- ScatterPlotItem
    GraphicsObject <|-- PlotDataItem
    GraphicsObject <|-- PlotCurveItem

    QGraphicsWidget <|-- GraphicsWidget
    QGraphicsGridLayout <|-- QGraphicsLayout

    GraphicsWidget <|-- ViewBox
    GraphicsWidget <|-- PlotItem
    GraphicsWidget <|-- GraphicsLayout

    class GraphicsLayout{
        layout: QGraphicsGridLayout
    }

    class PlotItem{
        items: List[GraphicsItem]
        layout: QGraphicsGridLayout
        vb: ViewBox
        addItem(GraphicsItem)
    }

    class ViewBox{
        addItem(GraphicsItem)
    }

    class PlotDataItem{
        curve: PlotCurveItem
        scatter: PlotScatterItem
    }

    class PlotWidget{
        plotItem: PlotItem
    }


    class QGraphicsView{
        scene()
    }
    class ImageView{
        graphicsView: GraphicsView
        imageItem: ImageItem
        view: ViewBox
    }

    class GraphicsLayoutWidget{
        graphicsLayout: GraphicsLayout
    }

The YEd license says the software can't be used as part as of an automated build process but I understand this as that it can't be executed automatically. I think it is perfectly legal to just include the generated SVG in the repo.

Ideally we would be able to have just the code, and not have to worry about the SVG being committed to the repo.

You will always have to make a selection of classes and tweak the generated output. Even with PlantUml there was a large config file that needs to be maintained. IMO there's no difference between maintaining the config file or directly maintaining a diagram. Or am I missing something?

I think we can do away w/ the light arrows and just specify the types in the entries.

We could also do both :-)

You will always have to make a selection of classes and tweak the generated output. Even with PlantUml there was a large config file that needs to be maintained. IMO there's no difference between maintaining the config file or directly maintaining a diagram. Or am I missing something?

The issue is that we can't "generate" the entirety of the documentation with a make command as we (more or less) currently do. There are images like that in the docs right now, so it's not like we're introducing something new with this PR (although some of those images could easily be migrated to PlantUML/Mermaid/GraphiViz generated images, but that's for another topic).

As you correctly point out, this is likely not as big of a deal as I'm making it out to be :)

Again, don't think this is a deal breaker, I'm just trying to make sure there isn't a platform that would work better for us. Since this PR was opened, mermaid has gotten much more support (renders in github markdow for example).

Assuming we stay w/ yEd (which I have yet to be convinced of another diagram platform that is more suitable); a blurb to CONTRIBUTING.md should be added about this image/file and how it was created and the application needed to edit it. Lastly, the image should go live here: https://github.com/pyqtgraph/pyqtgraph/tree/master/doc/source/images

I'm open to suggestions on where in the docs the image should live.

Hi @titusjan if you have the opportunity, could you update the graph with the condensed version; from that point, I can figure out where to integrate into the docs and such.

I think after this is merged, we will release 0.13.0 👍🏻

Sorry for not responding earlier. I was on a short vacation and didn't read my email.

I reverted back to the condensed version and moved it to the doc/source/images directory.

I'm open to suggestions on where in the docs the image should live.

Perhaps a separate page in the API reference would be the best. It can contain a small paragraph explaining the image. I think there should be a hyperlink to the diagram somehwere in the Plotting in pyqtgraph as well.

Sorry for not responding earlier. I was on a short vacation and didn't read my email.

I reverted back to the condensed version and moved it to the doc/source/images directory.

I'm open to suggestions on where in the docs the image should live.

Perhaps a separate page in the API reference would be the best. It can contain a small paragraph explaining the image. I think there should be a hyperlink to the diagram somewhere in the Plotting in pyqtgraph as well.

My apologies for you coming back from vacation to a bunch of notifications from me, hope you had a good vacation!

I should add, that @ixjlyons and I are going to do a massive restructure of the docs in the not-too-distant future; so it will likely get moved around when that happens.

There is an "Organizations of Plotting Classes" section in Plotting in pyqtgraph, that I think would make a natural home for this chart and an explanation, but I am not opposed to having its own page either.

@ixjlyons do you have an opinion on this?

I view the "Plotting in pyqtgraph" page as introductory/tutorial material, and putting the diagram there might be a little overwhelming to the target reader. I like the idea of giving it a separate page, probably under API reference, and linking to it.

We're also lacking internals docs and this would be a great reference there too, once there's some expository content. I've always been tempted to put a placeholder there.

Perhaps a separate page in the API reference would be the best. It can contain a small paragraph explaining the image. I think there should be a hyperlink to the diagram somehwere in the Plotting in pyqtgraph as well.

Would you like me to create this and add to this branch or would you want to draft something up?

Would you like me to create this and add to this branch or would you want to draft something up?

I made a draft version. Let me know what you think or feel free to make modifications.

Would you like me to create this and add to this branch or would you want to draft something up?

I made a draft version. Let me know what you think or feel free to make modifications.

Just read it over, the contents look good to me. The only thing preventing the merge is the merge-conflict in apireference.rst.

I merged the upstream master branch into my issue-848 branch and resolved the conflict.

Read the docs now complaining because:

/home/docs/checkouts/readthedocs.org/user_builds/pyqtgraph/checkouts/1631/doc/source/apireference.rst:6: WARNING: toctree contains reference to nonexisting document 'graphicswindow'

EDIT: I think that line was removed from a previous commit; and probably got brought back in there as part of the merge. Anyway just remove that line 👍🏻

Yes it was a reference to the "Deprecated Window Classes" page, which seems to have been removed from the documentation.

I removed the line.

RTD passes, when CI is green, I'm going to merge.

Thanks, @titusjan for your work on this, and your extraordinary patience with us. Should you submit another PR, I'll do the best I can to make sure it doesn't take 1.5 years before merging!

EDIT: now I'm all out of excuses for delaying the release of 0.13.0 ... suppose I should get to work on the changelog tonight

Thanks for your support and congrats on the upcoming release. Your work is greatly appreciated @j9ac9k

@titusjan do you have a twitter handle I can tag you with relating to this PR? I'd like to post to twitter and I'd like to give you credit.

No I don't have twitter. The titusjan account on twitter was already taken by someone else unfortunately.

Thanks for wanting to giving me credit though.

Hi @titusjan

Slight follow-up here, do you know if yEd allows for storing multiple color palettes in a file, allowing one to quickly toggle between the two? The motivation here is to generate a dark mode friendly svg and a light mode friendly one... without having two separate .graphml files.

I couldn't find any functionality like that, unfortunately.

I couldn't find any functionality like that, unfortunately.

Thanks for checking!