<table>
  <tr>
    <td><a href="#blue-marble">Blue Marble</a></td>
    <td valign="top" rowspan="99"><a href="https://discord.gg/tpeBPy46hf"><img alt="Discord Banner" src="https://discord.com/api/guilds/796124137042608188/widget.png?style=banner4"></a></td>
  </tr>
  <tr>
    <td>&emsp;<a href="#quick-guide">Quick Guide</a></td>
  </tr>
  <tr>
    <td>&emsp;<a href="#overview">Overview</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#installation-instructions">Installation Instructions</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#script-settings">Script Settings</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#template-settings">Template Settings</a></td>
  </tr>
  <tr>
    <td>&emsp;<a href="#how-versioning-works">How Versioning Works</a></td>
  </tr>
  <tr>
    <td>&emsp;<a href="#licenses">Licenses</a></td>
  </tr>
  <tr>
    <td>&emsp;<a href="#faq">FAQ</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#is-blue-marble-malware">Is Blue Marble malware?</a></td>
  </tr>
    <tr>
    <td>&emsp;&emsp;<a href="#why-are-some-pixels-not-showing-on-the-overlay">Why are some pixels not showing on the overlay?</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#how-can-blue-marble-place-pixels-for-me">How can Blue Marble place pixels for me?</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#how-do-i-hide-the-overlay">How do I hide the overlay?</a></td>
  </tr>
  <tr>
    <td>&emsp;&emsp;<a href="#why-do-game-notifications-appear-on-top-of-the-overlay">Why do game notifications appear on top of the overlay?</a></td>
  </tr>
</table>

<h1>Blue Marble</h1>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Latest Version" src="https://img.shields.io/badge/Latest_Version-0.90.0-lightblue?style=flat"></a>
<a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer"><img alt="Latest Release" src="https://img.shields.io/github/v/release/SwingTheVine/Wplace-BlueMarble?sort=semver&style=flat&label=Latest%20Release&color=blue"></a>
<a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/LICENSE.txt" target="_blank" rel="noopener noreferrer"><img alt="Software License: MPL-2.0" src="https://img.shields.io/badge/Software_License-MPL--2.0-slateblue?style=flat"></a>
<a href="https://discord.gg/tpeBPy46hf" target="_blank" rel="noopener noreferrer"><img alt="Contact Me" src="https://img.shields.io/badge/Contact_Me-gray?style=flat&logo=Discord&logoColor=white&logoSize=auto&labelColor=cornflowerblue"></a>
<a href="https://bluemarble.lol/" target="_blank" rel="noopener noreferrer"><img alt="Blue Marble Website" src="https://img.shields.io/badge/Blue_Marble_Website-crqch-blue?style=flat&logo=globe&logoColor=white"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="WakaTime" src="https://img.shields.io/badge/Coding_Time-212hrs_17mins-blue?style=flat&logo=wakatime&logoColor=black&logoSize=auto&labelColor=white"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Patches" src="https://img.shields.io/badge/Total_Patches-1115-black?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Lines of Code" src="https://img.shields.io/badge/Lines_Of_Code-5908-blue?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Total Comments" src="https://img.shields.io/badge/Lines_Of_Comments-5160-blue?style=flat"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Compression" src="https://img.shields.io/badge/Compression-73.34%25-blue"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Repo Size" src="https://img.shields.io/github/repo-size/SwingTheVine/Wplace-BlueMarble"></a>
<a href="https://hits.sh/github.com/SwingTheVine/Wplace-BlueMarble/" target="_blank" rel="noopener"><img alt="Views" src="https://hits.sh/github.com/SwingTheVine/Wplace-BlueMarble.svg?label=Views&extraCount=664359&color=ffffff"/></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Downloads" src="https://img.shields.io/github/downloads/SwingTheVine/Wplace-BlueMarble/total.svg"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Build" src="https://github.com/SwingTheVine/Wplace-BlueMarble/actions/workflows/build.yml/badge.svg"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="Pages" src="https://github.com/SwingTheVine/Wplace-BlueMarble/actions/workflows/pages/pages-build-deployment/badge.svg?branch=wiki"></a>
<a href="" target="_blank" rel="noopener noreferrer"><img alt="CodeQL" src="https://github.com/SwingTheVine/Wplace-BlueMarble/actions/workflows/github-code-scanning/codeql/badge.svg"></a>
<a href="https://www.bestpractices.dev/projects/11067" target="_blank" rel="noopener noreferrer"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/11067/badge"></a>

<h2>Quick Guide</h2>
<p>
  Press the arrows to reveal the option you want.
  <details>
    <summary>
      <b>I want to download Blue Marble.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="#installation-instructions">Click here</a> to view the installation instructions.
  </details>
  <details>
    <summary>
      <b>I want to ask questions about Blue Marble.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://discord.gg/tpeBPy46hf" target="_blank" rel="noopener noreferrer">Click here</a> for the Discord server invite to the Blue Marble support server.
    <br>
    <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/discussions/categories/q-a">Click here</a> for the GitHub help & question page for Blue Marble.
  </details>
  <details>
    <summary>
      <b>I want to report a bug.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/issues/new/choose">Click here</a> to report a bug, then choose the "Bug Report" option.
  </details>
  <details>
    <summary>
      <b>I want to suggest a feature.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/issues/new/choose">Click here</a> to suggest a feature, then choose the Feature Request" option.
  </details>
  <details>
    <summary>
      <b>I want to contribute.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/CONTRIBUTING.md">Click here</a> to read the contributing guidelines.
  </details>
  <details>
    <summary>
      <b>I want to report a vulnerability.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/security">Click here</a> to submit a vulnerability report.
  </details>
  <details>
    <summary>
      <b>I want to visit the website.</b> <sup>(Click to Expand)</sup>
    </summary>
    <a href="https://bluemarble.lol/" target="_blank" rel="noopener noreferrer">Click here</a> to visit the official Blue Marble website.
  </details>
</p>

<h2>Overview</h2>
<p>
  Welcome to Blue Marble! Blue Marble is a userscript for the website <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a>. The purpose of Blue Marble is to allow you to take an image, and layer it onto the canvas! That way, you can easily trace the image of your art, without having to look back and forth between multiple tabs/monitors. In addition, Blue Marble supports some neat extra features such as: 
  <ul>
    <li>Displaying the number of pixels you need to level up</li>
    <li>Displaying a simple coordinate system (tile coordinats & pixel coordinates)</li>
    <li>Allowing you to move the color palette to the top of the screen when placing pixels</li>
    <li>Allowing you to use the eyedropper on the template image, provided the colors are correct</li>
    <li>Minimizing or maximizing the menu to switch between compact and full views</li>
    <li>Filtering overlay colors by toggling individual template colors or using global enable/disable buttons</li>
    <li>...and more!</li>
  </ul>
  If you like this userscript, please ⭐ the repository! For more information and updates, visit the <a href="https://bluemarble.lol/" target="_blank" rel="noopener noreferrer">Blue Marble website</a>. If you wish to contribute to Blue Marble, check out the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">CONTRIBUTING.md</a> file in <code>docs/</code>.

  <img alt="Showcase image of Blue Marble template" src="./assets/Showcase1.png">

  <h3>Installation Instructions</h3>
  <a href="" target="_blank" rel="noopener noreferrer"><img alt="Supported Browsers" src="https://img.shields.io/badge/Supported%20Browsers-Chrome%20%7C%20Firefox%2A%20%7C%20Safari%20%7C%20Edge%20%7C%20Brave-orange?style=flat"></a>
  <a href="" target="_blank" rel="noopener noreferrer"><img alt="Unupported Browsers" src="https://img.shields.io/badge/Unsupported%20Browsers-Firefox%2A%20%7C%20Kiwi%20%7C%20Vivaldi-red?style=flat"></a>
  <p>
    Blue Marble has been verified to work on mobile devices. Blue Marble was designed on Chrome, but Blue Marble might work on "unsupported" browsers not listed above. Some versions/forks of Firefox work. Some versions/forks of Firefox do not work.
    <br>
    Installation instructions for Blue Marble are below. Click the arrows to expand the instructions you want to see. Blue text is a link.
    <details>
      <summary>
        <b>Install Chrome</b> <sup>(Click to expand)</sup>
      </summary>
      <a href="https://www.youtube.com/watch?v=gg5oiJcftEc" target="_blank" rel="noopener noreferrer"><img alt="Install Tutorial" src="https://img.shields.io/badge/Install_Tutorial-gray?style=flat&logo=YouTube&logoColor=white&logoSize=auto&labelColor=darkred"></a>
      <ol>
        <li>Install the <a href="https://chromewebstore.google.com/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo" target="_blank" rel="noopener noreferrer">TamperMonkey</a> extension for Chrome.
        <br>
        <img alt="Click the 'Add extension' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall1.png"></li>
        <li>Right-click the extension.
        <br>
        <img alt="Enter the 'Manage Extension' menu" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall2.png"></li>
        <li>Left-click "Manage Extension."</li>
        <li>Enable "Developer Mode."
        <br>
        <img alt="Enable 'Developer Mode' and 'Allow user scripts'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall3.png"></li>
        <li>Enable "Allow user scripts."</li>
        <li><strong>One-click install:</strong> Click this link to Install Blue Marble directly: <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases/download/pre/BlueMarble.user.js" target="_blank" rel="noopener noreferrer"><strong>Install Blue Marble</strong></a>
        <br>
        TamperMonkey will automatically detect the userscript and prompt you to Install it.</li>
        <li>Refresh the <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a> webpage.</li>
      </ol>
    </details>
    <details>
      <summary>
        <b>Install on Microsoft Edge</b> <sup>(Click to expand)</sup>
      </summary>
      <ol>
        <li>Install the <a href="https://microsoftedge.microsoft.com/addons/detail/iikmkjmpaadaobahmlepeloendndfphd" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Microsoft Edge.
        <br>
        <img alt="Click the 'Get' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall1.png"></li>
        <li>Right-click the extension.
        <br>
        <img alt="Enter the 'Manage Extension' menu" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall2.png"></li>
        <li>Left-click "Manage Extension."</li>
        <li>Enable "Developer Mode."
        <br>
        <img alt="Enable 'Developer Mode'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall3.png"></li>
        <li>Download the <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases" target="_blank" rel="noopener noreferrer">BlueMarble.user.js</a> file in the "Assets" of the latest release.</li>
        <li>Open the TamperMonkey Dashboard.
        <br>
        <img alt="Enter the TamperMonkey 'Dashboard'" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerEdgeInstall4.png"></li>
        <li>Drag the <code>BlueMarble.user.js</code> file inside the dashboard of TamperMonkey.
        <br>
        <img alt="Drag the userscript into the dashboard" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall5.png"></li>
        <li>Click the "Install" button to Install Blue Marble.
        <br>
        <img alt="Click the 'Install' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall6.png"></li>
        <li>Enable Blue Marble inside the TamperMonkey dashboard.
        <br>
        <img alt="Enable Blue Marble" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerChromeInstall7.png"></li>
        <li>Refresh the <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a> webpage.</li>
      </ol>
    </details>
    <details>
      <summary>
        <b>Install on Firefox</b> <sup>(Click to expand)</sup>
      </summary>
      <ol>
        <li>Install the <a href="https://addons.mozilla.org/en-US/firefox/addon/tampermonkey/" target="_blank" rel="noopener noreferrer">TamperMonkey</a> plugin for Firefox.
        <br>
        <img alt="Click the 'Add to Firefox' button" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/ComputerFirefoxInstall1.png"></li>
        <li><strong>One-click install:</strong> Click this link to Install Blue Marble directly: <a href="https://github.com/SwingTheVine/Wplace-BlueMarble/releases/download/pre/BlueMarble.user.js" target="_blank" rel="noopener noreferrer"><strong>Install Blue Marble</strong></a>
        <br>
        TamperMonkey will automatically detect the userscript and prompt you to install it.</li>
        <li>Refresh the <a href="https://wplace.live/" target="_blank" rel="noopener noreferrer">wplace.live</a> webpage.</li>
      </ol>
    </details>
  </p>

  <h3>Template Instructions</h3>
  <p>
    Blue Marble will display your template as the same size. If your image is 500 pixels tall and 300 pixels wide, the template will be 500 pixels tall and 300 pixels wide. Here is the instructions to display a template image on the canvas:
    <ol>
      <li>Find the pixel of the top left corner. Fill in <code>Tl X</code>, <code>Tl Y</code>, <code>Px X</code>, and <code>Px Y</code> with the coordinates. You can use the "Pin" icon to auto-fill the coordinates after clicking the pixel.
      <br>
      <img alt="Find template coordinates" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/TemplateCoordinates1.png"></li>
      <li>Upload a PNG or WEBP image.</li>
      <li>Click the "Create" button.</li>
      <li>If your template still does not show, try clicking the "Enable" button.</li>
    </ol>
  </p>

  <h3>Script Settings</h3>
  <p>
    There are many settings available for the Blue Marble userscript! Through these settings, you can control how the script behaves.
  </p>

  <h3>Template Settings</h3>
  <p>
    <h4>Transparent Pixels</h4>
    <p>
      Templates for Blue Marble work slightly different from normal. Since there is a "Transparent" color, and transparent pixels in templates are typically ignored, your template should have a custom color to signify "Transparent" colored pixels.
      <ul>
        <li>If you want a specific pixel to be any color, it should be transparent in your template.</li>
        <li>If you want a specific pixel to be the "Transparent" color on the Wplace palette, it should have the <code>#deface</code> hex color.</li>
      </ul>
    </p>
    <h4>Coordinates</h4>
    <p>
      <h5>Tile Coordinates</h5>
      <p>
        The coordinate system for wplace.live is unique. Instead of all pixels having a global coordinate number (x, y), the coordinate number is relative to the tile. This means you need to know the tile number and the coordinate number to do anything. In Blue Marble, the tile coordinates and the pixel coordinates are displayed when you click on a pixel. These are the coordinates you should use for aligning a template.
        <br>
        <img alt="Where to find tile coordinates" src="https://github.com/SwingTheVine/Wplace-BlueMarble/blob/main/docs/assets/TemplateCoordinatesDisplay.png">
      </p>
      <h5>Template Coordinates</h5>
      <p>
        The template is aligned from the top left corner of the template. You can auto-fill this position using the "pin" (also called "waypoint") icon next to the coordinate input boxes.
      </p>
    </p>
  </p>
</p>

<h2>How Versioning Works</h2>
<p>
  The versioning system for this userscript follows the <a href="https://semver.org/" target="_blank" rel="noopener noreferrer">Semantic Versioning rules</a>. As such, it is formatted in an <code>X.Y.Z</code> format where:
  <ul>
    <li>X is the major version. This is incremented when a non-backward compatible update is pushed. This is for new features that break previous versions of the userscript. Additionally, if wplace.live breaks the userscript, this will be incremented.</li>
    <li>Y is the minor version. This is incremented whenever I push to GitHub. This is for stable bug-fixes and new (non-breaking) features.</li>
    <li>Z is the patch version. This is incremented whenever I launch a development version of the userscript to test a patch. This is for unstable bug-fixes/features.</li>
  </ul>
</p>

<h2>Licenses</h2>
<p>
  (Below, all mentions of the "userscript" refer to the "Blue Marble" userscript made by SwingTheVine) <br>
  Most of this userscript is licensed under the <code>Mozilla Public License Version 2.0</code> (MPL-2.0). All software, code, and libraries in this repository are licensed under the MPL-2.0 license. However, the "Blue Marble" image in this userscript is owned by NASA and is licensed under the <code>Creative Commons 0 1.0 Universal</code> (CC0 1.0) license.
</p>

<h2>FAQ</h2>
<p>
  <h3>Is Blue Marble malware?</h3>
  <p><b>A:</b> Blue Marble does not contain malicious code. The Blue Marble code can be found in the <code>src/</code> folder. If you worry about Blue Marble being malware, you can read the code, then bundle it yourself using the tools in <code>build/</code>.

  <h3>Why are some pixels not showing on the overlay?</h3>
  <p><b>A:</b> This usually happens if the template image is not converted to the Wplace color palette. You should convert your template using a color converter for Wplace, or manually adjust the template image to match the Wplace color palette. Also check that no pixels are disabled in the filter settings of the Blue Marble menu.</p>

  <h3>How can Blue Marble place pixels for me?</h3>
  <p><b>A:</b> Unfortunately, Blue Marble will not support the automatic placement of pixels without user interaction because it is not allowed by Wplace.

  <h3>How do I hide the overlay?</h3>
  <p><b>A:</b> You can temporarily hide the overlay by clicking the "Disable" button in the Blue Marble menu.  
  <br>
  If you want to completely remove both the overlay and the Blue Marble menu, turn off the userscript in Tampermonkey and refresh the page.</p>

  <h3>How do I tell colors apart?</h3>
  <p><b>A:</b> Find the color in the color filter list. Click the checkbox to turn the color on or off. If you want to work on only one color at a time (recommended), then click "Disable All" in the color filter. Finally, enable the checkbox next to the color you want to place. This way, only one color on your template will appear at a time.</p>

  <h3>How do get the color of a pixel?</h3>
  <p><b>A:</b> Use the eyedropper in the palette menu of wplace. If your template colors match the wplace palette, you can select the template pixel dot to get the template's color for that pixel.</p>

  <h3>Why do game notifications appear on top of the overlay?</h3>
  <p><b>A:</b> Game notifications only appear when they need immediate attention. Therefore, they have priority over the overlay (which typically needs no attention).</p>
</p>
