Skip to content

Allow image markers to plot agents#2799

Merged
tpike3 merged 3 commits intomesa:mainfrom
UniK-INES:feature_vis_imagemarkers
Jun 3, 2025
Merged

Allow image markers to plot agents#2799
tpike3 merged 3 commits intomesa:mainfrom
UniK-INES:feature_vis_imagemarkers

Conversation

@Holzhauer
Copy link
Copy Markdown
Contributor

Summary

Enable images as markers for plotting agents and apply the feature to the Schelling model example

Motive

In may cases images are a preferable means to distinguish agents in the visualisation.

Implementation

In _scatter() it is checked whether the value for marker contains a valid file resource. If so, an image is created and zoomed (_get_zoom_factor) to the size of a grid cell (it is required to postpone calls of _scatter() in draw* methods because x and y limits need to be set earlier). An AnnotationBbox is used to display the image on the grid.

Usage Examples

The Schelling model was updated to apply image markers (and AgentPortrayalStyle) depending on agent type and state:

Schelling_before
Schelling_after

(Agents' step method was changed and assign_state introduced. Now the initial number of happy agents is shown correctly in the figure.)

Additional Notes

It seems that figure size is adjusted in solara after its initilisation. That's why CORRECTION_FACTOR_MARKER_ZOOM = 0.6 was introduced. There might be a better approach...

@github-actions
Copy link
Copy Markdown

Performance benchmarks:

Model Size Init time [95% CI] Run time [95% CI]
BoltzmannWealth small 🔴 +4.7% [+4.0%, +5.3%] 🔵 -0.2% [-0.4%, +0.0%]
BoltzmannWealth large 🔵 -0.5% [-1.2%, +0.1%] 🔵 +0.1% [-2.8%, +3.0%]
Schelling small 🔴 +40.6% [+40.3%, +40.8%] 🔵 -2.2% [-2.4%, -1.9%]
Schelling large 🔴 +119.6% [+117.7%, +122.0%] 🟢 -13.5% [-14.6%, -12.6%]
WolfSheep small 🔵 +0.6% [+0.2%, +1.1%] 🔵 -0.1% [-0.3%, +0.2%]
WolfSheep large 🔵 +0.2% [-0.4%, +0.9%] 🔵 -0.0% [-1.1%, +1.0%]
BoidFlockers small 🔵 -0.3% [-0.9%, +0.4%] 🔵 -1.4% [-1.7%, -1.2%]
BoidFlockers large 🔵 -1.8% [-2.1%, -1.4%] 🔵 -2.3% [-2.6%, -1.9%]

@tpike3
Copy link
Copy Markdown
Member

tpike3 commented May 31, 2025

Thanks @Holzhauer! As we have a Google Summer of Code contributor working the visualization front end right now so I am going to ask him to take a look as well. But I have no issues with this and am very glad you addressed the Solara initialization issue!

Copy link
Copy Markdown
Member

@tpike3 tpike3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Sahil-Chhoker
Copy link
Copy Markdown
Collaborator

I really like this PR, but as you said there can be a better approach for the size. size or more accurately "s" in the dict arguments contains the sizes of every agents in a list, you can apply similar logic of that of z_order to size as well and use that for zooming.

Also pass the z_order to the AnnonationBbox.

@tpike3
Copy link
Copy Markdown
Member

tpike3 commented Jun 1, 2025

@Holzhauer I am good with merging this as is, but could you please resolve the conflicts.

If you want to add the **kwargs argument so users can pass in the the number kwargs available that should address @Sahil-Chhoker points.

Thanks again!

Holzhauer added 3 commits June 2, 2025 19:46
- add image marker
- postpone call of _scatter() in draw* method because limits need to be
set earlier
- add _get_zoom_factor to achieve correct image size
- add agent attribute 'happy'
- add emoticon PNGs
- correct Readme.md
- adapt agents step method and introduce assign_state
- setup use of image markers in app.py
- call agent methods in model.py
- refactor masking for markers and images
- add agent level transparency for image markers
- add agent level zorder for image markers
- support agent level image sizes
- add transparency to schelling model agent images
@Holzhauer Holzhauer force-pushed the feature_vis_imagemarkers branch from f433141 to c6a0e70 Compare June 2, 2025 17:58
@Holzhauer
Copy link
Copy Markdown
Contributor Author

Thanks for your comments and suggestions. I refactored the masking quite a bit and added agent level control for transparency, zorder, and size for image markers. Also **kwargs was added to AnnotationBbox. I added transparency to Schelling model agent images and changed the example a bit:
SchellingAlphaZorder

The only thing I'm not totally satisfied with is the size parameter. Its default is 50, but for image sizes to fit to the grid cell size by default a default factor value of 1 makes more sense. However, I decided to divide the size value by 50 and stick to the legacy default value.

Copy link
Copy Markdown
Collaborator

@Sahil-Chhoker Sahil-Chhoker left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great—everything is concise and clean.
Just one small suggestion: we probably don't need two constants to adjust the size. Using just CORRECTION_FACTOR_MARKER_ZOOM and setting it to 0.01 should do the job well.
That said, it's non-blocking and @tpike3, this PR is good to merge.

@tpike3
Copy link
Copy Markdown
Member

tpike3 commented Jun 3, 2025

Thanks @Holzhauer!

@tpike3 tpike3 merged commit eddcc85 into mesa:main Jun 3, 2025
11 of 12 checks passed
@tpike3 tpike3 added visualisation enhancement Release notes label labels Jun 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement Release notes label visualisation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants